@temporalio/agent-harness 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temporal Technologies Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,6 @@
-# Temporary Holding Version
+# @temporalio/agent-harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The workflow-safe authoring API of the Temporal agent harness: `defineAgent`, handlers, tools,
+approvals, state and the protocol, with no Node dependencies. Agents written with it run on a
+worker from [`@temporalio/agent-harness-worker`](../worker/README.md), whose README also shows how
+to serve them to the harness's server and console.

package/dist/src/ai-sdks/google-genai-plugin/index.d.ts

@@ -0,0 +1,6 @@
+export { InteractionConversation, type FunctionCallStep, type FunctionResultStepParam, type InteractionReply, } from "./interactions-conversation.ts";
+export type { InteractionResult } from "./interactions-models.ts";
+export { functionParam } from "./interactions-workflow.ts";
+export { TemporalAsyncClient } from "./temporal-async-client.ts";
+export { GEMINI_INTERACTIONS_CREATE_STREAMED_ACTIVITY, TemporalAsyncInteractionStream, TemporalAsyncInteractions, type GeminiInteractionsActivity, type InteractionCreateParamsStreaming, } from "./temporal-interactions.ts";
+export { googleGenaiClient } from "./workflow.ts";

package/dist/src/ai-sdks/google-genai-plugin/index.js

@@ -0,0 +1,24 @@
+// The Google Gemini integration's workflow side (Python's google_genai_plugin). Experimental.
+//
+// `googleGenaiClient` gives workflow code a Gemini client whose network calls run as activities on
+// the worker's real client, registered by `GoogleGenAIPlugin` from
+// `@temporalio/agent-harness-worker/ai-sdks/google-genai-plugin`; no credentials enter the
+// workflow or its history. The Interactions API has no automatic function calling, so the workflow
+// drives the tool loop: declare tools with `functionParam`, keep the conversation in an
+// `InteractionConversation`, and run each call with `runner.runTool`.
+//
+//   const gemini = googleGenaiClient({ runner });
+//   conversation.addUserText(text);
+//   while (true) {
+//     const stream = await gemini.interactions.create({
+//       model, input: conversation.steps, tools: tools.map(functionParam), stream: true,
+//     });
+//     const reply = await conversation.readReply(stream);
+//     if (reply.functionCalls.length === 0) return reply.text;
+//     conversation.addFunctionResults(await Promise.all(reply.functionCalls.map(runCall)));
+//   }
+export { InteractionConversation, } from "./interactions-conversation.js";
+export { functionParam } from "./interactions-workflow.js";
+export { TemporalAsyncClient } from "./temporal-async-client.js";
+export { GEMINI_INTERACTIONS_CREATE_STREAMED_ACTIVITY, TemporalAsyncInteractionStream, TemporalAsyncInteractions, } from "./temporal-interactions.js";
+export { googleGenaiClient } from "./workflow.js";

package/dist/src/ai-sdks/google-genai-plugin/interactions-conversation.d.ts

@@ -0,0 +1,35 @@
+import type { Interactions } from "@google/genai";
+/** A function call the model made. The API sends a `signature` the SDK's type does not declare. */
+export type FunctionCallStep = Interactions.FunctionCallStep & {
+    signature?: string;
+};
+/** The result of one function call, to send back with `addFunctionResults`. */
+export type FunctionResultStepParam = Interactions.FunctionResultStep & {
+    signature?: string;
+};
+/** One model reply: its text, the function calls it made, and the interaction's id. */
+export interface InteractionReply {
+    text: string;
+    functionCalls: FunctionCallStep[];
+    interactionId: string;
+}
+/**
+ * The steps of one conversation with a Gemini model, oldest first. Pass `steps` as the `input` of
+ * every `interactions.create`, without `previous_interaction_id`.
+ */
+export declare class InteractionConversation {
+    #private;
+    /** The whole conversation, to send as `input`. */
+    get steps(): Interactions.Step[];
+    addUserText(text: string): void;
+    /** The results of the function calls in the last reply, in any order. */
+    addFunctionResults(results: Iterable<FunctionResultStepParam>): void;
+    /**
+     * Read one streamed `interactions.create` to its end and add the model's steps.
+     *
+     * The steps are added only once the stream completes, so a failed call leaves the conversation
+     * as it was. Throws an ApplicationFailure on an error event, on a stream that ends without
+     * completing, and (non-retryably) on a step this conversation cannot carry back to the model.
+     */
+    readReply(stream: AsyncIterable<Interactions.InteractionSSEEvent>): Promise<InteractionReply>;
+}

package/dist/src/ai-sdks/google-genai-plugin/interactions-conversation.js

@@ -0,0 +1,178 @@
+// A Gemini Interactions conversation that the workflow holds and sends whole on every call
+// (Python's _interactions_conversation.py).
+//
+// Why not chain with `previous_interaction_id`: the API rebuilds a chained conversation from the
+// stored interactions, and a STREAMED interaction stores only its own steps. The rebuild reads the
+// previous interaction and the one before it, no further, so once two streamed interactions follow
+// each other the rebuilt conversation starts partway through, at a function result whose call is
+// missing, and the API rejects the next function result with 400 "Please ensure that function
+// response turn comes immediately after a function call turn". A tool-calling loop that streams
+// every model call hits that on its third tool result.
+//
+// So the conversation lives here, in workflow state, and goes out as the `input` of every
+// `interactions.create`. That also makes the workflow the record of what the model was told: a
+// replay, a retry or a restarted worker sends exactly the same conversation. The cost is that
+// every model call carries the whole conversation in its activity input.
+//
+// A typical tool-calling turn:
+//
+//   conversation.addUserText(text);
+//   while (true) {
+//     const stream = await gemini.interactions.create({
+//       model, input: conversation.steps, tools, stream: true,
+//     });
+//     const reply = await conversation.readReply(stream);
+//     if (reply.functionCalls.length === 0) return reply.text;
+//     conversation.addFunctionResults(await runCalls(reply.functionCalls));
+//   }
+import { ApplicationFailure } from "@temporalio/workflow";
+/**
+ * The steps of one conversation with a Gemini model, oldest first. Pass `steps` as the `input` of
+ * every `interactions.create`, without `previous_interaction_id`.
+ */
+export class InteractionConversation {
+    #steps = [];
+    /** The whole conversation, to send as `input`. */
+    get steps() {
+        return [...this.#steps];
+    }
+    addUserText(text) {
+        this.#steps.push({ type: "user_input", content: [{ type: "text", text }] });
+    }
+    /** The results of the function calls in the last reply, in any order. */
+    addFunctionResults(results) {
+        for (const result of results)
+            this.#steps.push({ ...result });
+    }
+    /**
+     * Read one streamed `interactions.create` to its end and add the model's steps.
+     *
+     * The steps are added only once the stream completes, so a failed call leaves the conversation
+     * as it was. Throws an ApplicationFailure on an error event, on a stream that ends without
+     * completing, and (non-retryably) on a step this conversation cannot carry back to the model.
+     */
+    async readReply(stream) {
+        const thoughts = new Map();
+        const calls = new Map();
+        const args = new Map();
+        const outputs = new Map();
+        let interactionId = null;
+        for await (const event of stream) {
+            switch (event.event_type) {
+                case "error":
+                    throw ApplicationFailure.create({
+                        type: event.error?.code || "stream_error",
+                        message: event.error?.message || "stream error",
+                    });
+                case "step.start": {
+                    const { index, step } = event;
+                    if (step.type === "thought") {
+                        const thought = { type: "thought" };
+                        if (step.signature)
+                            thought.signature = step.signature;
+                        if (step.summary?.length)
+                            thought.summary = step.summary.map(textParam);
+                        thoughts.set(index, thought);
+                    }
+                    else if (step.type === "function_call") {
+                        calls.set(index, step);
+                    }
+                    else if (step.type === "model_output") {
+                        outputs.set(index, (step.content ?? []).map((c) => textParam(c).text).join(""));
+                    }
+                    else {
+                        throw unsupported(`produced a '${step.type}' step`);
+                    }
+                    break;
+                }
+                case "step.delta": {
+                    const { index, delta } = event;
+                    const thought = thoughts.get(index);
+                    if (delta.type === "text" && outputs.has(index)) {
+                        outputs.set(index, outputs.get(index) + (delta.text ?? ""));
+                    }
+                    else if (delta.type === "arguments_delta" && calls.has(index)) {
+                        args.set(index, (args.get(index) ?? "") + (delta.arguments ?? ""));
+                    }
+                    else if (delta.type === "thought_signature" && thought) {
+                        if (delta.signature)
+                            thought.signature = delta.signature;
+                    }
+                    else if (delta.type === "thought_summary" && thought) {
+                        if (delta.content !== undefined)
+                            thought.summary = [...(thought.summary ?? []), textParam(delta.content)];
+                    }
+                    else {
+                        throw unsupported(`streamed a '${delta.type}' delta`);
+                    }
+                    break;
+                }
+                case "interaction.completed":
+                    interactionId = event.interaction.id;
+                    break;
+            }
+        }
+        if (interactionId === null)
+            throw ApplicationFailure.create({
+                type: "stream_error",
+                message: "stream ended without interaction.completed event",
+            });
+        const modelSteps = [];
+        const functionCalls = [];
+        const indexes = [...new Set([...thoughts.keys(), ...calls.keys(), ...outputs.keys()])];
+        for (const index of indexes.sort((a, b) => a - b)) {
+            const thought = thoughts.get(index);
+            let call = calls.get(index);
+            if (thought) {
+                modelSteps.push(thought);
+            }
+            else if (call) {
+                const raw = args.get(index);
+                if (raw !== undefined)
+                    call = { ...call, arguments: parseArguments(raw) };
+                functionCalls.push(call);
+                const callStep = {
+                    type: "function_call",
+                    id: call.id,
+                    name: call.name,
+                    arguments: call.arguments,
+                };
+                if (call.signature)
+                    callStep.signature = call.signature;
+                modelSteps.push(callStep);
+            }
+            else {
+                const text = outputs.get(index);
+                modelSteps.push(text
+                    ? { type: "model_output", content: [{ type: "text", text }] }
+                    : { type: "model_output" });
+            }
+        }
+        this.#steps.push(...modelSteps);
+        const text = [...outputs.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([, t]) => t)
+            .join("");
+        return { text, functionCalls, interactionId };
+    }
+}
+/** A text block the conversation can send back; anything else is refused. */
+function textParam(content) {
+    if (content.type !== "text" || content.annotations?.length)
+        throw unsupported(`produced ${content.type} content`);
+    return { type: "text", text: content.text };
+}
+/** A function call's arguments, from the JSON fragments streamed for it. */
+function parseArguments(raw) {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new TypeError(`function call arguments are not a JSON object: ${raw}`);
+    return parsed;
+}
+function unsupported(what) {
+    return ApplicationFailure.create({
+        type: "UnsupportedInteractionStep",
+        nonRetryable: true,
+        message: `the model ${what}, which an InteractionConversation cannot carry back to it`,
+    });
+}

package/dist/src/ai-sdks/google-genai-plugin/interactions-models.d.ts

@@ -0,0 +1,8 @@
+import type { Interactions } from "@google/genai";
+/**
+ * The `gemini_interactions_create_streamed` activity's result: every SSE event of the streamed
+ * call, verbatim and in order, so the workflow iterates them as it would the SDK's stream.
+ */
+export interface InteractionResult {
+    events: Interactions.InteractionSSEEvent[];
+}

package/dist/src/ai-sdks/google-genai-plugin/interactions-models.js

@@ -0,0 +1,4 @@
+// What crosses the activity boundary for the Interactions API (Python's _interactions_models.py).
+// The request side has no type of its own: the workflow sends the `interactions.create` params as
+// they are, plus the turn's stream context.
+export {};

package/dist/src/ai-sdks/google-genai-plugin/interactions-workflow.d.ts

@@ -0,0 +1,8 @@
+import type { Interactions } from "@google/genai";
+import type { AnyHarnessTool } from "../../harness/agent-workflow/types.ts";
+/**
+ * A harness tool as an Interactions-API function declaration, for the `tools` of
+ * `interactions.create`. The tool's name is the name the model calls it by, and its model-facing
+ * parameters (injected ones excluded) are the declared JSON schema.
+ */
+export declare function functionParam(tool: AnyHarnessTool): Interactions.Function;

package/dist/src/ai-sdks/google-genai-plugin/interactions-workflow.js

@@ -0,0 +1,15 @@
+// Workflow-side helpers for the Interactions API (Python's _interactions_workflow.py). The workflow
+// drives the tool-calling loop itself, running each call with `runner.runTool`.
+/**
+ * A harness tool as an Interactions-API function declaration, for the `tools` of
+ * `interactions.create`. The tool's name is the name the model calls it by, and its model-facing
+ * parameters (injected ones excluded) are the declared JSON schema.
+ */
+export function functionParam(tool) {
+    return {
+        type: "function",
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    };
+}

package/dist/src/ai-sdks/google-genai-plugin/temporal-async-client.d.ts

@@ -0,0 +1,10 @@
+import type { ActivityOptions } from "@temporalio/workflow";
+import type { AgentWorkflowRunner } from "../../harness/agent-workflow.ts";
+import { TemporalAsyncInteractions } from "./temporal-interactions.ts";
+export declare class TemporalAsyncClient {
+    readonly interactions: TemporalAsyncInteractions;
+    constructor({ activityConfig, runner, }?: {
+        activityConfig?: ActivityOptions;
+        runner?: AgentWorkflowRunner | null;
+    });
+}

package/dist/src/ai-sdks/google-genai-plugin/temporal-async-client.js

@@ -0,0 +1,9 @@
+// The Gemini client a workflow holds (Python's _temporal_async_client.py): each module it exposes
+// runs its network calls in activities on the worker's real client.
+import { TemporalAsyncInteractions } from "./temporal-interactions.js";
+export class TemporalAsyncClient {
+    interactions;
+    constructor({ activityConfig, runner = null, } = {}) {
+        this.interactions = new TemporalAsyncInteractions(runner, activityConfig);
+    }
+}

package/dist/src/ai-sdks/google-genai-plugin/temporal-interactions.d.ts

@@ -0,0 +1,31 @@
+import type { Interactions } from "@google/genai";
+import { type ActivityOptions } from "@temporalio/workflow";
+import type { TurnStreamContext } from "../../harness/agent-protocol/index.ts";
+import type { AgentWorkflowRunner } from "../../harness/agent-workflow.ts";
+import type { InteractionResult } from "./interactions-models.ts";
+export declare const GEMINI_INTERACTIONS_CREATE_STREAMED_ACTIVITY = "gemini_interactions_create_streamed";
+/** The params of a streamed `interactions.create`, passed to the worker's client as they are. */
+export type InteractionCreateParamsStreaming = Interactions.InteractionCreateParams.InteractionCreateParamsStreaming;
+export type GeminiInteractionsActivity = (params: InteractionCreateParamsStreaming, streamContext: TurnStreamContext | null) => Promise<InteractionResult>;
+/**
+ * The events of one streamed call, already collected by the activity. Iterate it with
+ * `for await`, as the SDK's stream; each iteration walks the same events again.
+ */
+export declare class TemporalAsyncInteractionStream implements AsyncIterable<Interactions.InteractionSSEEvent> {
+    #private;
+    constructor(events: readonly Interactions.InteractionSSEEvent[]);
+    [Symbol.asyncIterator](): AsyncIterator<Interactions.InteractionSSEEvent>;
+}
+/**
+ * The client's `interactions`. Only the streaming `create` is supported; it runs in an activity
+ * whose options default to a 3 minute start-to-close timeout.
+ */
+export declare class TemporalAsyncInteractions {
+    #private;
+    constructor(runner: AgentWorkflowRunner | null, activityConfig?: ActivityOptions);
+    /**
+     * One streamed `interactions.create`. With a runner, the activity publishes the call's events
+     * (model_interaction_started, reply_delta, tool_requested, ...) to the runner's current turn.
+     */
+    create(params: InteractionCreateParamsStreaming): Promise<TemporalAsyncInteractionStream>;
+}

package/dist/src/ai-sdks/google-genai-plugin/temporal-interactions.js

@@ -0,0 +1,43 @@
+// The workflow-side `interactions` module (Python's _temporal_interactions.py): `create` has the
+// SDK's shape but runs the call in the `gemini_interactions_create_streamed` activity, which holds
+// the worker's real client and publishes the call's turn events as it streams.
+import { proxyActivities } from "@temporalio/workflow";
+export const GEMINI_INTERACTIONS_CREATE_STREAMED_ACTIVITY = "gemini_interactions_create_streamed";
+/**
+ * The events of one streamed call, already collected by the activity. Iterate it with
+ * `for await`, as the SDK's stream; each iteration walks the same events again.
+ */
+export class TemporalAsyncInteractionStream {
+    #events;
+    constructor(events) {
+        this.#events = events;
+    }
+    async *[Symbol.asyncIterator]() {
+        yield* this.#events;
+    }
+}
+/**
+ * The client's `interactions`. Only the streaming `create` is supported; it runs in an activity
+ * whose options default to a 3 minute start-to-close timeout.
+ */
+export class TemporalAsyncInteractions {
+    #runner;
+    #activityConfig;
+    constructor(runner, activityConfig) {
+        this.#runner = runner;
+        this.#activityConfig = activityConfig ?? { startToCloseTimeout: "3 minutes" };
+    }
+    /**
+     * One streamed `interactions.create`. With a runner, the activity publishes the call's events
+     * (model_interaction_started, reply_delta, tool_requested, ...) to the runner's current turn.
+     */
+    async create(params) {
+        if (params.stream !== true)
+            throw new TypeError("TemporalAsyncInteractions only supports stream: true; pass stream: true or extend the " +
+                "shim for the non-streaming path.");
+        const streamContext = this.#runner === null ? null : this.#runner.currentStreamContext;
+        const activities = proxyActivities({ summary: "interactions.create", ...this.#activityConfig });
+        const result = await activities[GEMINI_INTERACTIONS_CREATE_STREAMED_ACTIVITY](params, streamContext);
+        return new TemporalAsyncInteractionStream(result.events);
+    }
+}

package/dist/src/ai-sdks/google-genai-plugin/workflow.d.ts

@@ -0,0 +1,16 @@
+import type { ActivityOptions } from "@temporalio/workflow";
+import type { AgentWorkflowRunner } from "../../harness/agent-workflow.ts";
+import { TemporalAsyncClient } from "./temporal-async-client.ts";
+/**
+ * A Gemini client for workflow code whose API calls run as activities on the worker's
+ * `GoogleGenAIPlugin` client, so credentials never enter the workflow or its history.
+ *
+ * `activityConfig` replaces the activity options (default: a 3 minute start-to-close timeout).
+ * With `runner`, a streamed call publishes its events (model_interaction_started, reply_delta,
+ * tool_requested, model_interaction_ended, ...) to the runner's current turn from the activity;
+ * without it, streaming still works but nothing reaches the turn's stream.
+ */
+export declare function googleGenaiClient({ activityConfig, runner, }?: {
+    activityConfig?: ActivityOptions;
+    runner?: AgentWorkflowRunner | null;
+}): TemporalAsyncClient;

package/dist/src/ai-sdks/google-genai-plugin/workflow.js

@@ -0,0 +1,14 @@
+// Workflow utilities for the Gemini integration (Python's google_genai_plugin/workflow.py).
+import { TemporalAsyncClient } from "./temporal-async-client.js";
+/**
+ * A Gemini client for workflow code whose API calls run as activities on the worker's
+ * `GoogleGenAIPlugin` client, so credentials never enter the workflow or its history.
+ *
+ * `activityConfig` replaces the activity options (default: a 3 minute start-to-close timeout).
+ * With `runner`, a streamed call publishes its events (model_interaction_started, reply_delta,
+ * tool_requested, model_interaction_ended, ...) to the runner's current turn from the activity;
+ * without it, streaming still works but nothing reaches the turn's stream.
+ */
+export function googleGenaiClient({ activityConfig, runner = null, } = {}) {
+    return new TemporalAsyncClient({ ...(activityConfig ? { activityConfig } : {}), runner });
+}

package/dist/src/ai-sdks/jev/evaluator.d.ts

@@ -0,0 +1,38 @@
+import { type ActivityOptions } from "@temporalio/workflow";
+import { type AutoApprovalContext, type AutoApprovalDecision, type AutoModeEvaluator } from "../../harness/agent-protocol/index.ts";
+export declare const JEV_TOOL_APPROVAL_ACTIVITY = "jev_tool_approval";
+export declare const DEFAULT_JEV_MODEL = "jev-latest";
+export interface JevApprovalRequest {
+    state: Record<string, unknown>;
+    questions: Record<string, Record<string, unknown>>;
+    model: string | null;
+}
+export interface JevApprovalAnswer {
+    model: string;
+    request_id: string;
+    verdict: string;
+    verdict_confidence: number;
+    verdict_probabilities: Record<string, number>;
+    irreversible: number;
+    input_tokens: number | null;
+    output_tokens: number | null;
+}
+export type ExtraState = Record<string, unknown> | ((ctx: AutoApprovalContext) => Record<string, unknown>);
+/** The jev_tool_approval activity's options; `jevEvaluator({activityOptions})` merges over them. */
+export declare const DEFAULT_ACTIVITY_OPTIONS: ActivityOptions;
+export declare function jevEvaluator({ model, extraState, activityOptions, }?: {
+    model?: string | null;
+    extraState?: ExtraState;
+    activityOptions?: ActivityOptions;
+}): AutoModeEvaluator;
+export declare function buildRequest(ctx: AutoApprovalContext, { model, extraState, }?: {
+    model?: string | null;
+    extraState?: Record<string, unknown> | undefined;
+}): JevApprovalRequest;
+/** Turn Jev's answer into a decision under the operator's thresholds. Escalates when unsure. */
+export declare function decide(answer: JevApprovalAnswer, opts: {
+    minConfidence: number;
+    escalateIfIrreversibleAbove: number | null;
+    criteriaSetName?: string;
+    criteriaVersion?: number;
+}): AutoApprovalDecision;

package/dist/src/ai-sdks/jev/evaluator.js

@@ -0,0 +1,155 @@
+// The builtin auto mode evaluator, backed by TypeSafe's Jev. Workflow-safe: it builds plain JSON
+// and dispatches the model call as the `jev_tool_approval` activity by name (see worker.ts).
+import { proxyActivities } from "@temporalio/workflow";
+import { ApprovalVerdict, } from "../../harness/agent-protocol/index.js";
+export const JEV_TOOL_APPROVAL_ACTIVITY = "jev_tool_approval";
+export const DEFAULT_JEV_MODEL = "jev-latest";
+/** The jev_tool_approval activity's options; `jevEvaluator({activityOptions})` merges over them. */
+export const DEFAULT_ACTIVITY_OPTIONS = {
+    startToCloseTimeout: "30 seconds",
+    retry: { maximumAttempts: 3 },
+    summary: "jev_approval",
+};
+export function jevEvaluator({ model = DEFAULT_JEV_MODEL, extraState, activityOptions, } = {}) {
+    const options = { ...DEFAULT_ACTIVITY_OPTIONS, ...activityOptions };
+    const approve = async (ctx) => {
+        const extra = typeof extraState === "function" ? extraState(ctx) : extraState;
+        const { jev_tool_approval } = proxyActivities(options);
+        const answer = await jev_tool_approval(buildRequest(ctx, { model, extraState: extra }));
+        const [minConfidence, irreversibleCeiling] = ctx.thresholds;
+        return decide(answer, {
+            minConfidence,
+            escalateIfIrreversibleAbove: irreversibleCeiling,
+            criteriaSetName: ctx.criteria_set_name,
+            criteriaVersion: ctx.criteria_version,
+        });
+    };
+    approve.evaluatorLabel = "jev_evaluator";
+    return approve;
+}
+function rules(set, ctx) {
+    const out = {};
+    if (set.effect)
+        out.what_calls_to_this_tool_do = set.effect;
+    if (set.approve_when.length)
+        out.approve_when = [...set.approve_when];
+    if (set.deny_when.length)
+        out.deny_when = [...set.deny_when];
+    if (set.escalate_when.length)
+        out.escalate_when = [...set.escalate_when];
+    if (Object.keys(ctx.criteria.context).length)
+        out.operating_context = { ...ctx.criteria.context };
+    return out;
+}
+export function buildRequest(ctx, { model = DEFAULT_JEV_MODEL, extraState, } = {}) {
+    const state = {
+        situation: "An AI agent wants to run a tool. You are the approval gate that decides whether the call may run unattended, must be " +
+            "refused, or has to be shown to a person first. The agent chose this tool and these arguments itself.",
+        approval_criteria: rules(ctx.criteria_set, ctx),
+        tool: {
+            name: ctx.tool_name,
+            description: ctx.tool_description,
+            declared_inherently_safe: ctx.inherently_safe,
+        },
+        call_arguments: ctx.tool_input,
+    };
+    if (extraState && Object.keys(extraState).length)
+        state.agent_state = { ...extraState };
+    return {
+        state,
+        model,
+        questions: {
+            verdict: {
+                type: "choice",
+                instructions: {
+                    question: "Under the operator's rules in `approval_criteria`, and those rules only, what should happen to the call described " +
+                        "by `tool` and `call_arguments`?",
+                    priorities: [
+                        "Judge the call as it would actually run: `tool.description` says what the tool does, and `call_arguments` are the exact arguments it would run with.",
+                        "`approval_criteria` is the operator's decision and the only authority here. Do not substitute your own sense of what is risky for what it says — neither to approve something it forbids nor to refuse something it allows.",
+                        "`approval_criteria.deny_when` and `.escalate_when` are binding. `.approve_when` describes what a routine call looks like; it permits nothing that a deny or escalate rule also matches, so when rules conflict the stricter one wins.",
+                        "An absent key in `approval_criteria` means the operator said nothing about it. Silence is never permission.",
+                        "`tool.declared_inherently_safe` is the tool author's own claim that the tool is never unsafe under any input. Treat it as a hint; it never overrides `approval_criteria`.",
+                        "If the rules do not settle this call, choose `escalate`. A person is available and asking costs almost nothing; guessing does not.",
+                    ],
+                },
+                criteria: {
+                    approve: {
+                        what: "Run the call now, unattended, with no human review.",
+                        when: "`approval_criteria` permits calls of this kind, and nothing in `call_arguments` crosses a line the criteria draw.",
+                        not_for: "A call the criteria simply do not address — silence is not permission; that is `escalate`.",
+                    },
+                    deny: {
+                        what: "Refuse the call. It never runs, and the agent is told it was refused so it can try a different approach.",
+                        when: "`approval_criteria` rule out calls of this kind, or `call_arguments` show this particular call doing something the criteria forbid.",
+                        not_for: "A call that merely looks consequential but that the criteria do not forbid; that is `escalate`.",
+                    },
+                    escalate: {
+                        what: "Hold the call and put it in front of a person, who approves or denies it themselves.",
+                        when: "`approval_criteria` do not settle this call: they are silent on this kind of call, they are ambiguous, or `call_arguments` are not specific enough to tell which side of the criteria the call falls on.",
+                        not_for: "A call the criteria plainly permit or plainly forbid — deciding those is the point of having them.",
+                    },
+                },
+            },
+            irreversible: {
+                type: "noul",
+                instructions: "Independently of whether the call should be allowed: if this call runs and turns out to have been a mistake, is its effect one that cannot be taken back?",
+                criteria: {
+                    true: "Running it causes something that cannot be undone from inside this system afterwards — data or a resource destroyed, money moved, a message or request sent to someone outside it.",
+                    false: "It only reads or computes, or whatever it changes can be changed back by a later call.",
+                },
+            },
+        },
+    };
+}
+const pct = (x) => `${Math.round(x * 100)}%`;
+// Jev answers in the wire vocabulary its questions offer.
+const VERDICTS = {
+    approve: "approved",
+    deny: "denied",
+    escalate: "user-approval",
+};
+/** Turn Jev's answer into a decision under the operator's thresholds. Escalates when unsure. */
+export function decide(answer, opts) {
+    const verdict = VERDICTS[answer.verdict];
+    const stats = `jev/${answer.model}: verdict=${answer.verdict} (confidence ${pct(answer.verdict_confidence)}), irreversible ${pct(answer.irreversible)}`;
+    const details = {
+        model: answer.model,
+        request_id: answer.request_id,
+        verdict: answer.verdict,
+        confidence: answer.verdict_confidence,
+        probabilities: { ...answer.verdict_probabilities },
+        irreversible: answer.irreversible,
+        usage: { input_tokens: answer.input_tokens, output_tokens: answer.output_tokens },
+        thresholds: {
+            min_confidence: opts.minConfidence,
+            escalate_if_irreversible_above: opts.escalateIfIrreversibleAbove,
+        },
+        criteria_set: opts.criteriaSetName ?? "",
+        criteria_version: opts.criteriaVersion ?? 0,
+    };
+    const escalate = (why) => ({
+        verdict: ApprovalVerdict.USER_APPROVAL,
+        reason: `${stats} — ${why}`,
+        details,
+    });
+    if (answer.verdict_confidence < opts.minConfidence) {
+        return escalate(`below the ${pct(opts.minConfidence)} confidence needed to decide automatically; escalated to a human.`);
+    }
+    if (verdict === undefined)
+        return escalate("unrecognized verdict; escalated to a human.");
+    if (verdict === ApprovalVerdict.USER_APPROVAL)
+        return escalate("the approval criteria do not settle this call.");
+    if (verdict === ApprovalVerdict.DENIED) {
+        return {
+            verdict: ApprovalVerdict.DENIED,
+            reason: `${stats} — the approval criteria forbid this call.`,
+            details,
+        };
+    }
+    if (opts.escalateIfIrreversibleAbove !== null &&
+        answer.irreversible > opts.escalateIfIrreversibleAbove) {
+        return escalate(`approved on the criteria, but the effect looks irreversible (over the ${pct(opts.escalateIfIrreversibleAbove)} ceiling); escalated to a human.`);
+    }
+    return { verdict: ApprovalVerdict.APPROVED, reason: `${stats} — auto-approved.`, details };
+}