@temporalio/agent-harness 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,369 @@
+import { z } from "zod";
+export declare const SEND_AGENT_MESSAGE_UPDATE = "send_agent_message";
+export declare const TOOL_APPROVAL_UPDATE = "tool_approval";
+export declare const PROVIDE_CALLBACK_RESULT_UPDATE = "provide_callback_result";
+export declare const AGENT_STATUS_QUERY = "agent_status";
+export declare const AGENT_INTERFACE_QUERY = "agent_interface";
+export declare const CLOSE_SIGNAL = "close";
+export declare const AGENT_ID_LENGTH = 6;
+export declare const APPROVAL_SHORT_ID_LENGTH = 6;
+export declare const MidTurn: {
+    readonly ENQUEUE: "enqueue";
+    readonly REJECT: "reject";
+    readonly ACCEPT: "accept";
+};
+export type MidTurn = (typeof MidTurn)[keyof typeof MidTurn];
+export declare const MessageDisposition: {
+    readonly OPENED: "opened";
+    readonly JOINED: "joined";
+    readonly QUEUED: "queued";
+};
+export type MessageDisposition = (typeof MessageDisposition)[keyof typeof MessageDisposition];
+/** What an auto-mode evaluator decides, named after AI SDK 7's tool-approval outcomes. */
+export declare const ApprovalVerdict: {
+    readonly APPROVED: "approved";
+    readonly DENIED: "denied";
+    readonly USER_APPROVAL: "user-approval";
+    readonly NOT_APPLICABLE: "not-applicable";
+};
+export type ApprovalVerdict = (typeof ApprovalVerdict)[keyof typeof ApprovalVerdict];
+/** The verdict as it goes on the wire (auto_approval_evaluation_* events), as in Python. */
+export declare const AutoApprovalVerdict: {
+    readonly APPROVE: "approve";
+    readonly DENY: "deny";
+    readonly ESCALATE: "escalate";
+};
+export type AutoApprovalVerdict = (typeof AutoApprovalVerdict)[keyof typeof AutoApprovalVerdict];
+/** Both of the evaluator's "not mine to decide" outcomes leave the call to a human. */
+export declare const WIRE_VERDICT: Readonly<Record<ApprovalVerdict, AutoApprovalVerdict>>;
+export declare const ToolApprovalPolicySchema: z.ZodObject<{
+    dangerously_skip_all_approvals: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0 | 1>, z.ZodString]>, z.ZodTransform<boolean, string | 0 | 1 | boolean>>>;
+    auto_approve_inherently_safe: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0 | 1>, z.ZodString]>, z.ZodTransform<boolean, string | 0 | 1 | boolean>>>;
+    auto_approve_tools: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
+    auto_mode_enabled: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0 | 1>, z.ZodString]>, z.ZodTransform<boolean, string | 0 | 1 | boolean>>>;
+}, z.core.$strict>;
+export type ToolApprovalPolicy = z.output<typeof ToolApprovalPolicySchema>;
+export declare const ToolApprovalPolicy: {
+    parse: (value: unknown) => ToolApprovalPolicy;
+    alwaysRequireHumanApproval: () => ToolApprovalPolicy;
+    allowInherentlySafe: () => ToolApprovalPolicy;
+    allowTools: (tools: Iterable<string>, { alsoInherentlySafe }?: {
+        alsoInherentlySafe?: boolean | undefined;
+    }) => ToolApprovalPolicy;
+    autoMode: ({ preApprovedTools, preApproveInherentlySafe, }?: {
+        preApproveInherentlySafe?: boolean | undefined;
+        preApprovedTools?: Iterable<string> | undefined;
+    }) => ToolApprovalPolicy;
+    dangerouslySkipAll: () => ToolApprovalPolicy;
+    withChanges: (policy: ToolApprovalPolicy, changes: Partial<ToolApprovalPolicy>) => ToolApprovalPolicy;
+    withToolAllowed: (policy: ToolApprovalPolicy, toolName: string) => ToolApprovalPolicy;
+    withAutoMode: (policy: ToolApprovalPolicy, enabled: boolean) => ToolApprovalPolicy;
+    /** Layers 0-2: dispatch with no gate and no approval events at all. */
+    autoApproves(policy: ToolApprovalPolicy, toolName: string, { inherentlySafe }: {
+        inherentlySafe: boolean;
+    }): boolean;
+    /** Layer 3: whether a call the static layers did not approve goes to the auto mode evaluator. */
+    consultsAutoMode(policy: ToolApprovalPolicy, toolName: string, opts: {
+        inherentlySafe: boolean;
+    }): boolean;
+};
+export declare const AutoApprovalCriteriaSetSchema: z.ZodObject<{
+    effect: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    approve_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    deny_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    escalate_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    min_confidence: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+    escalate_if_irreversible_above: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+}, z.core.$strip>;
+export type AutoApprovalCriteriaSet = z.output<typeof AutoApprovalCriteriaSetSchema>;
+export declare const AutoApprovalCriteriaSchema: z.ZodObject<{
+    sets: z.ZodPrefault<z.ZodPipe<z.ZodPreprocess<z.ZodMap<z.ZodString, z.ZodObject<{
+        effect: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        approve_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deny_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        escalate_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        min_confidence: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+        escalate_if_irreversible_above: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+    }, z.core.$strip>>, unknown>, z.ZodTransform<Record<string, {
+        effect: string | null;
+        approve_when: string[];
+        deny_when: string[];
+        escalate_when: string[];
+        min_confidence: number | null;
+        escalate_if_irreversible_above: number | null;
+    }> & {
+        [k: string]: {
+            effect: string | null;
+            approve_when: string[];
+            deny_when: string[];
+            escalate_when: string[];
+            min_confidence: number | null;
+            escalate_if_irreversible_above: number | null;
+        };
+    }, Map<string, {
+        effect: string | null;
+        approve_when: string[];
+        deny_when: string[];
+        escalate_when: string[];
+        min_confidence: number | null;
+        escalate_if_irreversible_above: number | null;
+    }>>>>;
+    tools: z.ZodPrefault<z.ZodPipe<z.ZodPreprocess<z.ZodMap<z.ZodString, z.ZodString>, unknown>, z.ZodTransform<Record<string, string> & {
+        [k: string]: string;
+    }, Map<string, string>>>>;
+    default: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    context: z.ZodPrefault<z.ZodPipe<z.ZodPreprocess<z.ZodMap<z.ZodString, z.ZodUnknown>, unknown>, z.ZodTransform<Record<string, unknown> & {
+        [k: string]: unknown;
+    }, Map<string, unknown>>>>;
+    min_confidence: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>;
+    escalate_if_irreversible_above: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+}, z.core.$strip>;
+export type AutoApprovalCriteria = z.output<typeof AutoApprovalCriteriaSchema>;
+export type Thresholds = readonly [
+    minConfidence: number,
+    escalateIfIrreversibleAbove: number | null
+];
+export declare const AutoApprovalCriteria: {
+    parse: (value: unknown) => AutoApprovalCriteria;
+    empty: () => AutoApprovalCriteria;
+    criteriaSet: (value: z.input<typeof AutoApprovalCriteriaSetSchema>) => AutoApprovalCriteriaSet;
+    isEmptySet: (s: AutoApprovalCriteriaSet) => boolean;
+    /** Precedence: runtime/config assignment, then the tool's declared set, then the catch-all. */
+    setNameFor: (c: AutoApprovalCriteria, toolName: string, declared?: string | null) => string | null;
+    /** The set judging `toolName`, or null when there is nothing to judge against (escalate). */
+    forTool(c: AutoApprovalCriteria, toolName: string, declared?: string | null): AutoApprovalCriteriaSet | null;
+    thresholdsForSet(c: AutoApprovalCriteria, s: AutoApprovalCriteriaSet | null): Thresholds;
+    withSet: (c: AutoApprovalCriteria, name: string, s: AutoApprovalCriteriaSet) => AutoApprovalCriteria;
+    withToolAssigned: (c: AutoApprovalCriteria, toolName: string, setName: string) => AutoApprovalCriteria;
+};
+export interface AutoApprovalDecision {
+    verdict: ApprovalVerdict;
+    reason?: string | null;
+    details?: Record<string, unknown>;
+}
+export interface AutoApprovalContext {
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    inherently_safe: boolean;
+    tool_description: string | null;
+    criteria: AutoApprovalCriteria;
+    criteria_version: number;
+    criteria_set: AutoApprovalCriteriaSet;
+    criteria_set_name: string;
+    thresholds: Thresholds;
+}
+/** Async on purpose: the gate races it against a human and cancels the loser. */
+export type AutoModeEvaluator = ((ctx: AutoApprovalContext) => Promise<AutoApprovalDecision>) & {
+    /** Published as `evaluator` on the evaluation events; defaults to the function name. */
+    evaluatorLabel?: string;
+};
+export declare const AgentConfigSchema: z.ZodObject<{
+    approval_policy: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        dangerously_skip_all_approvals: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0 | 1>, z.ZodString]>, z.ZodTransform<boolean, string | 0 | 1 | boolean>>>;
+        auto_approve_inherently_safe: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0 | 1>, z.ZodString]>, z.ZodTransform<boolean, string | 0 | 1 | boolean>>>;
+        auto_approve_tools: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
+        auto_mode_enabled: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<0 | 1>, z.ZodString]>, z.ZodTransform<boolean, string | 0 | 1 | boolean>>>;
+    }, z.core.$strict>>>, z.ZodTransform<{
+        dangerously_skip_all_approvals: boolean;
+        auto_approve_inherently_safe: boolean;
+        auto_approve_tools: string[];
+        auto_mode_enabled: boolean;
+    } | null, {
+        dangerously_skip_all_approvals: boolean;
+        auto_approve_inherently_safe: boolean;
+        auto_approve_tools: string[];
+        auto_mode_enabled: boolean;
+    } | null | undefined>>;
+    auto_approval_criteria: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        sets: z.ZodPrefault<z.ZodPipe<z.ZodPreprocess<z.ZodMap<z.ZodString, z.ZodObject<{
+            effect: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            approve_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            deny_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            escalate_when: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            min_confidence: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+            escalate_if_irreversible_above: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+        }, z.core.$strip>>, unknown>, z.ZodTransform<Record<string, {
+            effect: string | null;
+            approve_when: string[];
+            deny_when: string[];
+            escalate_when: string[];
+            min_confidence: number | null;
+            escalate_if_irreversible_above: number | null;
+        }> & {
+            [k: string]: {
+                effect: string | null;
+                approve_when: string[];
+                deny_when: string[];
+                escalate_when: string[];
+                min_confidence: number | null;
+                escalate_if_irreversible_above: number | null;
+            };
+        }, Map<string, {
+            effect: string | null;
+            approve_when: string[];
+            deny_when: string[];
+            escalate_when: string[];
+            min_confidence: number | null;
+            escalate_if_irreversible_above: number | null;
+        }>>>>;
+        tools: z.ZodPrefault<z.ZodPipe<z.ZodPreprocess<z.ZodMap<z.ZodString, z.ZodString>, unknown>, z.ZodTransform<Record<string, string> & {
+            [k: string]: string;
+        }, Map<string, string>>>>;
+        default: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        context: z.ZodPrefault<z.ZodPipe<z.ZodPreprocess<z.ZodMap<z.ZodString, z.ZodUnknown>, unknown>, z.ZodTransform<Record<string, unknown> & {
+            [k: string]: unknown;
+        }, Map<string, unknown>>>>;
+        min_confidence: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>;
+        escalate_if_irreversible_above: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>, z.ZodTransform<number, string | number | boolean>>, z.ZodNumber>>>;
+    }, z.core.$strip>>>, z.ZodTransform<{
+        sets: Record<string, {
+            effect: string | null;
+            approve_when: string[];
+            deny_when: string[];
+            escalate_when: string[];
+            min_confidence: number | null;
+            escalate_if_irreversible_above: number | null;
+        }> & {
+            [k: string]: {
+                effect: string | null;
+                approve_when: string[];
+                deny_when: string[];
+                escalate_when: string[];
+                min_confidence: number | null;
+                escalate_if_irreversible_above: number | null;
+            };
+        };
+        tools: Record<string, string> & {
+            [k: string]: string;
+        };
+        default: string | null;
+        context: Record<string, unknown> & {
+            [k: string]: unknown;
+        };
+        min_confidence: number;
+        escalate_if_irreversible_above: number | null;
+    } | null, {
+        sets: Record<string, {
+            effect: string | null;
+            approve_when: string[];
+            deny_when: string[];
+            escalate_when: string[];
+            min_confidence: number | null;
+            escalate_if_irreversible_above: number | null;
+        }> & {
+            [k: string]: {
+                effect: string | null;
+                approve_when: string[];
+                deny_when: string[];
+                escalate_when: string[];
+                min_confidence: number | null;
+                escalate_if_irreversible_above: number | null;
+            };
+        };
+        tools: Record<string, string> & {
+            [k: string]: string;
+        };
+        default: string | null;
+        context: Record<string, unknown> & {
+            [k: string]: unknown;
+        };
+        min_confidence: number;
+        escalate_if_irreversible_above: number | null;
+    } | null | undefined>>;
+    agent_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+}, z.core.$strip>;
+export type AgentConfig = z.output<typeof AgentConfigSchema>;
+export type AgentConfigInput = z.input<typeof AgentConfigSchema>;
+export declare const messagePayload: z.ZodDefault<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+export declare const AgentMessageSchema: z.ZodObject<{
+    type: z.ZodString;
+    payload: z.ZodDefault<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+}, z.core.$strip>;
+export type AgentMessage = z.output<typeof AgentMessageSchema>;
+export declare const TextMessage: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+export declare const TextReply: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+export interface MessageContext {
+    joined_turn: boolean;
+    turn_id: string;
+    turn_number: number;
+    message_id: string;
+}
+export interface AgentMessageReply {
+    turn_number: number;
+    turn_id: string;
+    message_id: string;
+    disposition: MessageDisposition;
+    accepted_offset: number;
+}
+export declare const ToolApprovalDecisionSchema: z.ZodObject<{
+    tool_id: z.ZodString;
+    approved: z.ZodBoolean;
+    reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    remember: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ToolApprovalDecision = z.output<typeof ToolApprovalDecisionSchema>;
+export interface ToolApprovalResult {
+    tool_id: string;
+    accepted: boolean;
+}
+export declare const CallbackResultSchema: z.ZodObject<{
+    tool_id: z.ZodString;
+    result: z.ZodDefault<z.ZodUnknown>;
+    error: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+}, z.core.$strip>;
+export type CallbackResult = z.output<typeof CallbackResultSchema>;
+export interface CallbackResultAck {
+    tool_id: string;
+    accepted: boolean;
+}
+/** `turn_id` guards against cancelling a turn that opened after the caller looked. */
+export interface PendingApproval {
+    tool_id: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    turn_number: number;
+    short_id: string;
+}
+export interface PendingCallback {
+    tool_id: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    output_schema: Record<string, unknown>;
+    turn_number: number;
+}
+export interface PendingTurn {
+    turn_number: number;
+    turn_id: string;
+    message_id: string;
+    message: string;
+}
+export interface SubagentInfo {
+    subagent_id: string;
+    agent_key: string;
+    workflow_id: string;
+}
+export interface AgentStatus {
+    agent_id: string;
+    current_turn: number;
+    turn_active: boolean;
+    turn_participants: number;
+    pending_turns: PendingTurn[];
+    pending_approvals: PendingApproval[];
+    pending_callbacks: PendingCallback[];
+    subagents: SubagentInfo[];
+    approval_policy: ToolApprovalPolicy;
+    has_auto_approval_evaluator: boolean;
+}
+/** One turn of the current run (a continued run keeps its last 20), as the `agent_state` query indexes it. */
+export interface AcceptedFunction {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    output: Record<string, unknown>;
+    mid_turn: MidTurn;
+    model_callable: boolean;
+}

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

@@ -0,0 +1,222 @@
+// The agent's callable interface: the signal/update/query names an agent workflow and its clients
+// share, the validated input models (zod, in place of pydantic), and the wire types (Python's
+// agent_protocol/agent_interface.py). Every wire shape is snake_case JSON, identical to the Python
+// harness, so the packaged UI, `@temporalio/agent-harness-client` and the Go connectors work against
+// either backend. Workflow-sandbox safe (zod only).
+import { z } from "zod";
+export const SEND_AGENT_MESSAGE_UPDATE = "send_agent_message";
+export const TOOL_APPROVAL_UPDATE = "tool_approval";
+export const PROVIDE_CALLBACK_RESULT_UPDATE = "provide_callback_result";
+export const AGENT_STATUS_QUERY = "agent_status";
+export const AGENT_INTERFACE_QUERY = "agent_interface";
+export const CLOSE_SIGNAL = "close";
+export const AGENT_ID_LENGTH = 6;
+export const APPROVAL_SHORT_ID_LENGTH = 6;
+export const MidTurn = { ENQUEUE: "enqueue", REJECT: "reject", ACCEPT: "accept" };
+export const MessageDisposition = { OPENED: "opened", JOINED: "joined", QUEUED: "queued" };
+/** What an auto-mode evaluator decides, named after AI SDK 7's tool-approval outcomes. */
+export const ApprovalVerdict = {
+    APPROVED: "approved",
+    DENIED: "denied",
+    USER_APPROVAL: "user-approval",
+    NOT_APPLICABLE: "not-applicable",
+};
+/** The verdict as it goes on the wire (auto_approval_evaluation_* events), as in Python. */
+export const AutoApprovalVerdict = {
+    APPROVE: "approve",
+    DENY: "deny",
+    ESCALATE: "escalate",
+};
+/** Both of the evaluator's "not mine to decide" outcomes leave the call to a human. */
+export const WIRE_VERDICT = {
+    approved: "approve",
+    denied: "deny",
+    "user-approval": "escalate",
+    "not-applicable": "escalate",
+};
+const AGENT_ID_PATTERN = new RegExp(`^[0-9a-f]{${AGENT_ID_LENGTH}}(-[0-9a-f]{${AGENT_ID_LENGTH}})*$`);
+// The values pydantic's lax mode coerces, so a config Python accepts parses here too.
+const TRUE_STRINGS = new Set(["true", "1", "yes", "on", "t", "y"]);
+const FALSE_STRINGS = new Set(["false", "0", "no", "off", "f", "n"]);
+const laxBool = z
+    .union([
+    z.boolean(),
+    z.literal([0, 1]),
+    z
+        .string()
+        .refine((s) => TRUE_STRINGS.has(s.toLowerCase()) || FALSE_STRINGS.has(s.toLowerCase()), {
+        message: "Input should be a valid boolean, unable to interpret input",
+    }),
+])
+    .transform((v) => typeof v === "string" ? TRUE_STRINGS.has(v.toLowerCase()) : typeof v === "number" ? v === 1 : v);
+// Python float() syntax for a finite decimal, digits optionally grouped by single underscores.
+const DIGITS = String.raw `\d(?:_?\d)*`;
+const NUMERIC_STRING = new RegExp(String.raw `^\s*[+-]?(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:[eE][+-]?${DIGITS})?\s*$`);
+const unit = z
+    .union([
+    z.number(),
+    z.boolean(),
+    z
+        .string()
+        .regex(NUMERIC_STRING, "Input should be a valid number, unable to parse string as a number"),
+])
+    .transform((v) => Number(typeof v === "string" ? v.replaceAll("_", "") : v))
+    .pipe(z.number().min(0).max(1));
+// ---------------------------------------------------------------------------------------------
+// Tool-approval policy. A plain, serializable value; derive the next one with the functions on
+// `ToolApprovalPolicy`, which re-validate (the cross-field invariant included).
+// ---------------------------------------------------------------------------------------------
+export const ToolApprovalPolicySchema = z
+    .strictObject({
+    dangerously_skip_all_approvals: laxBool.default(false),
+    auto_approve_inherently_safe: laxBool.default(false),
+    auto_approve_tools: z
+        .array(z.string())
+        .default([])
+        .transform((tools) => [...new Set(tools)].sort()),
+    auto_mode_enabled: laxBool.default(false),
+})
+    .refine((p) => !(p.dangerously_skip_all_approvals && p.auto_mode_enabled), {
+    message: "dangerously_skip_all_approvals=True approves every call outright, so no call is ever gated and " +
+        "auto mode could never be consulted. Set one or the other: skip approvals entirely, or enable " +
+        "auto mode over a policy that actually gates.",
+});
+export const ToolApprovalPolicy = {
+    parse: (value) => ToolApprovalPolicySchema.parse(value),
+    alwaysRequireHumanApproval: () => ToolApprovalPolicySchema.parse({}),
+    allowInherentlySafe: () => ToolApprovalPolicySchema.parse({ auto_approve_inherently_safe: true }),
+    allowTools: (tools, { alsoInherentlySafe = false } = {}) => ToolApprovalPolicySchema.parse({
+        auto_approve_tools: [...tools],
+        auto_approve_inherently_safe: alsoInherentlySafe,
+    }),
+    autoMode: ({ preApprovedTools = [], preApproveInherentlySafe = false, } = {}) => ToolApprovalPolicySchema.parse({
+        auto_approve_tools: [...preApprovedTools],
+        auto_approve_inherently_safe: preApproveInherentlySafe,
+        auto_mode_enabled: true,
+    }),
+    dangerouslySkipAll: () => ToolApprovalPolicySchema.parse({ dangerously_skip_all_approvals: true }),
+    withChanges: (policy, changes) => ToolApprovalPolicySchema.parse({ ...policy, ...changes }),
+    withToolAllowed: (policy, toolName) => ToolApprovalPolicySchema.parse({
+        ...policy,
+        auto_approve_tools: [...policy.auto_approve_tools, toolName],
+    }),
+    withAutoMode: (policy, enabled) => ToolApprovalPolicySchema.parse({ ...policy, auto_mode_enabled: enabled }),
+    /** Layers 0-2: dispatch with no gate and no approval events at all. */
+    autoApproves(policy, toolName, { inherentlySafe }) {
+        if (policy.dangerously_skip_all_approvals)
+            return true;
+        if (inherentlySafe && policy.auto_approve_inherently_safe)
+            return true;
+        return policy.auto_approve_tools.includes(toolName);
+    },
+    /** Layer 3: whether a call the static layers did not approve goes to the auto mode evaluator. */
+    consultsAutoMode(policy, toolName, opts) {
+        return !ToolApprovalPolicy.autoApproves(policy, toolName, opts) && policy.auto_mode_enabled;
+    },
+};
+// ---------------------------------------------------------------------------------------------
+// Auto-approval criteria: the named rule sets an auto mode evaluator judges gated calls against.
+// ---------------------------------------------------------------------------------------------
+export const AutoApprovalCriteriaSetSchema = z.object({
+    effect: z.string().nullable().default(null),
+    approve_when: z.array(z.string()).default([]),
+    deny_when: z.array(z.string()).default([]),
+    escalate_when: z.array(z.string()).default([]),
+    min_confidence: unit.nullable().default(null),
+    escalate_if_irreversible_above: unit.nullable().default(null),
+});
+// z.record assigns into a plain object, where a "__proto__" key sets the prototype and vanishes.
+const ownRecord = (value) => z
+    .preprocess((v, ctx) => {
+    if (typeof v === "object" && v !== null && !Array.isArray(v))
+        return new Map(Object.entries(v));
+    ctx.addIssue({ code: "invalid_type", expected: "record", input: v });
+    return z.NEVER;
+}, z.map(z.string(), value))
+    .transform((m) => Object.assign(Object.create(null), Object.fromEntries(m)))
+    .prefault({});
+export const AutoApprovalCriteriaSchema = z.object({
+    sets: ownRecord(AutoApprovalCriteriaSetSchema),
+    tools: ownRecord(z.string()),
+    default: z.string().nullable().default(null),
+    context: ownRecord(z.unknown()),
+    min_confidence: unit.default(0.8),
+    escalate_if_irreversible_above: unit.nullable().default(0.5),
+});
+const own = (record, key) => Object.hasOwn(record, key) ? record[key] : undefined;
+export const AutoApprovalCriteria = {
+    parse: (value) => AutoApprovalCriteriaSchema.parse(value),
+    empty: () => AutoApprovalCriteriaSchema.parse({}),
+    criteriaSet: (value) => AutoApprovalCriteriaSetSchema.parse(value),
+    isEmptySet: (s) => !(s.effect || s.approve_when.length || s.deny_when.length || s.escalate_when.length),
+    /** Precedence: runtime/config assignment, then the tool's declared set, then the catch-all. */
+    setNameFor: (c, toolName, declared) => own(c.tools, toolName) || declared || c.default,
+    /** The set judging `toolName`, or null when there is nothing to judge against (escalate). */
+    forTool(c, toolName, declared) {
+        const name = AutoApprovalCriteria.setNameFor(c, toolName, declared);
+        const found = name === null ? undefined : own(c.sets, name);
+        return found === undefined || AutoApprovalCriteria.isEmptySet(found) ? null : found;
+    },
+    thresholdsForSet(c, s) {
+        if (s === null)
+            return [c.min_confidence, c.escalate_if_irreversible_above];
+        return [
+            s.min_confidence ?? c.min_confidence,
+            s.escalate_if_irreversible_above ?? c.escalate_if_irreversible_above,
+        ];
+    },
+    withSet: (c, name, s) => ({
+        ...c,
+        sets: Object.assign(Object.create(null), c.sets, { [name]: s }),
+    }),
+    withToolAssigned: (c, toolName, setName) => ({
+        ...c,
+        tools: Object.assign(Object.create(null), c.tools, { [toolName]: setName }),
+    }),
+};
+// ---------------------------------------------------------------------------------------------
+// Standardized agent input and messages
+// ---------------------------------------------------------------------------------------------
+export const AgentConfigSchema = z.object({
+    approval_policy: ToolApprovalPolicySchema.nullish().transform((v) => v ?? null),
+    auto_approval_criteria: AutoApprovalCriteriaSchema.nullish().transform((v) => v ?? null),
+    agent_id: z
+        .string()
+        .regex(AGENT_ID_PATTERN)
+        .nullish()
+        .transform((v) => v ?? null),
+});
+// Not z.record, which rebuilds the object and drops a "__proto__" key.
+export const messagePayload = z
+    .custom((v) => typeof v === "object" && v !== null && !Array.isArray(v), "Expected an object")
+    .default({});
+export const AgentMessageSchema = z.object({
+    type: z.string(),
+    payload: messagePayload,
+});
+// Schemas as Python's pydantic models publish them (field titles included), for wire parity.
+export const TextMessage = z.object({ text: z.string().meta({ title: "Text" }) }).meta({
+    title: "TextMessage",
+    description: "Free-form natural-language text from the user (the input to a plain chat handler).",
+});
+export const TextReply = z.object({ text: z.string().meta({ title: "Text" }) }).meta({
+    title: "TextReply",
+    description: "A free-form natural-language reply (the output of a plain chat handler).",
+});
+export const ToolApprovalDecisionSchema = z.object({
+    tool_id: z.string(),
+    approved: z.boolean(),
+    reason: z
+        .string()
+        .nullish()
+        .transform((v) => v ?? null),
+    remember: z.boolean().default(false),
+});
+export const CallbackResultSchema = z.object({
+    tool_id: z.string(),
+    result: z.unknown().default(null),
+    error: z
+        .string()
+        .nullish()
+        .transform((v) => v ?? null),
+});

package/dist/src/harness/agent-protocol/events.d.ts

@@ -0,0 +1,10 @@
+import type { Protocol } from "@temporalio/agent-harness-client";
+export type AgentEvent = Protocol.AgentEvent;
+export type AgentStreamItem = Protocol.AgentStreamItem;
+export type AgentEventType = Protocol.AgentEventType;
+export type TokenUsage = Protocol.TokenUsage;
+export type JsonValue = Protocol.JsonValue;
+export type StreamEventOf<T extends AgentEventType> = Extract<AgentStreamItem, {
+    type: T;
+}>;
+export declare const TURN_EVENTS_TOPIC = "turn_events";

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

@@ -0,0 +1,6 @@
+// The agent's event-stream vocabulary (Python's agent_protocol/events.py). The event types are not
+// redeclared here: they are the generated `Protocol` namespace of `@temporalio/agent-harness-client`,
+// itself generated from contract/protocol.schema.json, so a payload this backend publishes is
+// type-checked against exactly what the client and UI parse.
+// The pubsub topic the agent publishes its turn events on.
+export const TURN_EVENTS_TOPIC = "turn_events";

package/dist/src/harness/agent-protocol/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./events.ts";
+export * from "./agent-interface.ts";
+export * from "./subagent-interface.ts";
+export * from "./schema.ts";
+export { TurnStreamContextSchema, type TurnStreamContext } from "../stream-context.ts";

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

@@ -0,0 +1,7 @@
+// The agent protocol (Python's agent_protocol package): the event vocabulary, the agent's callable
+// interface, and the subagent-turn contract.
+export * from "./events.js";
+export * from "./agent-interface.js";
+export * from "./subagent-interface.js";
+export * from "./schema.js";
+export { TurnStreamContextSchema } from "../stream-context.js";

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

@@ -0,0 +1,34 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from "@standard-schema/spec";
+/** Standard Schema (`~standard.validate`) plus Standard JSON Schema (`~standard.jsonSchema`). */
+export interface Schema<I = unknown, O = I> {
+    readonly "~standard": StandardSchemaV1.Props<I, O> & StandardJSONSchemaV1.Props<I, O>;
+}
+export type InferInput<S extends Schema> = StandardTypedV1.InferInput<S>;
+export type InferOutput<S extends Schema> = StandardTypedV1.InferOutput<S>;
+/**
+ * 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 declare function toJsonSchema(schema: Schema, io?: "input" | "output"): Record<string, unknown>;
+/** Validate synchronously; schemas with async refinements are rejected. */
+export declare function validate<S extends Schema>(schema: S, value: unknown): {
+    ok: true;
+    value: InferOutput<S>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * 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 declare function jsonSchema<T = unknown>(schema: Record<string, unknown>, options?: {
+    validate?: (value: unknown) => {
+        ok: true;
+        value: T;
+    } | {
+        ok: false;
+        message: string;
+    };
+}): Schema<T>;