@temporalio/agent-harness 0.0.0-stage → 0.2.0

package/dist/src/harness/agent-protocol/schema.js

@@ -0,0 +1,53 @@
+// Schemas: any Standard Schema that can also render JSON Schema (zod v4 is one), or raw JSON
+// Schema wrapped with `jsonSchema()`. The harness needs JSON Schema for agent_interface, model
+// tool declarations and Code Mode stubs, and synchronous validation (update validators are sync).
+// TypeScript only: Python's models are pydantic's, which carry both.
+/**
+ * JSON Schema of a schema: what it accepts (`input`, the default) or what parsing returns (`output`).
+ * zod renders each mode as it behaves: an input object is open, since parsing ignores extra keys,
+ * and an output object is closed.
+ */
+export function toJsonSchema(schema, io = "input") {
+    const libraryOptions = { unrepresentable: "any" };
+    const { $schema: _drop, ...rest } = schema["~standard"].jsonSchema[io]({
+        target: "draft-2020-12",
+        libraryOptions,
+    });
+    return rest;
+}
+/** Validate synchronously; schemas with async refinements are rejected. */
+export function validate(schema, value) {
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise)
+        throw new TypeError("harness schemas must validate synchronously");
+    if (result.issues === undefined)
+        return { ok: true, value: result.value };
+    return {
+        ok: false,
+        message: result.issues
+            .map((i) => (i.path?.length
+            ? `${i.path.map((p) => String(typeof p === "object" ? p.key : p)).join(".")}: `
+            : "") + i.message)
+            .join("; "),
+    };
+}
+/**
+ * Raw JSON Schema as a harness schema (the AI SDK's `jsonSchema()` counterpart). Values pass
+ * unchecked unless `validate` is given, so prefer a schema library where input is untrusted.
+ */
+export function jsonSchema(schema, options = {}) {
+    const render = () => schema;
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "temporal-agent-harness",
+            validate(value) {
+                if (options.validate === undefined)
+                    return { value: value };
+                const r = options.validate(value);
+                return r.ok ? { value: r.value } : { issues: [{ message: r.message }] };
+            },
+            jsonSchema: { input: render, output: render },
+        },
+    };
+}

package/dist/src/harness/agent-protocol/subagent-interface.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const RUN_SUBAGENT_TURN_ACTIVITY = "run_subagent_turn";
+export declare const DEFAULT_SUBAGENT_HEARTBEAT_TIMEOUT = "20 seconds";
+export declare const DEFAULT_SUBAGENT_START_TO_CLOSE_TIMEOUT = "1 hour";
+export declare const RunSubagentTurnInputSchema: z.ZodObject<{
+    child_workflow_id: z.ZodString;
+    type: z.ZodString;
+    payload: z.ZodDefault<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+    from_offset: z.ZodDefault<z.ZodNumber>;
+    handle: z.ZodString;
+    agent_key: z.ZodString;
+    parent_stream_context: 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>;
+}, z.core.$strip>;
+export type RunSubagentTurnInput = z.output<typeof RunSubagentTurnInputSchema>;
+export interface SubagentTurnResult {
+    output: Record<string, unknown>;
+    turn_id: string;
+    turn_number: number;
+    consumed_offset: number;
+}

package/dist/src/harness/agent-protocol/subagent-interface.js

@@ -0,0 +1,17 @@
+// The subagent-turn activity contract between a parent agent's workflow and the harness activity
+// that drives one turn on a child (Python's agent_protocol/subagent_interface.py).
+import { z } from "zod";
+import { messagePayload } from "./agent-interface.js";
+import { TurnStreamContextSchema } from "../stream-context.js";
+export const RUN_SUBAGENT_TURN_ACTIVITY = "run_subagent_turn";
+export const DEFAULT_SUBAGENT_HEARTBEAT_TIMEOUT = "20 seconds";
+export const DEFAULT_SUBAGENT_START_TO_CLOSE_TIMEOUT = "1 hour";
+export const RunSubagentTurnInputSchema = z.object({
+    child_workflow_id: z.string(),
+    type: z.string(),
+    payload: messagePayload,
+    from_offset: z.number().int().default(0),
+    handle: z.string(),
+    agent_key: z.string(),
+    parent_stream_context: TurnStreamContextSchema,
+});

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

@@ -0,0 +1,4 @@
+import type { AgentWorkflow } from "./agent.ts";
+type Json = Record<string, unknown>;
+export declare function agentSchema(agent: AgentWorkflow, source: string): Json;
+export {};

package/dist/src/harness/agent-schema.js

@@ -0,0 +1,106 @@
+// `temporal-agent-harness schema`: an agent's init data, handlers and observable state as one JSON
+// Schema document, in the shape @temporal-agent-harness/codegen consumes. Each model becomes a
+// `$defs` entry named by its zod `.meta({ title })`, else by where it appears; a titled object
+// nested inside one gets its own entry too. Init data and handler inputs are in input mode (a
+// defaulted field may be omitted by a sender); handler outputs and states in output mode (every
+// field arrives). A model whose two modes differ appears as `Name-Input` and `Name-Output`, as
+// pydantic names them.
+import { toJsonSchema } from "./agent-protocol/index.js";
+// Refs are written as `PENDING name \0 io` and resolved once every model has been seen, because
+// whether a name splits into -Input/-Output depends on all of them.
+const PENDING = "\0pending:";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const LITERAL_KEYS = new Set(["default", "const", "enum", "examples"]);
+export function agentSchema(agent, source) {
+    const def = agent.definition;
+    const found = new Map();
+    const owners = new Map();
+    const register = (name, io, body) => {
+        const modes = found.get(name) ?? {};
+        const prior = modes[io];
+        if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(body))
+            throw collision(name);
+        found.set(name, { ...modes, [io]: body });
+        return { $ref: `${PENDING}${name}\0${io}` };
+    };
+    const collision = (name) => new Error(`${def.name}: two different models are both named '${name}'; give each a unique .meta({ title })`);
+    const hoist = (node, io, top) => {
+        if (Array.isArray(node))
+            return node.map((n) => hoist(n, io, false));
+        if (!isObject(node))
+            return node;
+        const out = Object.fromEntries(Object.entries(node).map(([k, v]) => [k, LITERAL_KEYS.has(k) ? v : hoist(v, io, false)]));
+        return !top && typeof out.title === "string" && out.type === "object"
+            ? register(out.title, io, out)
+            : out;
+    };
+    // zod's own `$defs` (a recursive model's) are lifted as they are, so their refs still resolve.
+    const lifted = {};
+    const ref = (schema, io, fallback) => {
+        const { $defs: inner = {}, ...generated } = toJsonSchema(schema, io);
+        for (const [key, value] of Object.entries(inner)) {
+            if (key in lifted && JSON.stringify(lifted[key]) !== JSON.stringify(value))
+                throw collision(key);
+            lifted[key] = value;
+        }
+        const body = hoist(generated, io, true);
+        const name = typeof body.title === "string" ? body.title : fallback;
+        const seen = owners.get(name) ?? new Set();
+        if (seen.add(schema).size > 1)
+            throw collision(name);
+        owners.set(name, seen);
+        return register(name, io, body);
+    };
+    const pascal = (s) => s.replace(/(^|_)(\w)/g, (_m, _p, c) => c.toUpperCase());
+    const doc = {
+        agent: def.name,
+        source,
+        init_data: def.initData === undefined
+            ? null
+            : {
+                data: ref(def.initData.schema, "input", `${def.name}InitData`),
+                required: def.initData.required,
+            },
+        handlers: Object.fromEntries(Object.entries(def.handlers)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, h]) => [
+            name,
+            {
+                description: h.description,
+                mid_turn: h.midTurn,
+                input: ref(h.input, "input", `${pascal(name)}Input`),
+                output: ref(h.output, "output", `${pascal(name)}Output`),
+            },
+        ])),
+        states: Object.fromEntries(Object.entries(def.states ?? {}).map(([id, decl]) => [
+            id,
+            ref(decl.schema, "output", pascal(id)),
+        ])),
+    };
+    const split = new Set([...found]
+        .filter(([, m]) => m.input && m.output && JSON.stringify(m.input) !== JSON.stringify(m.output))
+        .map(([n]) => n));
+    const defs = { ...lifted };
+    for (const [name, { input, output }] of found) {
+        if (split.has(name))
+            Object.assign(defs, { [`${name}-Input`]: input, [`${name}-Output`]: output });
+        else
+            defs[name] = input ?? output;
+    }
+    doc.$defs = Object.fromEntries(Object.entries(defs).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    const resolve = (node) => {
+        if (Array.isArray(node))
+            return node.map(resolve);
+        if (!isObject(node))
+            return node;
+        if (typeof node.$ref === "string" && node.$ref.startsWith(PENDING)) {
+            const [name = "", io] = node.$ref.slice(PENDING.length).split("\0");
+            return {
+                ...node,
+                $ref: `#/$defs/${split.has(name) ? `${name}-${io === "input" ? "Input" : "Output"}` : name}`,
+            };
+        }
+        return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, LITERAL_KEYS.has(k) ? v : resolve(v)]));
+    };
+    return resolve(doc);
+}

package/dist/src/harness/agent-workflow/errors.d.ts

@@ -0,0 +1,26 @@
+import type { AutoModeEvaluator, ToolApprovalPolicy } from "../agent-protocol/index.ts";
+export declare class ToolApprovalDenied extends Error {
+    name: string;
+    readonly toolName: string;
+    readonly reason: string | null;
+    constructor(toolName: string, reason: string | null);
+}
+export declare class CallbackToolError extends Error {
+    name: string;
+    readonly toolName: string;
+    readonly reason: string | null;
+    constructor(toolName: string, reason: string | null);
+}
+/** What Python's `str(e)` gives for an exception: its message alone. */
+export declare function errorMessage(e: unknown): string;
+/**
+ * Whether `e` is the cancellation of the scope this code runs in (Python's CancelledError, which
+ * `except Exception` lets through), not a cancellation it observed from an inner scope, such as an
+ * author's own timeout, which is a failure like any other.
+ */
+export declare function isOwnCancellation(e: unknown): boolean;
+/** An error and its causes, deduplicated: an ActivityFailure's own message says only "Activity task failed". */
+export declare function errorText(e: unknown): string;
+/** Rejects JSON a Python peer can't read back as sent. */
+export declare function assertPortableJson(value: unknown, what: string): void;
+export declare function assertAutoModeHasEvaluator(policy: ToolApprovalPolicy, evaluator: AutoModeEvaluator | undefined): void;

package/dist/src/harness/agent-workflow/errors.js

@@ -0,0 +1,67 @@
+import { ApplicationFailure, CancellationScope, isCancellation } from "@temporalio/workflow";
+import { portabilityProblem } from "../state/index.js";
+export class ToolApprovalDenied extends Error {
+    name = "ToolApprovalDenied";
+    toolName;
+    reason;
+    constructor(toolName, reason) {
+        super(`tool '${toolName}' was not approved${reason ? `: ${reason}` : ""}`);
+        this.toolName = toolName;
+        this.reason = reason;
+    }
+}
+export class CallbackToolError extends Error {
+    name = "CallbackToolError";
+    toolName;
+    reason;
+    constructor(toolName, reason) {
+        super(`callback tool '${toolName}' failed${reason ? `: ${reason}` : ""}`);
+        this.toolName = toolName;
+        this.reason = reason;
+    }
+}
+/** What Python's `str(e)` gives for an exception: its message alone. */
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Whether `e` is the cancellation of the scope this code runs in (Python's CancelledError, which
+ * `except Exception` lets through), not a cancellation it observed from an inner scope, such as an
+ * author's own timeout, which is a failure like any other.
+ */
+export function isOwnCancellation(e) {
+    return isCancellation(e) && CancellationScope.current().consideredCancelled;
+}
+/** An error and its causes, deduplicated: an ActivityFailure's own message says only "Activity task failed". */
+export function errorText(e) {
+    const parts = [];
+    let current = e;
+    while (current instanceof Error && parts.length < 5) {
+        const text = current.message || current.name;
+        if (!parts.includes(text))
+            parts.push(text);
+        current = current.cause;
+    }
+    return parts.length ? parts.join(": ") : String(e);
+}
+/** Rejects JSON a Python peer can't read back as sent. */
+export function assertPortableJson(value, what) {
+    const problem = portabilityProblem(value);
+    if (problem !== undefined)
+        throw ApplicationFailure.create({
+            type: "NonPortableJson",
+            nonRetryable: true,
+            message: `${what} ${problem}`,
+        });
+}
+export function assertAutoModeHasEvaluator(policy, evaluator) {
+    if (evaluator !== undefined || !policy.auto_mode_enabled)
+        return;
+    throw ApplicationFailure.create({
+        type: "AutoModeWithoutEvaluator",
+        nonRetryable: true,
+        message: "ToolApprovalPolicy has auto_mode_enabled=True, but this agent has no autoModeEvaluator wired, so " +
+            "nothing could ever judge a call while the policy reported auto mode on. Either pass " +
+            "autoModeEvaluator (jevEvaluator() is the builtin), or use a policy with auto mode off.",
+    });
+}

package/dist/src/harness/agent-workflow/types.d.ts

@@ -0,0 +1,88 @@
+import type { z } from "zod";
+import type { AgentMessage, AutoApprovalCriteria, AutoModeEvaluator, MessageContext, MidTurn, Schema, ToolApprovalPolicy } from "../agent-protocol/index.ts";
+import type { StateDecl } from "../state/index.ts";
+/** One `@agent.accepts`-style handler declaration: the static half, discoverable without a run. */
+export interface HandlerDecl<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
+    readonly description: string;
+    readonly input: I;
+    readonly output: O;
+    readonly midTurn: MidTurn;
+    readonly modelCallable: boolean;
+    /** The input's parameter name (Python's handler parameter); a subagent send tool's argument. */
+    readonly inputName: string;
+}
+export type HandlerImpl<D extends HandlerDecl> = (message: z.output<D["input"]>, ctx: MessageContext) => Promise<z.input<D["output"]>>;
+export interface Admission {
+    message: AgentMessage;
+    turn_id: string;
+    turn_number: number;
+    message_id: string;
+    /** Stream offset of the message's message_accepted; absent in runs carried before it was kept. */
+    accepted_offset?: number;
+}
+export interface ApprovalEntry {
+    tool_id: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    turn_number: number;
+    turn_id: string;
+    message_id: string | null;
+    short_id: string;
+    inherently_safe: boolean;
+    status: "pending" | "approved" | "denied";
+    reason: string | null;
+    remember: boolean;
+}
+export interface CallbackEntry {
+    tool_id: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    output_schema: Record<string, unknown>;
+    output: Schema;
+    turn_number: number;
+    turn_id: string;
+    message_id: string | null;
+    status: "pending" | "resolved";
+    outcome: "ok" | "error" | "timeout";
+    result: unknown;
+    error: string | null;
+}
+export interface SubagentInstance {
+    handle: string;
+    workflow_id: string;
+    agent_key: string;
+    last_consumed_offset: number;
+    next_ticket: number;
+    serving: number;
+}
+export interface RunnerOptions {
+    handlers: Readonly<Record<string, HandlerDecl>>;
+    approvalPolicyDefault: ToolApprovalPolicy;
+    autoApprovalCriteriaDefault?: AutoApprovalCriteria | undefined;
+    autoModeEvaluator?: AutoModeEvaluator | undefined;
+    states?: Readonly<Record<string, AnyStateDecl>> | undefined;
+    /** The agent's validated init data, handed to each state's `initial`. */
+    data?: unknown;
+}
+export type AnyStateDecl = StateDecl<z.ZodType<Record<string, unknown>>>;
+export type ObjectSchema = Schema<Record<string, unknown>, Record<string, unknown>>;
+/**
+ * A harness tool: the AI SDK tool shape (`description`, `inputSchema`, optional `outputSchema`,
+ * `execute`) plus where it runs and how it is gated. A tool with no `execute` is a callback tool,
+ * fulfilled by a client against its required `outputSchema`.
+ */
+export interface HarnessTool<I = Record<string, unknown>, O = unknown> {
+    readonly kind: "inline" | "activity" | "callback";
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ObjectSchema;
+    readonly outputSchema: Schema | undefined;
+    readonly inherentlySafe: boolean;
+    readonly autoApprovalCriteria: string | null;
+    readonly injected: readonly string[];
+    /** The model-facing JSON schema of the arguments (injected parameters are not in it). */
+    readonly parameters: Record<string, unknown>;
+    /** Run the call. Only valid inside `runner.runTool(...)`. */
+    invoke(input: I): Promise<O>;
+}
+export type AnyHarnessTool = HarnessTool<never, unknown>;

package/dist/src/harness/agent-workflow/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,79 @@
+import { WorkflowStream } from "@temporalio/workflow-streams/workflow";
+import { AutoApprovalCriteria, ToolApprovalPolicy, type AgentConfig, type AgentStatus, type AgentStreamItem, type Schema, type TurnStreamContext } from "./agent-protocol/index.ts";
+import { StateRef } from "./state/index.ts";
+import { CallbackToolError, ToolApprovalDenied, errorText } from "./agent-workflow/errors.ts";
+import type { Admission, HandlerDecl, HandlerImpl, RunnerOptions, SubagentInstance } from "./agent-workflow/types.ts";
+export { CallbackToolError, ToolApprovalDenied, errorText, };
+export type { Admission, HandlerDecl, HandlerImpl, RunnerOptions, SubagentInstance, };
+export interface ToolCall {
+    readonly runner: AgentWorkflowRunner;
+    readonly toolId: string;
+    readonly injections: Readonly<Record<string, unknown>>;
+}
+export declare const messageIdStore: ALS<T>;
+export declare const toolCallStore: ALS<T>;
+/** The in-flight tool call, or throw: tools must be invoked through `runner.runTool`. */
+export declare function currentToolCall(what: string): ToolCall;
+export declare const AMBIENT: unique symbol;
+export declare class AgentWorkflowRunner {
+    #private;
+    readonly agentId: string;
+    readonly stream: WorkflowStream;
+    constructor(config: AgentConfig, options: RunnerOptions);
+    get closed(): boolean;
+    /** The live turn context, stamped with the ambient participant's message id; null when idle. */
+    get currentStreamContext(): TurnStreamContext | null;
+    get approvalPolicy(): ToolApprovalPolicy;
+    /** Install a new policy; pending calls it now allow-lists are approved in the same step. */
+    setApprovalPolicy(policy: ToolApprovalPolicy): void;
+    get autoApprovalCriteria(): AutoApprovalCriteria;
+    setAutoApprovalCriteria(criteria: AutoApprovalCriteria): void;
+    assignToolCriteria(toolName: string, criteriaSet: string): void;
+    get status(): AgentStatus;
+    /** Publish a payload on the current turn, attributed to the ambient message. */
+    publish(event: AgentStreamItem): void;
+    /**
+     * Run one tool call with its id and injections in scope; every harness tool needs this. A tool
+     * picked by a model at run time takes its (unvalidated) JSON arguments; the tool validates them.
+     */
+    runTool<I, O>(callId: string, tool: {
+        name?: string;
+        invoke(input: I): Promise<O>;
+    }, input: I, options?: {
+        injections?: Record<string, unknown>;
+    }): Promise<O>;
+    runTool<O>(callId: string, tool: {
+        name?: string;
+        invoke(input: never): Promise<O>;
+    }, input: unknown, options?: {
+        injections?: Record<string, unknown>;
+    }): Promise<O>;
+    /** Declared state: each snapshot was published at construction, then every committed mutation. */
+    readonly state: Readonly<Record<string, StateRef<Record<string, unknown>>>>;
+    run(impls: Readonly<Record<string, HandlerImpl<HandlerDecl>>>): Promise<void>;
+    /** @internal Enforce the approval policy for the in-flight tool call. Throws ToolApprovalDenied. */
+    applyApprovalPolicy(toolId: string, toolName: string, toolInput: Record<string, unknown>, opts: {
+        inherentlySafe: boolean;
+        description: string | null;
+        autoApprovalCriteria: string | null;
+    }): Promise<void>;
+    /** @internal The generic body of a callback tool: park until a client provides the result. */
+    awaitCallbackResult(args: {
+        toolId: string;
+        toolName: string;
+        toolInput: Record<string, unknown>;
+        output: Schema;
+        outputSchema: Record<string, unknown>;
+        timeout: string | number | undefined;
+    }): Promise<unknown>;
+    /** Start a child agent; returns its short, tree-unique handle (also its agent_id). */
+    startSubagent(agentKey: string, workflowType: string, taskQueue: string, { config, data }?: {
+        config?: Partial<AgentConfig>;
+        data?: unknown;
+    }): Promise<string>;
+    stopSubagent(handle: string): Promise<void>;
+    /** Send one message to a subagent and await its reply. Turns to one subagent run FIFO. */
+    runSubagentTurn(handle: string, msgType: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** @internal Stamp the envelope and publish. `messageId` defaults to the ambient participant. */
+    pub(turnId: string, turnNumber: number, event: AgentStreamItem, messageId?: string | null | typeof AMBIENT): void;
+}