Skip to content

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

8.3 KB
Raw Blame
import type { Context } from '@earendil-works/chord';
import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
import { createModels } from '@earendil-works/pi-ai/models';
import { vercelAIGatewayProvider } from '@earendil-works/pi-ai/providers/vercel-ai-gateway';
import { createRegistry, defineExtension, defineTool, Harness, ROOT_CONVERSATION_ID, type ToolRegistration } from '@earendil-works/pi-durable';
import type { World } from '@workflow/world';
import { NativeWorkspace } from 'harness-world-hands/workspace';
import { bashResultText, resolvePath, TOOL_SPECS, UNSAFE_CONFIRM_MS, type UnsafeToolName, unsafeResultText } from 'harness-world-hands/specs';
import type { Anchor } from 'harness-world/anchor';
import { type WorldStorage, type WorldStorageOptions } from './storage.ts';
import { worldStorage } from './index.ts';

const ctx = BACKGROUND_CONTEXT;

/** The provider id pi-ai 1.0 gives the Vercel AI Gateway. */
export const GATEWAY_PROVIDER = 'vercel-ai-gateway';

export interface PiDurableAgentOptions {
  world: World;
  /** A Gateway model id, e.g. `anthropic/claude-opus-5.5-fast`. */
  modelId: string;
  /** The Gateway credential (an OIDC token or an API key), asked for at every request. */
  apiKey: () => Promise<string>;
  instructions: string;
  /** Workflow name for runs this creates. Default `pi-durable`. */
  name?: string;
  storage?: WorldStorageOptions;
}

export interface PiDurableAgent {
  /**
   * `Harness.open(await worldStorage(world, id, { anchor }), ...)`: what
   * `worldStorage.wakeHandler` and the routes open. `anchor` is the delivery
   * (or deadline drive) its commits are written under.
   */
  openAgent(sessionId: string, anchor?: Anchor): Promise<Harness>;
  /** The storage behind the last harness `openAgent` opened for `sessionId` in this process (for a simulated crash). */
  storageOf(sessionId: string): WorldStorage | undefined;
  /** The root conversation with this agent's model and instructions (created on first use). */
  root(harness: Harness, context?: Context): ReturnType<Harness['root']>;
  modelId: string;
}

type FileSnapshot = Record<string, string>;
const filesOf = (details: unknown): FileSnapshot | undefined => {
  const files = (details as { files?: unknown } | undefined)?.files;
  return files && typeof files === 'object' ? (files as FileSnapshot) : undefined;
};

/**
 * Pi 1.0's durable Harness on a World with the demo's model, prompt and
 * workspace tools. The workspace is just-bash on an in-memory filesystem,
 * the same as the other harnesses' native baseline; every tool that can
 * change it records the whole workspace in its result's `details`, and a
 * process that opens the session rebuilds the workspace from the newest
 * one. So a crashed `bash` reruns against the files as of its start (the
 * crashed call recorded nothing), which is what makes the workspace tools
 * `replay: 'safe'`. The two unsafe example tools keep Pi's default (an
 * interrupted call comes back `interrupted`, never reruns).
 */
export function piDurableAgent(options: PiDurableAgentOptions): PiDurableAgent {
  const models = createModels({
    // The Gateway provider reads AI_GATEWAY_API_KEY from its auth context: hand it a fresh credential each time.
    authContext: {
      env: async (name) => (name === 'AI_GATEWAY_API_KEY' ? options.apiKey() : process.env[name]),
      fileExists: async () => false,
    },
  });
  models.setProvider(vercelAIGatewayProvider());
  if (!models.getModel(GATEWAY_PROVIDER, options.modelId)) throw new Error(`pi-ai 1.0 does not know ${options.modelId}`);
  const storages = new Map<string, WorldStorage>();

  const openAgent = async (sessionId: string, anchor?: Anchor): Promise<Harness> => {
    const storage = await worldStorage(options.world, sessionId, { name: options.name ?? 'pi-durable', ...options.storage, ...(anchor ? { anchor } : {}) });
    storages.set(sessionId, storage);
    const registry = createRegistry();
    registry.install(defineExtension({ name: 'workspace', tools: workspaceTools(() => hydrate(storage)) }));
    return Harness.open(storage, { models, registry, settings: { toolExecution: 'sequential' } }, ctx);
  };

  return {
    openAgent,
    storageOf: (id) => storages.get(id),
    root: (harness, context = ctx) =>
      harness.root(context, { agent: { model: { provider: GATEWAY_PROVIDER, modelId: options.modelId }, instructions: options.instructions } }),
    modelId: options.modelId,
  };
}

/** The workspace as of the newest tool result that recorded one (in a storage `workspaceTools` wrote to). */
export async function hydrate(storage: Pick<WorldStorage, 'scanEntries'>): Promise<NativeWorkspace> {
  let cursor: Parameters<WorldStorage['scanEntries']>[2];
  for (;;) {
    const page = await storage.scanEntries({ conversationId: ROOT_CONVERSATION_ID }, 200, cursor as never, ctx).catch(() => undefined);
    if (!page) break;
    for (const e of page.items) {
      if (e.kind !== 'pi.tool-result') continue;
      const files = filesOf((e.model?.[0] as { details?: unknown } | undefined)?.details);
      if (files) return NativeWorkspace.from(files);
    }
    if (!page.next) break;
    cursor = page.next;
  }
  return NativeWorkspace.from();
}

const text = (s: string) => ({ content: [{ type: 'text' as const, text: s }] });

const specTool = (name: keyof typeof TOOL_SPECS, replay: 'safe' | undefined, execute: (args: any, context: Context) => Promise<any>) =>
  defineTool({
    name: name as string,
    description: TOOL_SPECS[name].description,
    parameters: TOOL_SPECS[name].inputSchema as never,
    ...(replay ? { replay } : {}),
    execute: async (args, _api, context) => execute(args, context),
  }) as ToolRegistration;

/** The two non-idempotent example tools, unsafe_send_email and unsafe_make_payment (Pi's default replay: an interrupted call comes back interrupted). */
export function unsafeExampleTools(): ToolRegistration[] {
  const unsafe = (name: UnsafeToolName) =>
    specTool(name, undefined, async (input, context) => {
      const ref = `${name === 'unsafe_send_email' ? 'msg' : 'pay'}_${Math.random().toString(36).slice(2, 12)}`;
      await new Promise<void>((resolve) => {
        const timer = setTimeout(resolve, UNSAFE_CONFIRM_MS);
        context.abortSignal?.addEventListener('abort', () => (clearTimeout(timer), resolve()));
      });
      return text(unsafeResultText(name, input, ref));
    });
  return [unsafe('unsafe_send_email'), unsafe('unsafe_make_payment')];
}

/** bash, read_file, write_file, edit_file, list_files (`replay: 'safe'`) and the two unsafe example tools. */
export function workspaceTools(load: () => Promise<NativeWorkspace>): ToolRegistration[] {
  let ws: Promise<NativeWorkspace> | undefined;
  const workspace = () => (ws ??= load());
  const changed = async (w: NativeWorkspace, out: string) => ({ ...text(out), details: { files: await w.files() } });
  const tool = specTool;
  return [
    tool('bash', 'safe', async ({ command }, context) => {
      const w = await workspace();
      const result = await w.bash.exec(command, context.abortSignal ? { signal: context.abortSignal } : {});
      return changed(w, bashResultText(result));
    }),
    tool('read_file', 'safe', async ({ path }) => text(await (await workspace()).fs.readFile(resolvePath(path)))),
    tool('write_file', 'safe', async ({ path, content }) => {
      const w = await workspace();
      const target = resolvePath(path);
      await w.fs.mkdir(target.slice(0, target.lastIndexOf('/')), { recursive: true });
      await w.fs.writeFile(target, content);
      return changed(w, `wrote ${content.length} bytes to ${target}`);
    }),
    tool('edit_file', 'safe', async ({ path, oldText, newText }) => {
      const w = await workspace();
      const target = resolvePath(path);
      const before = await w.fs.readFile(target);
      const at = before.indexOf(oldText);
      if (at === -1) throw new Error(`oldText not found in ${target}`);
      if (before.indexOf(oldText, at + 1) !== -1) throw new Error(`oldText occurs more than once in ${target}`);
      await w.fs.writeFile(target, before.slice(0, at) + newText + before.slice(at + oldText.length));
      return changed(w, `edited ${target}`);
    }),
    tool('list_files', 'safe', async () => {
      const files = Object.keys(await (await workspace()).files()).sort();
      return text(files.length ? files.join('\n') : '(empty workspace)');
    }),
    ...unsafeExampleTools(),
  ];
}