Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

6.7 KB
Raw Blame
import { type DriveContext, EffectFailure, type EffectError, type HostTool, hostToolIO, type ReplayPolicy } from 'harness-world';

/**
 * The tool bridge: `HostTool`s as a harness-neutral list a port maps onto its
 * harness's own tool mechanism (Claude Code's in-process MCP server, Codex's
 * dynamic tools, OpenCode's plugin tools).
 *
 * Each call runs the kernel's effect sandwich keyed by the harness's own
 * tool-call id, `tool:<callId>`, step name `tool.<name>`, with the tool's
 * replay policy: a call the log already finished returns its recorded
 * result without running (a resumed harness that re-issues a call gets the
 * same answer), a `replay: 'never'` call interrupted by a crash comes back
 * as an interrupted result, never a second run. With the harness's built-in
 * tools turned off, these are its only tools, so every side effect it can
 * cause has an intent in the log before it runs.
 */

/** What a call returns to the harness. */
export interface ToolResult {
  text: string;
  /** The call failed (its recorded error) or was interrupted. */
  isError: boolean;
  /** The call's intent was committed and its outcome lost (see `EffectError.interrupted`). */
  interrupted?: boolean;
}

/** One tool, harness-neutral. */
export interface BridgedTool {
  name: string;
  description: string;
  /** JSON Schema for the input (`zodShapeFromJsonSchema` turns it into zod for SDKs that want that). */
  inputSchema: Record<string, unknown>;
  replay: ReplayPolicy;
  /**
   * Run the call. `callId` is the harness's id for this call (Claude Code's
   * tool_use id, Codex's call_id, ...); it must be stable across a resume of
   * the harness's session, since it is the memo key. `signal` is the
   * harness's own cancellation, if it has one; the drive's is always applied.
   */
  call(args: unknown, callId: string, signal?: AbortSignal): Promise<ToolResult>;
}

export interface ToolBridgeOptions {
  /**
   * Runs before a `replay: 'never'` call that the log has not finished:
   * the place for `journal.flush()`, so the harness's record of the call is
   * in the log before the call's intent is.
   */
  beforeNever?: (call: { name: string; callId: string; args: unknown }) => Promise<void>;
  /** Serialize calls (a per-drive mutex). Default true: concurrent effects in one drive are not exercised yet. */
  serial?: boolean;
  /** Publish `tool_start` / `tool_end` on `ctx.live` for calls that run. Default true. */
  live?: boolean;
  /** How much of a partial output an interrupted result quotes. Default 2000 characters. */
  partialChars?: number;
}

export interface ToolBridge {
  tools: BridgedTool[];
  get(name: string): BridgedTool | undefined;
  /** Run a call by tool name. An unknown name is an error result, not a throw. */
  call(name: string, args: unknown, callId: string, signal?: AbortSignal): Promise<ToolResult>;
}

/** A promise-chain mutex. */
export class Mutex {
  private tail: Promise<unknown> = Promise.resolve();
  run<T>(fn: () => Promise<T>): Promise<T> {
    const run = this.tail.then(fn, fn);
    this.tail = run.catch(() => {});
    return run;
  }
}

/** The memo key of a tool call. */
export const toolKey = (callId: string) => `tool:${callId}`;

/**
 * Build the bridge for one drive. The calls' effects are this drive's: build
 * a new bridge per `drive(ctx)`.
 *
 * A call whose effect throws anything but a committed failure (the drive was
 * preempted, a recovery resolved the call first, the World refused a write)
 * halts the drive (`ctx.halt`) and rethrows: the harness must not be handed
 * a result the log does not have, and its runtime must stop.
 */
export function toolBridge(ctx: DriveContext, tools: HostTool[], options: ToolBridgeOptions = {}): ToolBridge {
  const mutex = new Mutex();
  const serial = options.serial ?? true;
  const live = options.live ?? true;
  const bridged = tools.map((tool): BridgedTool => {
    const run = async (args: unknown, callId: string, signal?: AbortSignal): Promise<ToolResult> => {
      if (!callId) throw new TypeError(`harness-world-process: a call to ${tool.name} has no call id; derive a stable one`);
      const key = toolKey(callId);
      const fresh = !ctx.isMemoized(key);
      if (fresh && tool.replay === 'never') await options.beforeNever?.({ name: tool.name, callId, args });
      if (fresh && live) ctx.live({ type: 'tool_start', name: tool.name, args, callId });
      try {
        const text = await ctx.effect(
          key,
          {
            name: `tool.${tool.name}`,
            replay: tool.replay,
            input: args,
            ...(tool.requires ? { requires: tool.requires } : {}),
            ...(tool.needs?.length ? { needs: tool.needs } : {}),
          },
          (io) => tool.execute(args, hostToolIO(io, ctx, { signal: signal ? AbortSignal.any([signal, io.signal]) : io.signal }))
        );
        if (fresh && live) ctx.live({ type: 'tool_end', name: tool.name, callId, result: text });
        return { text: String(text), isError: false };
      } catch (err) {
        if (err instanceof EffectFailure) {
          if (fresh && live) ctx.live({ type: 'tool_end', name: tool.name, callId, isError: true });
          return { text: failureText(err.error, options.partialChars), isError: true, ...(err.error.interrupted ? { interrupted: true } : {}) };
        }
        ctx.halt?.(err);
        throw err;
      }
    };
    return {
      name: tool.name,
      description: tool.description,
      inputSchema: tool.inputSchema as Record<string, unknown>,
      replay: tool.replay,
      call: (args, callId, signal) => (serial ? mutex.run(() => run(args, callId, signal)) : run(args, callId, signal)),
    };
  });
  const byName = new Map(bridged.map((t) => [t.name, t]));
  return {
    tools: bridged,
    get: (name) => byName.get(name),
    call: async (name, args, callId, signal) => {
      const tool = byName.get(name);
      if (!tool) return { text: `unknown tool: ${name}`, isError: true };
      return tool.call(args, callId, signal);
    },
  };
}

/**
 * The text a harness gets for a failed call: the error, or for an
 * interrupted one, what the kernel recorded ("may or may not have taken
 * effect") plus the last progress it reported.
 */
export function failureText(error: EffectError, partialChars = 2000): string {
  const message = error.message || 'the tool failed with no message';
  if (!error.interrupted) return message;
  const last = error.partial?.at(-1);
  if (last === undefined) return message;
  const text = typeof last === 'string' ? last : JSON.stringify(last);
  return `${message}\nPartial output before the interruption:\n${clip(text, partialChars)}`;
}

/** At most `max` characters, with a marker when cut. */
export function clip(text: string, max: number): string {
  return text.length <= max ? text : `${text.slice(0, max)}… [${text.length - max} more characters]`;
}