@temporalio/agent-harness 0.0.0-stage → 0.1.0

package/dist/src/harness/agent.d.ts

@@ -0,0 +1,137 @@
+import { type ActivityOptions } from "@temporalio/workflow";
+import { z } from "zod";
+import { MidTurn, ToolApprovalPolicy, type AgentConfig, type InferInput, type InferOutput, type JsonValue, type Schema, type AutoApprovalCriteria, type AutoModeEvaluator, type TurnStreamContext } from "./agent-protocol/index.ts";
+import { AgentWorkflowRunner, type HandlerDecl, type HandlerImpl } from "./agent-workflow.ts";
+import type { StateDecl, StateRef } from "./state/index.ts";
+import type { AnyHarnessTool, HarnessTool, ObjectSchema } from "./agent-workflow/types.ts";
+export type { AnyHarnessTool, HarnessTool };
+export declare function handler<I extends z.ZodType, O extends z.ZodType>(decl: {
+    description: string;
+    input: I;
+    output: O;
+    midTurn?: MidTurn;
+    modelCallable?: boolean;
+    /**
+     * The input's parameter name (a Python handler's own parameter name): a parent's subagent send
+     * tool takes the input under it. Defaults to "message".
+     */
+    inputName?: string;
+}): HandlerDecl<I, O>;
+/** Phantom marker for a workflow-supplied tool parameter, hidden from the model. */
+export interface Injected<T> {
+    readonly __injected?: T;
+}
+export declare const injected: <T>() => Injected<T>;
+type InjectedValues<J> = {
+    [K in keyof J]: J[K] extends Injected<infer T> ? T : never;
+};
+interface ToolOptions<I extends ObjectSchema, O extends Schema | undefined, J> {
+    name: string;
+    description: string;
+    inputSchema: I;
+    outputSchema?: O;
+    inherentlySafe?: boolean;
+    autoApprovalCriteria?: string;
+    injected?: J;
+}
+type Output<O> = O extends Schema ? InferOutput<O> : unknown;
+/** Which call an inline tool's `execute` is running. */
+export interface InlineToolCall {
+    tool_id: string;
+}
+/** The context an activity tool's body runs with: which call it is, and where to publish. */
+export interface AgentToolContext {
+    stream_context: TurnStreamContext;
+    tool_id: string;
+}
+/**
+ * `tool_end`'s `tool_output`: the result as JSON. A tool that returns nothing gives `null`, an
+ * object's `toJSON` is honored (a `Date` is its ISO string), and an object property that is
+ * `undefined` is absent, as the payload converter encodes them.
+ *
+ * Where `JSON.stringify` would lose data silently, the call fails instead: a `Map`, `Set` or other
+ * built-in object with no JSON form, a function, symbol or bigint, a number that is not finite, an
+ * `undefined` array item, or a cycle. The protocol carries tool results as JSON, and a value that
+ * reaches readers changed would mean something other than what the tool returned.
+ */
+export declare function toolOutputJson(toolName: string, result: unknown): JsonValue;
+/**
+ * An inline tool when given `execute` (it runs in the workflow: deterministic code only), or a
+ * callback tool when not: the call parks in the workflow until an attached client fulfills it
+ * via the `provide_callback_result` update, validated against the required `outputSchema`.
+ * `execute` gets the call's `tool_id` third, to key the side effects of activities it starts on.
+ */
+export declare function tool<I extends ObjectSchema, O extends Schema | undefined = undefined, J = {}>(options: ToolOptions<I, O, J> & {
+    execute: (input: InferOutput<I>, injected: InjectedValues<J>, call: InlineToolCall) => Promise<Output<O>>;
+}): HarnessTool<InferInput<I>, Output<O>>;
+export declare function tool<I extends ObjectSchema, O extends Schema, J = {}>(options: ToolOptions<I, O, J> & {
+    outputSchema: O;
+    execute?: undefined;
+    timeout?: string | number;
+}): HarnessTool<InferInput<I>, InferOutput<O>>;
+/**
+ * A durable, activity-backed tool. This is the workflow-side declaration; register its body on a
+ * worker with `toolActivity(tool, impl)` from `@temporalio/agent-harness-worker`, which also
+ * publishes the call's tool_start and its tool_end or tool_error from the activity, once per
+ * attempt, and heartbeats while it runs.
+ *
+ * Runs with a 30 s start-to-close timeout and the default retry policy unless `activityOptions`
+ * replaces them (its `summary` defaults to "tool_call"). The body runs at least once and may run
+ * again after a crash or timeout, so make side effects idempotent (key them on `ctx.tool_id`).
+ */
+export declare function activityTool<I extends ObjectSchema, O extends Schema | undefined = undefined, J = {}>(options: ToolOptions<I, O, J> & {
+    activityOptions?: ActivityOptions;
+}): HarnessTool<InferInput<I>, Output<O>> & {
+    readonly __activity?: {
+        input: InferOutput<I>;
+        output: Output<O>;
+        injected: InjectedValues<J>;
+    };
+};
+type States = Record<string, StateDecl<z.ZodType<Record<string, unknown>>>>;
+type StateRefs<S extends States> = {
+    [K in keyof S]: StateRef<z.output<S[K]["schema"]>>;
+};
+type InitData<D> = D extends {
+    schema: infer Z extends z.ZodType;
+    required: infer R;
+} ? R extends true ? z.output<Z> : z.output<Z> | null : undefined;
+/** An agent's init data: what its workflow takes after its config, and whether it must be sent. */
+export type InitDataDecl = {
+    schema: z.ZodType;
+    required: boolean;
+};
+export interface AgentContext<S extends States, D> {
+    runner: AgentWorkflowRunner;
+    config: AgentConfig;
+    data: InitData<D>;
+    state: StateRefs<S>;
+}
+export type AgentImpl<H extends Record<string, HandlerDecl>> = {
+    [K in keyof H]: HandlerImpl<H[K]>;
+} & {
+    /** Awaited before the first message, and again at the start of each run after a continue-as-new. */
+    setup?: () => Promise<void>;
+    /** Awaited once, after close drains (or on cancellation). */
+    teardown?: () => Promise<void>;
+};
+export interface AgentDefinition<H extends Record<string, HandlerDecl> = Record<string, HandlerDecl>, S extends States = States, D extends InitDataDecl | undefined = InitDataDecl | undefined> {
+    /** The workflow type. Export the result of `defineAgent` under exactly this name. */
+    name: string;
+    handlers: H;
+    states?: S;
+    initData?: D;
+    approvalPolicyDefault: ToolApprovalPolicy;
+    autoApprovalCriteriaDefault?: AutoApprovalCriteria;
+    autoModeEvaluator?: AutoModeEvaluator;
+    create(ctx: AgentContext<S, D>): AgentImpl<H>;
+}
+export type AgentWorkflow<Def extends AgentDefinition = AgentDefinition> = ((config?: unknown, data?: unknown) => Promise<void>) & {
+    readonly definition: Def;
+};
+export declare function defineAgent<H extends Record<string, HandlerDecl>, S extends States = {}, D extends InitDataDecl | undefined = undefined>(definition: AgentDefinition<H, S, D>): AgentWorkflow<AgentDefinition<H, S, D>>;
+/** `{ required, schema }` for an agent's init data, as `GET /api/agents` reports it; null if none. */
+export declare function agentInitDataSchema(agent: AgentWorkflow): {
+    required: boolean;
+    schema: Record<string, unknown>;
+} | null;

package/dist/src/harness/agent.js

@@ -0,0 +1,272 @@
+// The authoring API. `defineAgent` turns a declaration into a Temporal workflow function (export
+// it under the agent's workflow type name); `handler` declares an accepted message; `tool` (inline,
+// or callback when it has no `execute`) and `activityTool` declare the three tool kinds. Every tool
+// publishes its own tool_start/tool_end lifecycle and passes the approval gate before it runs.
+//
+// Declarations are static (plain data plus zod schemas), so the web server and a parent agent can
+// read an agent's handlers and init data without running it, exactly as Python reads its class.
+import { ApplicationFailure, CancellationScope, isCancellation, proxyActivities, workflowInfo, } from "@temporalio/workflow";
+import { z } from "zod";
+import { AgentConfigSchema, MidTurn, ToolApprovalPolicy, toJsonSchema, validate, } from "./agent-protocol/index.js";
+import { AgentWorkflowRunner, currentToolCall, } from "./agent-workflow.js";
+import { errorMessage, isOwnCancellation } from "./agent-workflow/errors.js";
+// ---------------------------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------------------------
+export function handler(decl) {
+    if (!decl.description.trim())
+        throw new TypeError("handler(): a description is required (it is the tool description)");
+    return { midTurn: MidTurn.REJECT, modelCallable: true, inputName: "message", ...decl };
+}
+export const injected = () => ({});
+/**
+ * `tool_end`'s `tool_output`: the result as JSON. A tool that returns nothing gives `null`, an
+ * object's `toJSON` is honored (a `Date` is its ISO string), and an object property that is
+ * `undefined` is absent, as the payload converter encodes them.
+ *
+ * Where `JSON.stringify` would lose data silently, the call fails instead: a `Map`, `Set` or other
+ * built-in object with no JSON form, a function, symbol or bigint, a number that is not finite, an
+ * `undefined` array item, or a cycle. The protocol carries tool results as JSON, and a value that
+ * reaches readers changed would mean something other than what the tool returned.
+ */
+export function toolOutputJson(toolName, result) {
+    if (result === undefined)
+        return null;
+    const notJson = (path, what) => ApplicationFailure.create({
+        type: "ToolOutputNotJson",
+        nonRetryable: true,
+        message: `tool '${toolName}' returned a value with no JSON form at ${path}: ${what}`,
+    });
+    const ancestors = new Set();
+    const encode = (value, path, key) => {
+        if (value === null || typeof value === "string" || typeof value === "boolean")
+            return value;
+        if (typeof value === "number") {
+            if (!Number.isFinite(value))
+                throw notJson(path, String(value));
+            return value;
+        }
+        if (typeof value !== "object")
+            throw notJson(path, `a ${typeof value}`);
+        const toJSON = value.toJSON;
+        if (typeof toJSON === "function")
+            return encode(toJSON.call(value, key), path, key);
+        if (ancestors.has(value))
+            throw notJson(path, "a cycle");
+        ancestors.add(value);
+        try {
+            if (Array.isArray(value))
+                return value.map((item, i) => {
+                    if (item === undefined)
+                        throw notJson(`${path}[${i}]`, "undefined");
+                    return encode(item, `${path}[${i}]`, String(i));
+                });
+            // Plain objects and class instances tag as `Object`; Map, Set, RegExp, Error, typed
+            // arrays and the like have no own fields for JSON to carry.
+            const tag = Object.prototype.toString.call(value).slice(8, -1);
+            if (tag !== "Object")
+                throw notJson(path, `a ${tag}`);
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                if (v !== undefined)
+                    out[k] = encode(v, `${path}.${k}`, k);
+            }
+            return out;
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    };
+    return encode(result, "$", "");
+}
+function injectedValues(name, names, available) {
+    const values = {};
+    for (const n of names) {
+        if (!(n in available)) {
+            throw ApplicationFailure.create({
+                type: "MissingInjection",
+                nonRetryable: true,
+                message: `tool '${name}' requires injected argument '${n}', but runTool was called without it`,
+            });
+        }
+        values[n] = available[n];
+    }
+    return values;
+}
+function baseTool(kind, options, body, publishLifecycle) {
+    const injectedNames = Object.keys(options.injected ?? {});
+    const description = options.description;
+    return {
+        kind,
+        name: options.name,
+        description,
+        inputSchema: options.inputSchema,
+        outputSchema: options.outputSchema,
+        inherentlySafe: options.inherentlySafe ?? false,
+        autoApprovalCriteria: options.autoApprovalCriteria ?? null,
+        injected: injectedNames,
+        parameters: toJsonSchema(options.inputSchema),
+        async invoke(raw) {
+            const { runner, toolId, injections } = currentToolCall(`tool '${options.name}'`);
+            const ctx = runner.currentStreamContext;
+            if (ctx === null)
+                throw new Error(`tool '${options.name}' must be invoked within an active turn`);
+            const values = injectedValues(options.name, injectedNames, injections);
+            const parsed = validate(options.inputSchema, raw);
+            if (!parsed.ok) {
+                throw ApplicationFailure.create({
+                    type: "InvalidToolInput",
+                    nonRetryable: true,
+                    message: `Payload for tool '${options.name}' does not match its schema: ${parsed.message}`,
+                });
+            }
+            const input = parsed.value;
+            const toolInput = input;
+            await runner.applyApprovalPolicy(toolId, options.name, toolInput, {
+                inherentlySafe: options.inherentlySafe ?? false,
+                description,
+                autoApprovalCriteria: options.autoApprovalCriteria ?? null,
+            });
+            if (!publishLifecycle)
+                return (await body(input, values, toolId, runner));
+            runner.pub(ctx.turn_id, ctx.turn_number, {
+                type: "tool_start",
+                tool_id: toolId,
+                tool_name: options.name,
+                tool_input: toolInput,
+            });
+            let result;
+            let toolOutput;
+            try {
+                result = await body(input, values, toolId, runner);
+                toolOutput = toolOutputJson(options.name, result);
+            }
+            catch (e) {
+                if (!isOwnCancellation(e))
+                    runner.pub(ctx.turn_id, ctx.turn_number, {
+                        type: "tool_error",
+                        tool_id: toolId,
+                        tool_name: options.name,
+                        message: errorMessage(e),
+                    });
+                throw e;
+            }
+            runner.pub(ctx.turn_id, ctx.turn_number, {
+                type: "tool_end",
+                tool_id: toolId,
+                tool_name: options.name,
+                tool_output: toolOutput,
+            });
+            return result;
+        },
+    };
+}
+export function tool(options) {
+    const { execute } = options;
+    if (execute !== undefined)
+        return baseTool("inline", options, (input, values, toolId) => execute(input, values, { tool_id: toolId }), true);
+    const output = options.outputSchema;
+    if (output === undefined)
+        throw new TypeError(`tool '${options.name}' has no execute, so it is a callback tool and needs an outputSchema`);
+    const outputSchema = toJsonSchema(output);
+    return baseTool("callback", options, (input, _values, toolId, runner) => runner.awaitCallbackResult({
+        toolId,
+        toolName: options.name,
+        toolInput: input,
+        output,
+        outputSchema,
+        timeout: options.timeout,
+    }), true);
+}
+/**
+ * A durable, activity-backed tool. This is the workflow-side declaration; register its body on a
+ * worker with `toolActivity(tool, impl)` from `@temporalio/agent-harness-worker`, which also
+ * publishes the call's tool_start and its tool_end or tool_error from the activity, once per
+ * attempt, and heartbeats while it runs.
+ *
+ * Runs with a 30 s start-to-close timeout and the default retry policy unless `activityOptions`
+ * replaces them (its `summary` defaults to "tool_call"). The body runs at least once and may run
+ * again after a crash or timeout, so make side effects idempotent (key them on `ctx.tool_id`).
+ */
+export function activityTool(options) {
+    const activityOptions = {
+        summary: "tool_call",
+        ...(options.activityOptions ?? { startToCloseTimeout: "30 seconds" }),
+    };
+    return baseTool("activity", options, async (input, values, toolId, runner) => {
+        const ctx = {
+            stream_context: runner.currentStreamContext,
+            tool_id: toolId,
+        };
+        const activities = proxyActivities(activityOptions);
+        return activities[options.name](input, values, ctx);
+    }, false);
+}
+function invalidInput(message, type = "InvalidAgentInput") {
+    return ApplicationFailure.create({ type, nonRetryable: true, message });
+}
+export function defineAgent(definition) {
+    const workflow = async (rawConfig, rawData) => {
+        const workflowType = workflowInfo().workflowType;
+        if (workflowType !== definition.name) {
+            throw invalidInput(`agent '${definition.name}' is registered as workflow type '${workflowType}'; export it under its own name`);
+        }
+        const config = AgentConfigSchema.safeParse(rawConfig ?? {});
+        if (!config.success)
+            throw invalidInput(`${definition.name} was started with an invalid AgentConfig: ${config.error.message}`);
+        let data;
+        if (definition.initData === undefined) {
+            data = undefined;
+        }
+        else if (rawData === undefined || rawData === null) {
+            if (definition.initData.required) {
+                throw invalidInput(`${definition.name} requires init data, and none was given.`, "InitDataRequired");
+            }
+            data = null;
+        }
+        else {
+            const parsed = definition.initData.schema.safeParse(rawData);
+            if (!parsed.success)
+                throw invalidInput(`${definition.name} was started with invalid init data: ${parsed.error.message}`);
+            data = parsed.data;
+        }
+        const runner = new AgentWorkflowRunner(config.data, {
+            handlers: definition.handlers,
+            approvalPolicyDefault: definition.approvalPolicyDefault,
+            autoApprovalCriteriaDefault: definition.autoApprovalCriteriaDefault,
+            autoModeEvaluator: definition.autoModeEvaluator,
+            states: definition.states,
+            data,
+        });
+        const state = runner.state;
+        const impl = definition.create({
+            runner,
+            config: config.data,
+            data: data,
+            state,
+        });
+        for (const name of Object.keys(definition.handlers)) {
+            if (typeof impl[name] !== "function")
+                throw new TypeError(`${definition.name}.create() returned no implementation for handler '${name}'`);
+        }
+        await impl.setup?.();
+        try {
+            await runner.run(impl);
+        }
+        catch (e) {
+            if (isCancellation(e) && impl.teardown)
+                await CancellationScope.nonCancellable(impl.teardown);
+            throw e;
+        }
+        await impl.teardown?.();
+    };
+    Object.defineProperty(workflow, "name", { value: definition.name });
+    return Object.assign(workflow, { definition });
+}
+/** `{ required, schema }` for an agent's init data, as `GET /api/agents` reports it; null if none. */
+export function agentInitDataSchema(agent) {
+    const init = agent.definition.initData;
+    if (init === undefined)
+        return null;
+    return { required: init.required, schema: toJsonSchema(init.schema) };
+}

package/dist/src/harness/code-mode/activity-fs.d.ts

@@ -0,0 +1,46 @@
+import type { z } from "zod";
+import type { FileStat, FileSystem } from "./vfs.ts";
+import type { OKFGraph } from "./okf.ts";
+/** The most one file-view call returns. The console pages through anything larger. */
+export declare const MAX_VIEW_BYTES = 256000;
+export declare function activityName(filesystem: string, operation: string): string;
+export interface ActivityFilesystem<C> {
+    readonly kind: "activity-filesystem";
+    readonly name: string;
+    readonly writable: boolean;
+    readonly configSchema: z.ZodType<C>;
+    backend(config: C, options?: {
+        timeout?: string | number;
+        okfVersion?: string | null;
+    }): ActivityBackend;
+}
+/**
+ * A filesystem whose operations run as `vfs.<name>.*` activities. `configSchema` is validated
+ * on every activity, not here: a bad config fails the activity that uses it.
+ */
+export declare function activityFilesystem<C>(options: {
+    name: string;
+    configSchema: z.ZodType<C>;
+    writable: boolean;
+}): ActivityFilesystem<C>;
+/**
+ * A read-only mount backend. Each operation is one activity on the workflow's task queue.
+ * `okfGraph` walks the bundle in a single activity.
+ */
+export declare class ActivityBackend implements FileSystem {
+    #private;
+    readonly source: {
+        filesystem: string;
+        config: Record<string, unknown>;
+    };
+    readonly okfVersion: string | null;
+    constructor(source: {
+        filesystem: string;
+        config: Record<string, unknown>;
+    }, timeout: string | number, okfVersion: string | null);
+    stat(path: string): Promise<FileStat | null>;
+    read(path: string): Promise<Uint8Array>;
+    list(path: string): Promise<string[]>;
+    okfGraph(prefix: string, links: boolean): Promise<OKFGraph>;
+    protected do(operation: string, extra: Record<string, unknown>): Promise<void>;
+}

package/dist/src/harness/code-mode/activity-fs.js

@@ -0,0 +1,102 @@
+// The workflow half of an activity-backed filesystem. The worker builds the activities
+// (`filesystemActivities`); here a mount only calls them by name, so this module stays sandbox-safe.
+import { proxyActivities } from "@temporalio/workflow";
+import { decodeBase64, encodeBase64 } from "./base64.js";
+const NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** The most one file-view call returns. The console pages through anything larger. */
+export const MAX_VIEW_BYTES = 256_000;
+const RETRY = { maximumAttempts: 3 };
+export function activityName(filesystem, operation) {
+    return `vfs.${filesystem}.${operation}`;
+}
+/**
+ * A filesystem whose operations run as `vfs.<name>.*` activities. `configSchema` is validated
+ * on every activity, not here: a bad config fails the activity that uses it.
+ */
+export function activityFilesystem(options) {
+    if (!NAME.test(options.name))
+        throw new TypeError(`filesystem name '${options.name}' must be lowercase letters, digits, '-' and '_', like 'local-disk'`);
+    return {
+        kind: "activity-filesystem",
+        name: options.name,
+        writable: options.writable,
+        configSchema: options.configSchema,
+        backend(config, { timeout = "30 seconds", okfVersion = null } = {}) {
+            if (config === null || typeof config !== "object" || Array.isArray(config))
+                throw new TypeError(`${options.name}.backend() takes a config object`);
+            const stored = JSON.parse(JSON.stringify(config));
+            const source = { filesystem: options.name, config: stored };
+            return options.writable
+                ? new WritableActivityBackend(source, timeout, okfVersion)
+                : new ActivityBackend(source, timeout, okfVersion);
+        },
+    };
+}
+const utf8 = new TextEncoder();
+function unwire(content, encoding) {
+    return encoding === "base64" ? decodeBase64(content) : utf8.encode(content);
+}
+function wire(data) {
+    try {
+        return { content: new TextDecoder("utf-8", { fatal: true }).decode(data), encoding: "utf-8" };
+    }
+    catch {
+        return { content: encodeBase64(data), encoding: "base64" };
+    }
+}
+/**
+ * A read-only mount backend. Each operation is one activity on the workflow's task queue.
+ * `okfGraph` walks the bundle in a single activity.
+ */
+export class ActivityBackend {
+    source;
+    okfVersion;
+    #timeout;
+    constructor(source, timeout, okfVersion) {
+        this.source = source;
+        this.#timeout = timeout;
+        this.okfVersion = okfVersion;
+    }
+    async stat(path) {
+        const result = await this.#call("stat", { path });
+        return result.found;
+    }
+    async read(path) {
+        const found = await this.#call("read", { path });
+        return unwire(found.content, found.encoding);
+    }
+    async list(path) {
+        return this.#call("list", { path });
+    }
+    okfGraph(prefix, links) {
+        return this.#call("okf_graph", { path: prefix, links });
+    }
+    async #call(operation, extra) {
+        const arg = { config: this.source.config, ...extra };
+        const activities = proxyActivities({
+            startToCloseTimeout: this.#timeout,
+            retry: RETRY,
+        });
+        // A failure stays an ActivityFailure, as in Python: the driver gives the script an OS error
+        // as its built-in, and any other as the activity's failure.
+        return activities[activityName(this.source.filesystem, operation)](arg);
+    }
+    do(operation, extra) {
+        return this.#call(operation, extra);
+    }
+}
+class WritableActivityBackend extends ActivityBackend {
+    async write(path, data) {
+        const { content, encoding } = wire(data);
+        await this.do("write", { path, content, encoding });
+    }
+    async mkdir(path) {
+        await this.do("mkdir", { path });
+    }
+    async delete(path) {
+        await this.do("delete", { path });
+    }
+    async rename(path, target) {
+        await this.do("rename", { path, target });
+    }
+}

package/dist/src/harness/code-mode/base64.d.ts

@@ -0,0 +1,2 @@
+export declare function encodeBase64(bytes: Uint8Array): string;
+export declare function decodeBase64(value: string): Uint8Array;

package/dist/src/harness/code-mode/base64.js

@@ -0,0 +1,41 @@
+// Base64 that runs in the workflow sandbox, which has no atob/btoa or Buffer.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function encodeBase64(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i] ?? 0;
+        const b = i + 1 < bytes.length ? (bytes[i + 1] ?? 0) : 0;
+        const c = i + 2 < bytes.length ? (bytes[i + 2] ?? 0) : 0;
+        const n = (a << 16) | (b << 8) | c;
+        out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63];
+        out += i + 1 < bytes.length ? ALPHABET[(n >> 6) & 63] : "=";
+        out += i + 2 < bytes.length ? ALPHABET[n & 63] : "=";
+    }
+    return out;
+}
+export function decodeBase64(value) {
+    let length = value.length;
+    while (length > 0 && value[length - 1] === "=")
+        length--;
+    const clean = value.slice(0, length);
+    if (clean.length % 4 === 1)
+        throw new Error("invalid base64");
+    const out = new Uint8Array((clean.length * 3) >> 2);
+    let n = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const a = ALPHABET.indexOf(clean[i] ?? "");
+        const b = ALPHABET.indexOf(clean[i + 1] ?? "");
+        const c = i + 2 < clean.length ? ALPHABET.indexOf(clean[i + 2]) : -1;
+        const d = i + 3 < clean.length ? ALPHABET.indexOf(clean[i + 3]) : -1;
+        if (a < 0 || b < 0 || (c < 0 && i + 2 < clean.length) || (d < 0 && i + 3 < clean.length)) {
+            throw new Error("invalid base64");
+        }
+        const chunk = (a << 18) | (b << 12) | ((c < 0 ? 0 : c) << 6) | (d < 0 ? 0 : d);
+        out[n++] = (chunk >> 16) & 255;
+        if (c >= 0)
+            out[n++] = (chunk >> 8) & 255;
+        if (d >= 0)
+            out[n++] = chunk & 255;
+    }
+    return out.subarray(0, n);
+}

package/dist/src/harness/code-mode/driver.d.ts

@@ -0,0 +1,78 @@
+import type { AnyHarnessTool } from "../agent.ts";
+import type { AgentWorkflowRunner } from "../agent-workflow.ts";
+import { type TypeCheckStubs } from "./stubs.ts";
+import { type FileOpCall, type Mount } from "./vfs.ts";
+export declare const CODE_START_BATCH_ACTIVITY = "code_start_batch";
+export declare const CODE_RESUME_BATCH_ACTIVITY = "code_resume_batch";
+export declare const CODE_TYPE_CHECK_ACTIVITY = "code_type_check";
+export declare const DEFAULT_STEP_TIMEOUT = "30 seconds";
+export declare const STEP_RETRY: {
+    maximumAttempts: number;
+};
+export interface PendingCall {
+    /** Monty's call id. */
+    call_id: number;
+    function_name: string;
+    args: unknown[];
+    kwargs: Record<string, unknown>;
+}
+/** A pending call that is the script's `await asyncio.sleep(seconds)`, answered with a durable timer. */
+export declare const SLEEP_CALL = "asyncio.sleep";
+/** The workflow's clock (epoch ms) and the script's random seed: a script observes nothing of the worker. */
+export interface HostClock {
+    now: number;
+    seed: number;
+}
+export interface CodeBatchStep {
+    done: boolean;
+    stdout: string;
+    /** Opaque resume state while awaiting a batch: Monty's snapshot dump. */
+    snapshot: string | null;
+    /** Every call the script made in this step, in call order. Each starts at once. */
+    calls: PendingCall[];
+    /** The calls the script is blocked on, in call order (made in this step or earlier). */
+    awaiting: number[];
+    /** Set when the step stopped at a file operation on a mount: the next resume answers it. */
+    file_op?: FileOpCall;
+    output_json: string | null;
+    error: string | null;
+}
+export interface CallResult {
+    call_id: number;
+    return_value: unknown;
+    /** Set when the host call failed or was denied: the script sees it as an exception it can catch. */
+    error?: string;
+    /** The Python exception the script raises for `error`. */
+    error_type?: string;
+}
+export interface ResumeBatchInput {
+    snapshot: string;
+    results: CallResult[];
+    type_names: string[];
+    clock: HostClock;
+    /** The script has mounts, so its file operations end steps. */
+    files?: boolean;
+}
+export interface CodeModeActivities {
+    code_start_batch(script: string, stubs: TypeCheckStubs | null, clock: HostClock, files?: boolean): Promise<CodeBatchStep>;
+    code_resume_batch(input: ResumeBatchInput): Promise<CodeBatchStep>;
+    code_type_check(script: string, stubs: TypeCheckStubs): Promise<string>;
+}
+/**
+ * Runs a Code Mode script to completion, dispatching its host calls to real harness tools.
+ *
+ * Constructed per invocation by the `codeModeTool` closure, with the live runner. `toolsByName` is
+ * validated once by the factory; `stubs` are the generated stubs the sandbox type-checks the
+ * script against before running it.
+ */
+export declare class CodeModeDriver {
+    #private;
+    constructor(runner: AgentWorkflowRunner, toolsByName: ReadonlyMap<string, AnyHarnessTool>, options: {
+        injections: Readonly<Record<string, unknown>>;
+        stubs: TypeCheckStubs;
+        mounts: readonly Mount[];
+        stepTimeout: string | number;
+    });
+    /** Drive `script` to completion; return its output and final value (or the error) as text. */
+    runScript(script: string): Promise<string>;
+}