Skip to content

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

6.1 KB
Raw Blame
import { sandboxName } from 'durable-harness/sandbox';
import type { Harness } from 'harness-world';
import type { Brain, Hands, HarnessOption } from 'harness-world-demo-ui';
import { BUILTIN_HARNESSES, handsReason, isHands, legacyHands, pickHands, sandboxOffReason as sandboxOffCopy } from 'harness-world-demo-ui/axes';

/**
 * The demo's Hands axis on the server (docs/workspaces.md §8): where a
 * session's model commands and files go, recorded on its `run_created`
 * (`config.hands`) and read back on every drive, so each session keeps the
 * hands it started with whichever instance drives it.
 */

/** A session's hands: what its `run_created` recorded, else what its harness ran with before the hands axis. */
export function handsOfConfig(config: unknown, harness: string): Hands {
  const hands = (config as { hands?: unknown } | undefined)?.hands;
  return isHands(hands) ? hands : legacyHands(harness);
}

/**
 * What a harness built on its first drive declares before it exists: its
 * `lanes`, and how Agent Runs learns its model calls. durable-harness's
 * tracing reads `modelCalls` when a drive starts, before the build: a
 * wrapper that leaves it out gets every model call recorded twice (an empty
 * `chat` span from the `model` effect next to the harness's own).
 */
export type UpFront = Pick<Harness, 'lanes' | 'modelCalls'>;

/** The fields of `upFront` that are set, for the wrapper. */
export function upFrontFields(upFront: UpFront): UpFront {
  return { ...(upFront.lanes ? { lanes: upFront.lanes } : {}), ...(upFront.modelCalls ? { modelCalls: upFront.modelCalls } : {}) };
}

/** `built`, with a warning when its `modelCalls` is not what its wrapper declared up front. */
export function checkUpFront(name: string, upFront: UpFront, built: Harness): Harness {
  const declared = upFront.modelCalls ?? 'effects';
  const actual = built.modelCalls ?? 'effects';
  if (actual !== declared) console.warn(`[harness] ${name}: its wrapper declares modelCalls '${declared}', the harness '${actual}': Agent Runs records its model calls wrongly`);
  return built;
}

/**
 * One kernel harness that is really one per hands: each is built on the
 * first drive of a session with those hands (in this process), and each
 * drive goes to its session's. `name` and `upFront` are known up front.
 */
export function byHands(name: string, upFront: UpFront, build: (hands: Hands) => Promise<Harness>): Harness {
  const built = new Map<Hands, Promise<Harness>>();
  return {
    name,
    ...upFrontFields(upFront),
    async drive(ctx) {
      const hands = handsOfConfig(ctx.config, name);
      let harness = built.get(hands);
      if (!harness) {
        harness = build(hands).then((h) => checkUpFront(name, upFront, h));
        built.set(hands, harness);
        // A build that failed (a missing credential) is tried again on the next drive.
        harness.catch(() => built.delete(hands));
      }
      return (await harness).drive(ctx);
    },
  };
}

/**
 * The most a `sandbox()` session may spend on its model, over its life, in
 * US dollars: `HARNESS_SANDBOX_SESSION_USD`, default $2. Each session of
 * the demo's Claude Code and Codex boots a Vercel Sandbox VM and makes a
 * Drive; the cap is what keeps one visitor's session from running up the
 * model bill (the demo's routes start sessions for any visitor the
 * deployment's protection lets in).
 */
export function sandboxSessionUsd(): number {
  const usd = Number(process.env.HARNESS_SANDBOX_SESSION_USD ?? 2);
  return Number.isFinite(usd) && usd > 0 ? usd : 2;
}

/** The demo's `sandbox()`: the session's own Vercel Sandbox VM and Drive, with a finite per-session model budget. */
export async function demoSandbox() {
  const { sandbox } = await import('durable-harness');
  return sandbox({ budget: { sessionUsd: sandboxSessionUsd() } });
}

/** A production or preview deployment (`VERCEL_ENV`, not `VERCEL`: `vercel env pull` writes `VERCEL=1` locally). */
export const deployed = () => process.env.VERCEL_ENV === 'production' || process.env.VERCEL_ENV === 'preview';

/**
 * Why this deployment can't make Vercel Sandbox VMs (the `machine` and
 * `sandbox` hands; Claude Code and Codex altogether), or undefined when it
 * can. The VMs are named for the project (`sandboxName`): a deployment has
 * it in `VERCEL_PROJECT_ID` and authenticates with its OIDC token; a laptop
 * needs `vercel link` (the Vercel CLI's login gives the token).
 */
export function sandboxOffReason(): string | undefined {
  try {
    // Synchronous: durable-harness/sandbox's entry loads only the names, never the session factory or a VM.
    sandboxName('demo');
    return undefined;
  } catch {
    return sandboxOffCopy(!deployed());
  }
}

/** Why `option` can't take `hands` with its brain in `brain` (default a Function's) on this deployment, or undefined. */
export function serverHandsReason(option: Pick<HarnessOption, 'label' | 'hands' | 'handsDisabled'>, hands: Hands, brain: Brain = 'server'): string | undefined {
  const sandboxOff = sandboxOffReason();
  return handsReason(option, brain, hands, sandboxOff ? { sandboxOff } : {});
}

/**
 * The hands a session the sessions route starts gets (a Server brain, or a hybrid one's):
 * `wanted`, checked against the harness's (`option`: a process harness's
 * from lib/harnesses, Pi's and fx's from the page's own list), or its
 * default for this deployment when the page names none. A hands it can't
 * take here is an error, with why.
 */
export function startHands(option: Pick<HarnessOption, 'label' | 'hands' | 'defaultHands' | 'handsDisabled'>, wanted: unknown, brain: Brain = 'server'): { hands: Hands } | { error: string } {
  if (wanted === undefined) {
    const sandboxOff = sandboxOffReason();
    return { hands: pickHands(option, brain, undefined, sandboxOff ? { sandboxOff } : {}) };
  }
  if (!isHands(wanted)) return { error: `unknown hands ${JSON.stringify(wanted)}` };
  const reason = serverHandsReason(option, wanted, brain);
  return reason ? { error: reason } : { hands: wanted };
}

/** The option Pi's and fx's hands are checked against (the page's own list, `BUILTIN_HARNESSES`). */
export const builtinOption = (harness: string) => BUILTIN_HARNESSES.find((h) => h.value === harness);