@temporalio/agent-harness 0.0.0-stage → 0.1.0

package/dist/src/harness/py-repr.d.ts

@@ -0,0 +1,2 @@
+/** Python's repr() for JSON-native values: what the model sees as the script's result. */
+export declare function pyRepr(value: unknown): string;

package/dist/src/harness/py-repr.js

@@ -0,0 +1,24 @@
+// Python's repr() of JSON-native values, which is what the Python harness shows a model.
+/** Python's repr() for JSON-native values: what the model sees as the script's result. */
+export function pyRepr(value) {
+    if (value === null || value === undefined)
+        return "None";
+    if (value === true)
+        return "True";
+    if (value === false)
+        return "False";
+    if (typeof value === "string") {
+        const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+        const escaped = value.replace(/[\\\n\r\t]/g, (c) => ({ "\\": "\\\\", "\n": "\\n", "\r": "\\r", "\t": "\\t" })[c]);
+        return `${quote}${escaped.replaceAll(quote, `\\${quote}`)}${quote}`;
+    }
+    if (typeof value === "number")
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.map(pyRepr).join(", ")}]`;
+    if (typeof value === "object")
+        return `{${Object.entries(value)
+            .map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`)
+            .join(", ")}}`;
+    return String(value);
+}

package/dist/src/harness/state/index.d.ts

@@ -0,0 +1,40 @@
+import { type Draft } from "immer";
+import type { z } from "zod";
+export declare class HarnessStateError extends Error {
+    name: string;
+}
+export interface StateSnapshotEvent {
+    type: "state_snapshot";
+    state_id: string;
+    version: number;
+    value: Record<string, unknown>;
+}
+export interface StatePatchEvent {
+    type: "state_patch";
+    state_id: string;
+    version: number;
+    ops: Record<string, unknown>[];
+}
+export type StateEvent = StateSnapshotEvent | StatePatchEvent;
+export interface StateDecl<S extends z.ZodType<Record<string, unknown>>> {
+    readonly schema: S;
+    /** Receives the agent's validated init data (null/undefined when it has none). */
+    readonly initial: (data: unknown) => z.input<S>;
+}
+/** Declare a piece of observable state. Without `initial`, the schema's defaults must cover it. */
+export declare function state<S extends z.ZodType<Record<string, unknown>>>(schema: S, initial?: (data: unknown) => z.input<S>): StateDecl<S>;
+/** Why a Python peer can't read `value` back as sent, if it can't. */
+export declare function portabilityProblem(value: unknown, depth?: number): string | undefined;
+export declare class StateRef<T extends Record<string, unknown>> {
+    #private;
+    readonly stateId: string;
+    constructor(stateId: string, decl: StateDecl<z.ZodType<T>>, publish: (event: StateEvent) => void, data?: unknown);
+    /** The committed value. Deeply frozen: change it only through `mutate` or `set`. */
+    get current(): T;
+    get version(): number;
+    snapshot(): StateSnapshotEvent;
+    /** Apply `recipe` to a draft and publish what it changed. Synchronous by contract. */
+    mutate(recipe: (draft: Draft<T>) => void): void;
+    /** Replace the whole value (one `replace` op at the root). */
+    set(value: z.input<z.ZodType<T>>): void;
+}

package/dist/src/harness/state/index.js

@@ -0,0 +1,142 @@
+// Observable agent state. Declare it on an agent with `states: { board: state(BoardSchema) }`;
+// the key is its `state_id`. Every committed `ref.mutate((d) => { ... })` is published on the
+// event stream as RFC 6902 ops, so a consumer that applies one snapshot and then every patch in
+// version order holds the exact value without polling. Immer records the ops (it emits only
+// add/replace/remove, which is all the protocol allows); zod re-validates every commit.
+import { applyPatches, castDraft, enablePatches, freeze, produceWithPatches, } from "immer";
+enablePatches();
+export class HarnessStateError extends Error {
+    name = "HarnessStateError";
+}
+/** Declare a piece of observable state. Without `initial`, the schema's defaults must cover it. */
+export function state(schema, initial = () => ({})) {
+    return { schema, initial };
+}
+// Python's JSON parser rejects lone surrogates and nesting past about 200 levels, and a JSON number
+// past 2^53 has already been rounded by the time JavaScript sees it.
+const MAX_JSON_DEPTH = 200;
+/** Why a Python peer can't read `value` back as sent, if it can't. */
+export function portabilityProblem(value, depth = 0) {
+    if (typeof value === "string")
+        return value.isWellFormed() ? undefined : "has a string with a lone surrogate";
+    if (typeof value === "number") {
+        // From 1e21 up JSON writes numbers in exponent form, which every peer reads as a float.
+        if (Number.isInteger(value) && !Number.isSafeInteger(value) && Math.abs(value) < 1e21) {
+            return `has the integer ${value}, past 2^53, which a JSON number can't carry exactly; send it as a string`;
+        }
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    if (depth >= MAX_JSON_DEPTH)
+        return `nests deeper than ${MAX_JSON_DEPTH} levels`;
+    for (const [key, item] of Object.entries(value)) {
+        if (!key.isWellFormed())
+            return "has a key with a lone surrogate";
+        const problem = portabilityProblem(item, depth + 1);
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+}
+// structuredClone is not available in the workflow isolate; state values are JSON by contract.
+const jsonClone = (value) => JSON.parse(JSON.stringify(value));
+const escape = (segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+function toOp(patch) {
+    const op = {
+        op: patch.op,
+        path: patch.path.map((s) => `/${escape(s)}`).join(""),
+    };
+    if (patch.op !== "remove")
+        op.value = jsonClone(patch.value);
+    return op;
+}
+// Python writes an append as "/-"; an add at an array's current length means the same thing.
+function toOps(base, patches) {
+    let value = base;
+    return patches.flatMap((patch) => {
+        const op = toOp(patch);
+        const index = patch.path.at(-1);
+        const parent = patch.path
+            .slice(0, -1)
+            .reduce((v, key) => v[key], value);
+        // immer checks `key in base`, so deleting an absent key named like an inherited member
+        // (`toString`) comes out as a remove of a path that does not exist.
+        if (patch.op === "remove" && !Array.isArray(parent) && !Object.hasOwn(parent, index))
+            return [];
+        if (patch.op === "add" && Array.isArray(parent) && index === parent.length)
+            op.path = `${op.path.slice(0, -String(index).length)}-`;
+        value = applyPatches(value, [patch]);
+        return [op];
+    });
+}
+export class StateRef {
+    #current;
+    #version = 0;
+    #mutating = false;
+    #schema;
+    #publish;
+    stateId;
+    constructor(stateId, decl, publish, data) {
+        this.stateId = stateId;
+        this.#schema = decl.schema;
+        this.#current = freeze(this.#schema.parse(decl.initial(data)), true);
+        this.#publish = publish;
+    }
+    /** The committed value. Deeply frozen: change it only through `mutate` or `set`. */
+    get current() {
+        return this.#current;
+    }
+    get version() {
+        return this.#version;
+    }
+    snapshot() {
+        return {
+            type: "state_snapshot",
+            state_id: this.stateId,
+            version: this.#version,
+            value: jsonClone(this.#current),
+        };
+    }
+    /** Apply `recipe` to a draft and publish what it changed. Synchronous by contract. */
+    mutate(recipe) {
+        if (this.#mutating)
+            throw new HarnessStateError(`state ${this.stateId} already has an open mutate() block`);
+        this.#mutating = true;
+        try {
+            const [next, patches] = produceWithPatches(this.#current, (draft) => {
+                const returned = recipe(draft);
+                if (returned instanceof Promise) {
+                    throw new HarnessStateError(`mutate() on state ${this.stateId} must be synchronous; it must not span an await`);
+                }
+            });
+            const ops = toOps(this.#current, patches);
+            if (ops.length === 0)
+                return;
+            this.#commit(next, ops);
+        }
+        finally {
+            this.#mutating = false;
+        }
+    }
+    /** Replace the whole value (one `replace` op at the root). */
+    set(value) {
+        if (this.#mutating)
+            throw new HarnessStateError(`state ${this.stateId} cannot be set() inside its open mutate() block`);
+        const next = this.#schema.parse(value);
+        this.#commit(next, [{ op: "replace", path: "", value: jsonClone(next) }]);
+    }
+    // Validates but commits `next` itself, so the published ops describe exactly the committed value.
+    #commit(next, ops) {
+        const validated = this.#schema.safeParse(next);
+        if (!validated.success) {
+            throw new HarnessStateError(`state ${this.stateId}: the change does not fit its schema: ${validated.error.message}`);
+        }
+        const problem = portabilityProblem(next);
+        if (problem !== undefined)
+            throw new HarnessStateError(`state ${this.stateId}: the change ${problem}`);
+        this.#current = freeze(castDraft(next), true);
+        this.#version += 1;
+        this.#publish({ type: "state_patch", state_id: this.stateId, version: this.#version, ops });
+    }
+}

package/dist/src/harness/stream-context.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const TurnStreamContextSchema: z.ZodObject<{
+    turn_id: z.ZodString;
+    turn_number: z.ZodNumber;
+    message_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodString;
+}, z.core.$strip>;
+export type TurnStreamContext = z.output<typeof TurnStreamContextSchema>;

package/dist/src/harness/stream-context.js

@@ -0,0 +1,9 @@
+// Identifies the in-flight turn for code that publishes to the agent's stream from outside the
+// workflow, e.g. an activity (Python's stream_context.py).
+import { z } from "zod";
+export const TurnStreamContextSchema = z.object({
+    turn_id: z.string(),
+    turn_number: z.number().int(),
+    message_id: z.string().nullable().default(null),
+    agent_id: z.string(),
+});

package/dist/src/harness/subagent-toolset.d.ts

@@ -0,0 +1,29 @@
+import { type AgentWorkflow, type AnyHarnessTool } from "./agent.ts";
+export declare const SubagentToolPolicy: {
+    /** Every handler its author marked model_callable (the default). */
+    allowModelCallable: () => {
+        allowedNames: string[] | null;
+        includeNonModelCallable: boolean;
+    };
+    allowOnly: (...names: string[]) => {
+        allowedNames: string[];
+        includeNonModelCallable: boolean;
+    };
+    dangerouslyAllowAll: () => {
+        allowedNames: string[] | null;
+        includeNonModelCallable: boolean;
+    };
+};
+export type SubagentToolPolicy = ReturnType<typeof SubagentToolPolicy.allowModelCallable>;
+/**
+ * Tools that let a model start, message, and stop instances of another agent as subagents:
+ * `start_<key>`, one `<key>_<handler>` per selected handler, and `stop_<key>`. Each send tool takes
+ * the handle as `subagent` and the handler's input under its `inputName`.
+ */
+export declare function subagentToolset(agent: AgentWorkflow, options: {
+    key: string;
+    taskQueue: string;
+    workflowType?: string;
+    tools?: SubagentToolPolicy;
+    initData?: () => unknown;
+}): AnyHarnessTool[];

package/dist/src/harness/subagent-toolset.js

@@ -0,0 +1,87 @@
+// Subagents as tools (Python's subagent_toolset.py): a model starts, messages, and stops instances
+// of another agent through `start_<key>`, one `<key>_<handler>` per selected handler, and
+// `stop_<key>`.
+import { z } from "zod";
+import { currentToolCall } from "./agent-workflow.js";
+import { tool } from "./agent.js";
+export const SubagentToolPolicy = {
+    /** Every handler its author marked model_callable (the default). */
+    allowModelCallable: () => ({
+        allowedNames: null,
+        includeNonModelCallable: false,
+    }),
+    allowOnly: (...names) => ({ allowedNames: names, includeNonModelCallable: true }),
+    dangerouslyAllowAll: () => ({
+        allowedNames: null,
+        includeNonModelCallable: true,
+    }),
+};
+/**
+ * Tools that let a model start, message, and stop instances of another agent as subagents:
+ * `start_<key>`, one `<key>_<handler>` per selected handler, and `stop_<key>`. Each send tool takes
+ * the handle as `subagent` and the handler's input under its `inputName`.
+ */
+export function subagentToolset(agent, options) {
+    const def = agent.definition;
+    const { key, taskQueue } = options;
+    const workflowType = options.workflowType ?? def.name;
+    if (options.initData !== undefined && def.initData === undefined) {
+        throw new TypeError(`initData was given, but ${def.name} takes no init data.`);
+    }
+    if (options.initData === undefined && def.initData?.required) {
+        throw new TypeError(`${def.name} requires init data, so subagentToolset needs an initData callback that supplies it.`);
+    }
+    const policy = options.tools ?? SubagentToolPolicy.allowModelCallable();
+    const selected = Object.entries(def.handlers).filter(([name, h]) => (policy.allowedNames === null || policy.allowedNames.includes(name)) &&
+        (h.modelCallable || policy.includeNonModelCallable));
+    if (selected.length === 0) {
+        throw new TypeError(`${def.name} exposes no handlers under the given SubagentToolPolicy, so it has no callable surface.`);
+    }
+    for (const [name, h] of selected) {
+        if (h.inputName === "subagent")
+            throw new TypeError(`${def.name}.${name} names its input 'subagent', which its send tool uses for the handle.`);
+    }
+    const start = tool({
+        name: `start_${key}`,
+        description: `Start a new ${key} subagent and return its short handle. Call this first; then pass the returned handle as the ` +
+            `\`subagent\` argument to the ${key}_* tools to drive that instance, and to stop_${key} to shut it down. You may ` +
+            `start several instances to work on subtasks in parallel — each returns its own handle.`,
+        inputSchema: z.object({}),
+        outputSchema: z.string(),
+        execute: async () => {
+            const { runner } = currentToolCall(`start_${key}`);
+            let data = options.initData?.();
+            if (def.initData !== undefined && data !== undefined && data !== null)
+                data = def.initData.schema.parse(data);
+            else if (def.initData?.required)
+                throw new TypeError(`initData returned ${data}, but the ${key} subagent requires data.`);
+            return runner.startSubagent(key, workflowType, taskQueue, { data: data ?? undefined });
+        },
+    });
+    const sends = selected.map(([name, h]) => tool({
+        name: `${key}_${name}`,
+        description: `${h.description}\n\nSends this to the ${key} subagent identified by \`subagent\` (the handle returned by ` +
+            `start_${key}) and returns its reply. Send several messages to the same handle to have that instance expand on ` +
+            `or clarify its earlier work.`,
+        inputSchema: z.object({ subagent: z.string(), [h.inputName]: h.input }),
+        outputSchema: h.output,
+        execute: async (input) => {
+            const { runner } = currentToolCall(`${key}_${name}`);
+            const subagent = input.subagent;
+            const payload = jsonClone(h.input.parse(input[h.inputName]));
+            return h.output.parse(await runner.runSubagentTurn(subagent, name, payload));
+        },
+    }));
+    const stop = tool({
+        name: `stop_${key}`,
+        description: `Stop the ${key} subagent identified by \`subagent\` (the handle returned by start_${key}). Use it when that instance's work is done.`,
+        inputSchema: z.object({ subagent: z.string() }),
+        outputSchema: z.string(),
+        execute: async ({ subagent }) => {
+            await currentToolCall(`stop_${key}`).runner.stopSubagent(subagent);
+            return `stopped subagent '${subagent}'`;
+        },
+    });
+    return [start, ...sends, stop];
+}
+const jsonClone = (value) => JSON.parse(JSON.stringify(value));

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./harness/agent-protocol/index.ts";
+export * from "./harness/agent.ts";
+export * from "./harness/subagent-toolset.ts";
+export { AgentWorkflowRunner, ToolApprovalDenied, CallbackToolError, type HandlerDecl, type HandlerImpl, } from "./harness/agent-workflow.ts";
+export { state, StateRef, HarnessStateError, type StateDecl } from "./harness/state/index.ts";
+export { codeModeTool, codeModeTypeCheck, renderHostInterface, renderTypeCheckStubs, type CodeModeTool, FileTree, InMemoryFileSystem, Mount, osError, type FileStat, type FileSystem, FsError, type OsErrorType, type Seed, } from "./harness/code-mode/index.ts";
+export { activityFilesystem, activityName, MAX_VIEW_BYTES, type ActivityFilesystem, } from "./harness/code-mode/activity-fs.ts";
+export { FileIndex, indexTrack } from "./harness/code-mode/vfs.ts";
+export { okfBundleVfsMount, vfsMount } from "./harness/code-mode/mount-decl.ts";
+export { OKF_VERSION } from "./harness/code-mode/okf.ts";
+export { okfCodeModeTool } from "./harness/code-mode/okf-tool.ts";
+export { jevEvaluator, buildRequest as jevBuildRequest, decide as jevDecide, DEFAULT_JEV_MODEL, } from "./ai-sdks/jev/evaluator.ts";

package/dist/src/index.js

@@ -0,0 +1,13 @@
+// Workflow-safe authoring surface: import this from agent workflow modules.
+export * from "./harness/agent-protocol/index.js";
+export * from "./harness/agent.js";
+export * from "./harness/subagent-toolset.js";
+export { AgentWorkflowRunner, ToolApprovalDenied, CallbackToolError, } from "./harness/agent-workflow.js";
+export { state, StateRef, HarnessStateError } from "./harness/state/index.js";
+export { codeModeTool, codeModeTypeCheck, renderHostInterface, renderTypeCheckStubs, FileTree, InMemoryFileSystem, Mount, osError, FsError, } from "./harness/code-mode/index.js";
+export { activityFilesystem, activityName, MAX_VIEW_BYTES, } from "./harness/code-mode/activity-fs.js";
+export { FileIndex, indexTrack } from "./harness/code-mode/vfs.js";
+export { okfBundleVfsMount, vfsMount } from "./harness/code-mode/mount-decl.js";
+export { OKF_VERSION } from "./harness/code-mode/okf.js";
+export { okfCodeModeTool } from "./harness/code-mode/okf-tool.js";
+export { jevEvaluator, buildRequest as jevBuildRequest, decide as jevDecide, DEFAULT_JEV_MODEL, } from "./ai-sdks/jev/evaluator.js";

package/dist/src/sandbox.d.ts

@@ -0,0 +1,12 @@
+// Globals Temporal's workflow sandbox provides that the workflow-safe package uses. It compiles
+// without the DOM's or Node's global types, so a browser or Node API fails to compile here;
+// these few are declared as the sandbox has them.
+
+declare class TextEncoder {
+  encode(input?: string): Uint8Array;
+}
+
+declare class TextDecoder {
+  constructor(label?: string, options?: { fatal?: boolean });
+  decode(input?: Uint8Array): string;
+}

package/package.json

@@ -1,6 +1,98 @@
 {
   "name": "@temporalio/agent-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Temporal-native agent harness for TypeScript: the workflow-safe authoring API for durable agents.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./harness/agent-protocol": {
+      "types": "./dist/src/harness/agent-protocol/index.d.ts",
+      "default": "./dist/src/harness/agent-protocol/index.js"
+    },
+    "./harness/agent-schema": {
+      "types": "./dist/src/harness/agent-schema.d.ts",
+      "default": "./dist/src/harness/agent-schema.js"
+    },
+    "./harness/agent-workflow": {
+      "types": "./dist/src/harness/agent-workflow.d.ts",
+      "default": "./dist/src/harness/agent-workflow.js"
+    },
+    "./harness/code-mode": {
+      "types": "./dist/src/harness/code-mode/index.d.ts",
+      "default": "./dist/src/harness/code-mode/index.js"
+    },
+    "./harness/code-mode/vfs": {
+      "types": "./dist/src/harness/code-mode/vfs.d.ts",
+      "default": "./dist/src/harness/code-mode/vfs.js"
+    },
+    "./harness/code-mode/okf": {
+      "types": "./dist/src/harness/code-mode/okf.d.ts",
+      "default": "./dist/src/harness/code-mode/okf.js"
+    },
+    "./ai-sdks/google-genai-plugin": {
+      "types": "./dist/src/ai-sdks/google-genai-plugin/index.d.ts",
+      "default": "./dist/src/ai-sdks/google-genai-plugin/index.js"
+    },
+    "./ai-sdks/jev/evaluator": {
+      "types": "./dist/src/ai-sdks/jev/evaluator.d.ts",
+      "default": "./dist/src/ai-sdks/jev/evaluator.js"
+    },
+    "./ai-sdks/openai-agents-harness": {
+      "types": "./dist/src/ai-sdks/openai-agents-harness.d.ts",
+      "default": "./dist/src/ai-sdks/openai-agents-harness.js"
+    }
+  },
+  "files": [
+    "dist/src"
+  ],
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@temporalio/agent-harness-client": "^0.1.0",
+    "@temporalio/common": "^1.24.0",
+    "@temporalio/workflow": "^1.24.0",
+    "@temporalio/workflow-streams": "^1.24.0",
+    "immer": "^11.1.18",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@google/genai": "^2.31.0",
+    "@openai/agents-core": "~0.14.3",
+    "@temporalio/openai-agents": "^1.24.0"
+  },
+  "peerDependenciesMeta": {
+    "@google/genai": {
+      "optional": true
+    },
+    "@openai/agents-core": {
+      "optional": true
+    },
+    "@temporalio/openai-agents": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@google/genai": "^2.31.0",
+    "@openai/agents-core": "~0.14.3",
+    "@temporalio/openai-agents": "^1.24.0",
+    "@types/node": "^22.20.4",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporal-community/temporal-agent-harness.git",
+    "directory": "typescript/packages/core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }