eve 0.5.4 → 0.6.0-beta.3

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

@@ -0,0 +1,41 @@
+import type { ModelMessage } from "ai";
+import type { DeliverPayload, SessionAuthContext } from "#channel/types.js";
+import type { StepInput } from "#harness/types.js";
+/**
+ * Merges two {@link StepInput} values into one.
+ *
+ * Used by the harness to coalesce deferred step input with the current
+ * turn's input, and by the execution layer after calling `onDeliver`
+ * for each queued delivery payload.
+ */
+export declare function coalesceTurnInputs(a: StepInput, b: StepInput): StepInput;
+/**
+ * Extracts the final visible assistant text from model response messages.
+ *
+ * Prefers text extracted from the last assistant message that contains visible
+ * text. Falls back to the raw `text` property from the AI SDK result when no
+ * assistant message contains text. Returns `null` when neither source contains
+ * text.
+ */
+export declare function resolveAssistantStepText(messages: readonly ModelMessage[], fallback: string | undefined): string | null;
+/**
+ * Structural shape of the workflow `DeliverHookPayload`. Using a
+ * structural type keeps this helper decoupled from the concrete
+ * runtime type.
+ */
+interface DeliverLike {
+    readonly auth?: SessionAuthContext | null;
+    readonly kind: "deliver";
+    readonly payloads: readonly DeliverPayload[];
+}
+/**
+ * Coalesces an array of deliver-like items into a single item by
+ * collecting all payloads and keeping the most recent auth value.
+ *
+ * Used by the workflow runtime to batch follow-up deliveries that
+ * arrived while a turn or subagent delegation was in progress. Each
+ * payload is later passed to `onDeliver` individually so channel-
+ * specific fields are never lost.
+ */
+export declare function coalesceDeliveries<T extends DeliverLike>(items: readonly T[]): T;
+export {};

package/dist/src/harness/messages.js

@@ -0,0 +1 @@
+function coalesceTurnInputs(e,t){let n=coalesceInputResponses({a:e.inputResponses,b:t.inputResponses}),r=coalesceMessage({a:e.message,b:t.message}),i=coalesceContext({a:e.context,b:t.context}),a=t.outputSchema??e.outputSchema,o={};return n!==void 0&&(o.inputResponses=n),r!==void 0&&(o.message=r),i!==void 0&&(o.context=i),a!==void 0&&(o.outputSchema=a),o}function resolveAssistantStepText(e,t){for(let t=e.length-1;t>=0;--t){let n=e[t];if(n?.role!==`assistant`)continue;let r=extractMessageText(n);if(r.length>0)return r}return t!==void 0&&t.length>0?t:null}function extractMessageText(e){return typeof e.content==`string`?e.content:Array.isArray(e.content)?e.content.flatMap(e=>typeof e==`string`?[e]:`type`in e&&e.type===`text`&&typeof e.text==`string`?[e.text]:[]).join(``):``}function coalesceInputResponses(e){let t=e.a??[],n=e.b??[];if(!(t.length===0&&n.length===0))return[...t,...n]}function coalesceContext(e){let t=e.a??[],n=e.b??[];if(!(t.length===0&&n.length===0))return[...t,...n]}function coalesceMessage(e){return e.a===void 0?e.b:e.b===void 0?e.a:typeof e.a==`string`&&typeof e.b==`string`?`${e.a}\n\n${e.b}`:[...toUserContentArray(e.a),...toUserContentArray(e.b)]}function toUserContentArray(e){return typeof e==`string`?e.length>0?[{type:`text`,text:e}]:[]:Array.isArray(e)?[...e]:[]}function coalesceDeliveries(e){let[t,...n]=e;if(t===void 0)throw Error(`Cannot coalesce an empty delivery batch.`);let r=t.auth,i=[...t.payloads];for(let e of n)e.auth!==void 0&&(r=e.auth),i.push(...e.payloads);return{...t,auth:r,payloads:i}}export{coalesceDeliveries,coalesceTurnInputs,resolveAssistantStepText};

package/dist/src/harness/model-call-error.d.ts

@@ -0,0 +1,53 @@
+import type { JsonObject } from "#shared/json.js";
+/**
+ * One human-readable summary of a known model-call configuration failure.
+ *
+ * Returned by {@link summarizeKnownModelCallConfigError} for terminal
+ * failures that point at a fixable setup mistake (missing API key,
+ * gateway auth failure). Surfaces actionable text in REPL output and in
+ * structured `step.failed` events without dumping the full SDK error
+ * inspection into user-facing logs.
+ */
+export interface ModelCallConfigErrorSummary {
+    readonly name: string;
+    readonly message: string;
+}
+/**
+ * Returns a concise actionable summary for known terminal configuration
+ * errors raised during a model call. Returns `null` for everything else
+ * so the caller falls back to the raw SDK message.
+ */
+export declare function summarizeKnownModelCallConfigError(error: unknown): ModelCallConfigErrorSummary | null;
+/**
+ * Returns a concise summary for known model-call request failures that are not
+ * configuration errors. These failures happen before the agent can produce a
+ * response, so the user-facing message should avoid implying a bad tool call.
+ */
+export declare function summarizeKnownModelCallRequestError(error: unknown): ModelCallConfigErrorSummary | null;
+/**
+ * Returns the distinct upstream tool types referenced by any
+ * "tool type 'X' is not supported" rejection in an AI Gateway error's
+ * provider attempt list.
+ *
+ * Walks the cause chain to find the gateway error and inspects both the
+ * structured `data` field and the raw `responseBody` JSON. Returns an
+ * empty array for errors that are not of this shape.
+ *
+ * Used by the harness recovery path to identify which framework tools
+ * to drop before retrying the failing step. Detection is by string
+ * match on the upstream tool type — see
+ * {@link resolveFrameworkToolFromUpstreamType} for the mapping back to
+ * framework tool names.
+ */
+export declare function extractUnsupportedProviderToolTypes(error: unknown): readonly string[];
+/**
+ * Extracts compact, structured diagnostics from AI SDK / AI Gateway model-call
+ * errors. The full SDK error can include very large request bodies (especially
+ * tool schemas), so this shape lifts the important upstream response fields into
+ * `step.failed.details` before any inspector output gets truncated.
+ */
+export declare function extractModelCallErrorDetails(error: unknown): JsonObject;
+/**
+ * Classifies a model-call failure into the runtime's recovery policy.
+ */
+export declare function classifyModelCallError(error: unknown): "retry" | "recoverable" | "terminal";

package/dist/src/harness/model-call-error.js

@@ -0,0 +1 @@
+import{isObject}from"#shared/guards.js";const UNSUPPORTED_TOOL_TYPE_REGEX=/tool type ['"]([\w.-]+)['"] is not supported/i;function summarizeKnownModelCallConfigError(e){let t=readErrorName(e),n=readErrorMessage(e);return t===`GatewayAuthenticationError`||/AI Gateway authentication/i.test(n)?/Invalid API key/i.test(n)?{name:`AI Gateway authentication failed`,message:"AI Gateway rejected the provided API key. Update or unset `AI_GATEWAY_API_KEY` (check your shell profile if you did not set it for this project) — manage keys at https://vercel.com/dashboard/ai/api-keys. Unsetting it falls back to OIDC via `vercel link` + `vercel env pull`."}:/Invalid OIDC token/i.test(n)?{name:`AI Gateway authentication failed`,message:"AI Gateway rejected the OIDC token. Run `vercel env pull` to refresh `VERCEL_OIDC_TOKEN` in `.env.local`, or set `AI_GATEWAY_API_KEY` — create a key at https://vercel.com/dashboard/ai/api-keys."}:{name:`AI Gateway authentication failed`,message:"AI Gateway received no credentials. Run `vercel link` + `vercel env pull` to populate `VERCEL_OIDC_TOKEN`, or set `AI_GATEWAY_API_KEY` — create a key at https://vercel.com/dashboard/ai/api-keys."}:t===`LoadAPIKeyError`||/API key is missing/i.test(n)?{name:`Model provider API key missing`,message:"The model provider could not load an API key. Export the provider's API key environment variable (for example `AI_GATEWAY_API_KEY` or `OPENAI_API_KEY`) and try again."}:null}function summarizeKnownModelCallRequestError(e){let t=readModelCallErrorSignals(e);return t.statusCode===400&&isGatewayErrorSignal(t)?{name:`AI Gateway model request rejected`,message:`AI Gateway rejected the model request before the agent produced a response.`}:null}function extractUnsupportedProviderToolTypes(e){let n=new Set;for(let r of walkCauseChain(e)){collectUnsupportedToolTypesFromValue(readObjectField(r,`data`),n);let e=readStringField(r,`responseBody`);if(e!==void 0)try{collectUnsupportedToolTypesFromValue(JSON.parse(e),n)}catch{let r=UNSUPPORTED_TOOL_TYPE_REGEX.exec(e);r?.[1]!==void 0&&n.add(r[1])}}return[...n]}function collectUnsupportedToolTypesFromValue(n,r){if(n!=null){if(typeof n==`string`){let e=UNSUPPORTED_TOOL_TYPE_REGEX.exec(n);e?.[1]!==void 0&&r.add(e[1]);return}if(Array.isArray(n)){for(let e of n)collectUnsupportedToolTypesFromValue(e,r);return}if(isObject(n))for(let e of Object.values(n))collectUnsupportedToolTypesFromValue(e,r)}}function extractModelCallErrorDetails(e){let t=readModelCallErrorSignals(e),n={};return appendJsonField(n,`gatewayName`,t.gatewayName),appendJsonField(n,`gatewayType`,t.gatewayType),appendJsonField(n,`statusCode`,t.statusCode),appendJsonField(n,`generationId`,t.generationId),appendJsonField(n,`upstreamStatusCode`,t.upstreamStatusCode),appendJsonField(n,`upstreamType`,t.upstreamType),appendJsonField(n,`upstreamMessage`,t.upstreamMessage),appendJsonField(n,`responseBodySnippet`,t.responseBodySnippet),n}function readErrorName(t){if(t instanceof Error||isObject(t)&&typeof t.name==`string`)return t.name}function readErrorMessage(t){return t instanceof Error||isObject(t)&&typeof t.message==`string`?t.message:``}function classifyModelCallError(e){if(hasRetryableFlag(e))return`retry`;if(summarizeKnownModelCallConfigError(e)!==null)return`terminal`;let t=readModelCallErrorSignals(e);if(isRetryableGatewayType(t.gatewayType)||isRetryableGatewayType(t.upstreamType))return`retry`;if(isTerminalGatewayType(t.gatewayType)||isTerminalGatewayType(t.upstreamType)||t.gatewayName===`GatewayInvalidRequestError`)return`terminal`;let n=t.statusCode;if(n!==void 0){if(n===408||n===409||n===429||n>=500)return`retry`;if(isAmbiguousGatewayInternalBadRequest(t))return`recoverable`;if(n>=400&&n<500)return`terminal`}return isLikelyNetworkError(e)?`retry`:`recoverable`}function hasRetryableFlag(t){for(let n of walkCauseChain(t))if(isObject(n)&&n.isRetryable===!0)return!0;return!1}function isLikelyNetworkError(e){if(!(e instanceof Error))return!1;let t=e.message.toLowerCase();return t.includes(`econnreset`)||t.includes(`etimedout`)||t.includes(`eai_again`)||t.includes(`socket hang up`)||t.includes(`network`)||t.includes(`fetch failed`)?!0:e.cause!==void 0&&e.cause!==e?isLikelyNetworkError(e.cause):!1}function readModelCallErrorSignals(e){let t=findGatewayError(e),n=findUpstreamApiCallError(e),r=readStringField(n,`responseBody`),i=readGatewayErrorBody(n);return{gatewayName:readErrorName(t),gatewayType:readStringField(t,`type`),generationId:readStringField(t,`generationId`)??i?.generationId,responseBodySnippet:r===void 0?void 0:truncateSnippet(r,1e3),statusCode:readStatusCode(t)??readStatusCode(n)??findStatusCode(e),upstreamMessage:i?.message,upstreamStatusCode:readStatusCode(n),upstreamType:i?.type}}function findGatewayError(e){for(let t of walkCauseChain(e)){let e=readErrorName(t),n=readStringField(t,`type`);if(e?.startsWith(`Gateway`)||n?.endsWith(`_error`)||n===`rate_limit_exceeded`)return t}}function findUpstreamApiCallError(e){for(let t of walkCauseChain(e))if(readErrorName(t)===`AI_APICallError`||readStringField(t,`responseBody`)!==void 0||readObjectField(t,`data`)!==void 0||readObjectField(t,`requestBodyValues`)!==void 0)return t}function readGatewayErrorBody(e){let t=readGatewayErrorBodyFromValue(readObjectField(e,`data`));if(t!==void 0)return t;let n=readStringField(e,`responseBody`);if(n!==void 0)try{return readGatewayErrorBodyFromValue(JSON.parse(n))}catch{return}}function readGatewayErrorBodyFromValue(t){if(!isObject(t))return;let n=readObjectField(t,`error`);if(n===void 0)return;let r=readStringField(t,`generationId`),i=readStringField(n,`message`),a=readStringField(n,`type`);return i===void 0&&a===void 0&&r===void 0?void 0:{generationId:r,message:i,type:a}}function readStatusCode(t){if(isObject(t))return typeof t.statusCode==`number`?t.statusCode:void 0}function findStatusCode(e){for(let t of walkCauseChain(e)){let e=readStatusCode(t);if(e!==void 0)return e}}function readStringField(t,n){if(!isObject(t))return;let r=t[n];return typeof r==`string`&&r.length>0?r:void 0}function readObjectField(t,n){if(!isObject(t))return;let r=t[n];return isObject(r)?r:void 0}function isRetryableGatewayType(e){return e===`rate_limit_exceeded`||e===`timeout_error`}function isTerminalGatewayType(e){return e===`authentication_error`||e===`invalid_request_error`||e===`model_not_found`}function isGatewayErrorSignal(e){return e.gatewayName!==void 0||e.gatewayType!==void 0}function isAmbiguousGatewayInternalBadRequest(e){return e.statusCode===400&&(e.gatewayName===`GatewayInternalServerError`||e.gatewayType===`internal_server_error`)&&(e.upstreamType===void 0||e.upstreamType===`internal_server_error`)}function*walkCauseChain(t){let n=new Set,r=t;for(;isObject(r)&&!n.has(r);)n.add(r),yield r,r=r.cause}function appendJsonField(e,t,n){if(typeof n==`string`&&n.length>0){e[t]=n;return}typeof n==`number`&&Number.isFinite(n)&&(e[t]=n)}function truncateSnippet(e,t){return e.length<=t?e:`${e.slice(0,t)}...<truncated>`}export{classifyModelCallError,extractModelCallErrorDetails,extractUnsupportedProviderToolTypes,summarizeKnownModelCallConfigError,summarizeKnownModelCallRequestError};

package/dist/src/harness/otel-integration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Registers the AI SDK OpenTelemetry integration once so that model
+ * calls emit OTel spans, including runtime-context attributes. Safe to
+ * call multiple times — only the first call has an effect.
+ *
+ * In AI SDK v7 the built-in OTel tracing was moved to `@ai-sdk/otel`
+ * and must be registered explicitly.
+ */
+export declare function ensureOtelIntegration(): void;

package/dist/src/harness/otel-integration.js

@@ -0,0 +1 @@
+import{registerTelemetry}from"ai";import{OpenTelemetry}from"#compiled/@ai-sdk/otel/index.js";let registered=!1;function ensureOtelIntegration(){registered||(registered=!0,registerTelemetry(new OpenTelemetry({runtimeContext:!0})))}export{ensureOtelIntegration};

package/dist/src/harness/prompt-cache.d.ts

@@ -0,0 +1,83 @@
+import type { LanguageModel, ModelMessage, SystemModelMessage, ToolSet } from "ai";
+/**
+ * The caching strategy to apply for one harness step.
+ */
+export type PromptCachePath = {
+    readonly kind: "gateway-auto";
+} | {
+    readonly kind: "anthropic-direct";
+} | {
+    readonly kind: "none";
+};
+/**
+ * Cache marker injected on the Anthropic-direct path.
+ *
+ * The AI SDK Anthropic provider reads `providerOptions.anthropic.cacheControl`
+ * from message, message-part, system-message, and tool objects. The same
+ * namespace is used by `@ai-sdk/amazon-bedrock/anthropic` and
+ * `@ai-sdk/google-vertex/anthropic`, which both implement the native
+ * Anthropic Messages API.
+ */
+export interface AnthropicCacheMarker {
+    readonly anthropic: {
+        readonly cacheControl: {
+            readonly type: "ephemeral";
+        };
+    };
+}
+/**
+ * Detects which prompt caching path applies to a resolved model.
+ *
+ * Runs once per harness step right after `resolveModel()`.
+ */
+export declare function detectPromptCachePath(model: LanguageModel): PromptCachePath;
+/**
+ * Returns the shared Anthropic cache marker used on the `anthropic-direct`
+ * path. Exposed for unit tests and for the harness wiring layer.
+ */
+export declare function getAnthropicCacheMarker(): AnthropicCacheMarker;
+/**
+ * Returns a new `providerOptions` object with
+ * `gateway.caching = "auto"` merged into the existing `gateway` sub-object.
+ *
+ * Preserves any existing author-provided `gateway` keys (such as
+ * `order: ["anthropic", "bedrock"]` load balancing), and leaves an
+ * explicit author override on `gateway.caching` untouched so callers can
+ * opt out by setting `providerOptions.gateway.caching` to `false` or
+ * another value.
+ */
+export declare function mergeGatewayAutoCaching(base: Readonly<Record<string, unknown>> | undefined): Record<string, unknown>;
+/**
+ * Returns a new ToolSet where the last tool entry carries the Anthropic
+ * cache marker on `providerOptions`. Used on the `anthropic-direct` path
+ * to place a stable breakpoint at the end of the tools block, caching the
+ * full tool definitions across every turn.
+ *
+ * No-op when `tools` has no entries. Preserves existing `providerOptions`
+ * on tools (merges the cache marker in via spread).
+ */
+export declare function applyLastToolCacheBreakpoint(tools: ToolSet, marker: AnthropicCacheMarker): ToolSet;
+/**
+ * Marks the last system message in an instructions array with the Anthropic
+ * cache marker. This creates a cache breakpoint at the end of the system
+ * prompt, preserving the system prefix when tools change between steps.
+ *
+ * When `instructions` is a string or undefined, returns it unchanged —
+ * single-string system prompts don't support per-message providerOptions.
+ * No-op when the array is empty.
+ */
+export declare function applySystemCacheBreakpoint(instructions: readonly SystemModelMessage[], marker: AnthropicCacheMarker): SystemModelMessage[];
+/**
+ * Walks backward through `messages` and attaches the Anthropic cache marker
+ * to the most recent `assistant` and most recent `user` message. Returns a
+ * new array; does not mutate the input.
+ *
+ * This implements the "automatic cache advancement" pattern: each turn the
+ * breakpoints move forward, and the prior turn's breakpoints still warm the
+ * cache prefix, so the new breakpoints just extend the cached region.
+ *
+ * Tool-result messages (`role: "tool"`) are intentionally skipped — the
+ * adjacent assistant message's cache marker already covers the prefix
+ * through any preceding tool results.
+ */
+export declare function applyConversationCacheControl(messages: readonly ModelMessage[], marker: AnthropicCacheMarker): ModelMessage[];

package/dist/src/harness/prompt-cache.js

@@ -0,0 +1 @@
+const ANTHROPIC_CACHE_MARKER=Object.freeze({anthropic:Object.freeze({cacheControl:Object.freeze({type:`ephemeral`})})});function detectPromptCachePath(e){return typeof e==`string`?{kind:`gateway-auto`}:(typeof e.provider==`string`?e.provider.toLowerCase():``).includes(`anthropic`)?{kind:`anthropic-direct`}:{kind:`none`}}function getAnthropicCacheMarker(){return ANTHROPIC_CACHE_MARKER}function mergeGatewayAutoCaching(e){let t=e?.gateway!==void 0&&typeof e.gateway==`object`&&e.gateway!==null?e.gateway:void 0,n={...t,caching:t?.caching??`auto`};return{...e,gateway:n}}function applyLastToolCacheBreakpoint(e,t){let n=Object.entries(e);if(n.length===0)return e;let r={};for(let e=0;e<n.length;e++){let[i,a]=n[e];if(e===n.length-1){let e=a.providerOptions!==void 0&&typeof a.providerOptions==`object`?a.providerOptions:void 0;r[i]={...a,providerOptions:{...e,...t}}}else r[i]=a}return r}function applySystemCacheBreakpoint(e,t){if(e.length===0)return[...e];let n=[...e],r=n[n.length-1];return n[n.length-1]={...r,providerOptions:{...r.providerOptions,...t}},n}function applyConversationCacheControl(e,t){if(e.length===0)return[...e];let n=[...e],r=!1,i=!1;for(let e=n.length-1;e>=0&&(!r||!i);e--){let a=n[e];a!==void 0&&(!r&&a.role===`assistant`?(n[e]={...a,providerOptions:{...a.providerOptions,...t}},r=!0):!i&&a.role===`user`&&(n[e]={...a,providerOptions:{...a.providerOptions,...t}},i=!0))}return n}export{applyConversationCacheControl,applyLastToolCacheBreakpoint,applySystemCacheBreakpoint,detectPromptCachePath,getAnthropicCacheMarker,mergeGatewayAutoCaching};

package/dist/src/harness/provider-tools.d.ts

@@ -0,0 +1,62 @@
+import { type ToolSet } from "ai";
+import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
+import type { JsonObject } from "#shared/json.js";
+/**
+ * The provider backend resolved for one web search tool invocation.
+ */
+export type WebSearchBackend = "anthropic" | "gateway" | "google" | "openai";
+/**
+ * Returns the framework tool name that produced an upstream provider tool
+ * `type`, or `null` when the type is not one we know how to remove.
+ *
+ * Used by the harness recovery path to decide which tools to drop when a
+ * gateway fallback provider rejects a tool. Unknown types fall through to
+ * the existing terminal/recoverable handling.
+ */
+export declare function resolveFrameworkToolFromUpstreamType(type: string): string | null;
+/**
+ * Maps a {@link WebSearchBackend} to the gateway provider slug used in
+ * `providerOptions.gateway.only` to pin routing to that provider.
+ *
+ * Returns `null` for the `"gateway"` backend (Perplexity via AI Gateway),
+ * which is served by the gateway directly and does not need pinning.
+ */
+export declare function resolveGatewayPinForWebSearchBackend(backend: WebSearchBackend): string | null;
+/**
+ * Returns the output schema for the provider-managed web search tool that
+ * will be injected for `backend`.
+ */
+export declare function resolveWebSearchOutputSchema(backend: WebSearchBackend): JsonObject;
+/**
+ * Returns a new `providerOptions` object with
+ * `gateway.only = [provider]` merged into the existing `gateway`
+ * sub-object so the AI Gateway only attempts the given provider.
+ *
+ * Used by the harness to pin routing when a provider-specific tool
+ * (e.g. Anthropic's `web_search_20250305`) is in the per-step toolset,
+ * so a transient primary outage produces a clean retryable 503 instead
+ * of a fallback-to-incompatible-provider 400.
+ *
+ * Author overrides win — if `base.gateway.only` or `base.gateway.order`
+ * is already set, the input is returned unchanged so explicit routing
+ * preferences are never silently overwritten.
+ */
+export declare function mergeGatewayProviderPin(base: Readonly<Record<string, unknown>> | undefined, provider: string): Record<string, unknown>;
+/**
+ * Determines the web search backend for a model reference.
+ *
+ * - OpenAI models (gateway or BYO): native OpenAI search
+ * - Anthropic models (gateway or BYO): native Anthropic search
+ * - Direct/BYO Google models: native Google search grounding
+ * - Other models on AI Gateway (including `google/...`): Perplexity search via gateway
+ * - Other BYO models: not available (returns `null`)
+ */
+export declare function resolveWebSearchBackend(modelRef: RuntimeModelReference): WebSearchBackend | null;
+/**
+ * Constructs the AI SDK provider tool for web search based on the resolved
+ * backend. Called once per harness step when web search is enabled.
+ *
+ * Dynamic imports keep unused provider SDKs out of the bundle — only the
+ * provider matching the current model is loaded.
+ */
+export declare function resolveWebSearchProviderTool(backend: WebSearchBackend): Promise<ToolSet[string]>;

package/dist/src/harness/provider-tools.js

@@ -0,0 +1 @@
+import{isObject}from"#shared/guards.js";import{jsonSchema}from"ai";import{WEB_SEARCH_ANTHROPIC_OUTPUT_SCHEMA,WEB_SEARCH_GATEWAY_OUTPUT_SCHEMA,WEB_SEARCH_GOOGLE_OUTPUT_SCHEMA,WEB_SEARCH_OPENAI_OUTPUT_SCHEMA,WEB_SEARCH_TOOL_DEFINITION}from"#runtime/framework-tools/web-search.js";const UPSTREAM_TOOL_TYPE_TO_FRAMEWORK_NAME={web_search_20250305:WEB_SEARCH_TOOL_DEFINITION.name};function resolveFrameworkToolFromUpstreamType(e){return UPSTREAM_TOOL_TYPE_TO_FRAMEWORK_NAME[e]??null}function resolveGatewayPinForWebSearchBackend(e){switch(e){case`anthropic`:return`anthropic`;case`openai`:return`openai`;case`google`:return`google`;case`gateway`:return null}}function resolveWebSearchOutputSchema(e){switch(e){case`anthropic`:return WEB_SEARCH_ANTHROPIC_OUTPUT_SCHEMA;case`gateway`:return WEB_SEARCH_GATEWAY_OUTPUT_SCHEMA;case`google`:return WEB_SEARCH_GOOGLE_OUTPUT_SCHEMA;case`openai`:return WEB_SEARCH_OPENAI_OUTPUT_SCHEMA}}function mergeGatewayProviderPin(t,n){let r=isObject(t?.gateway)?t.gateway:void 0;if(r?.only!==void 0||r?.order!==void 0)return{...t};let i={...r,only:[n]};return{...t,gateway:i}}function resolveWebSearchBackend(e){let t=e.id.split(`/`)[0]??``;return t===`openai`||t.startsWith(`openai.`)?`openai`:t===`anthropic`||t.startsWith(`anthropic.`)?`anthropic`:t.startsWith(`google.`)?`google`:e.source===void 0?`gateway`:null}async function resolveWebSearchProviderTool(e){switch(e){case`openai`:{let{openai:t}=await import(`#compiled/@ai-sdk/openai/index.js`);return attachWebSearchOutputSchema(t.tools.webSearch({}),e)}case`anthropic`:{let{anthropic:t}=await import(`#compiled/@ai-sdk/anthropic/index.js`);return attachWebSearchOutputSchema(t.tools.webSearch_20250305(),e)}case`google`:{let{google:t}=await import(`#compiled/@ai-sdk/google/index.js`);return attachWebSearchOutputSchema(t.tools.googleSearch({}),e)}case`gateway`:{let{gateway:t}=await import(`ai`);return attachWebSearchOutputSchema(t.tools.perplexitySearch(),e)}}}function attachWebSearchOutputSchema(e,n){return{...e,outputSchema:jsonSchema(resolveWebSearchOutputSchema(n))}}export{mergeGatewayProviderPin,resolveFrameworkToolFromUpstreamType,resolveGatewayPinForWebSearchBackend,resolveWebSearchBackend,resolveWebSearchOutputSchema,resolveWebSearchProviderTool};

package/dist/src/harness/proxy-input-requests.d.ts

@@ -0,0 +1,32 @@
+import type { SubagentInputRequestHookPayload } from "#channel/types.js";
+import type { HarnessSession, SessionStateMap } from "#harness/types.js";
+/**
+ * Returns the proxy-routing map as a fresh `Map`. Never returns a live
+ * reference so accidental mutation cannot corrupt session state.
+ */
+export declare function getProxyInputRequests(state: SessionStateMap | undefined): ReadonlyMap<string, string>;
+/**
+ * Returns true when the session is currently proxying one or more
+ * HITL requests on behalf of a descendant subagent.
+ */
+export declare function hasProxyInputRequests(state: SessionStateMap | undefined): boolean;
+/**
+ * Replaces prior entries for `forChildContinuationToken` with the
+ * provided ones. A child raising a fresh batch overwrites its prior
+ * batch — the parent never keeps stale request metadata.
+ */
+export declare function upsertProxyInputRequests(input: {
+    readonly entries: readonly (readonly [requestId: string, childContinuationToken: string])[];
+    readonly forChildContinuationToken: string;
+    readonly session: HarnessSession;
+}): HarnessSession;
+/**
+ * Removes every entry for `childContinuationToken`. Called when a
+ * child subagent finishes so stale clicks no longer route to it.
+ */
+export declare function clearProxyInputRequestsForChild(session: HarnessSession, childContinuationToken: string): HarnessSession;
+/**
+ * Projects a {@link SubagentInputRequestHookPayload} into the
+ * `(requestId, childContinuationToken)` tuples the session stores.
+ */
+export declare function toProxyInputRequestEntries(payload: SubagentInputRequestHookPayload): readonly (readonly [requestId: string, childContinuationToken: string])[];

package/dist/src/harness/proxy-input-requests.js

@@ -0,0 +1 @@
+const PROXY_INPUT_REQUESTS_KEY=`eve.runtime.proxyInputRequests`;function getProxyInputRequests(e){return new Map(Object.entries(readMap(e)))}function hasProxyInputRequests(e){for(let t of Object.keys(readMap(e)))return!0;return!1}function upsertProxyInputRequests(e){let t={};for(let[n,r]of Object.entries(readMap(e.session.state)))r!==e.forChildContinuationToken&&(t[n]=r);for(let[n,r]of e.entries)t[n]=r;return writeMap(e.session,t)}function clearProxyInputRequestsForChild(e,t){let n=readMap(e.state),r={},i=!1;for(let[e,a]of Object.entries(n)){if(a===t){i=!0;continue}r[e]=a}return i?writeMap(e,r):e}function toProxyInputRequestEntries(e){return e.event.requests.map(t=>[t.requestId,e.childContinuationToken])}function readMap(t){let n=t?.[PROXY_INPUT_REQUESTS_KEY];if(typeof n!=`object`||!n||Array.isArray(n))return{};let r={};for(let[e,t]of Object.entries(n))typeof t==`string`&&(r[e]=t);return r}function writeMap(t,n){let r={...t.state};return Object.keys(n).length===0?(delete r[PROXY_INPUT_REQUESTS_KEY],{...t,state:Object.keys(r).length>0?r:void 0}):(r[PROXY_INPUT_REQUESTS_KEY]=n,{...t,state:r})}export{clearProxyInputRequestsForChild,getProxyInputRequests,hasProxyInputRequests,toProxyInputRequestEntries,upsertProxyInputRequests};

package/dist/src/harness/runtime-actions.d.ts

@@ -0,0 +1,106 @@
+import type { ModelMessage, ToolSet, TypedToolCall } from "ai";
+import type { RuntimeActionRequest, RuntimeActionResult } from "#runtime/actions/types.js";
+import type { HarnessEmitFn, HarnessSession, HarnessToolMap, SessionStateMap, StepInput } from "#harness/types.js";
+/**
+ * Serializable event coordinates for one pending runtime-action batch.
+ *
+ * Runtime action results are projected back onto the parent stream using the
+ * same turn and step identity as the originating `actions.requested` batch.
+ */
+interface PendingRuntimeActionEventMetadata {
+    readonly sequence: number;
+    readonly stepIndex: number;
+    readonly turnId: string;
+}
+/**
+ * Serializable pending runtime-action batch stored on `session.state`.
+ *
+ * `childContinuationTokens` maps each `subagent-call` action's
+ * `callId` to the deterministic child token minted by dispatch, so
+ * the harness can clear proxy-input entries on result resolution
+ * without re-deriving the token (keeps `harness/` runtime-agnostic).
+ */
+interface PendingRuntimeActionBatch {
+    readonly actions: readonly RuntimeActionRequest[];
+    readonly childContinuationTokens?: Readonly<Record<string, string>>;
+    readonly event: PendingRuntimeActionEventMetadata;
+    readonly responseMessages: readonly ModelMessage[];
+}
+/**
+ * Outcome of resolving a pending runtime-action batch.
+ */
+interface ResolvePendingRuntimeActionsResult {
+    readonly messages: ModelMessage[];
+    readonly outcome: "continue" | "resolved" | "unresolved";
+    readonly session: HarnessSession;
+}
+/** Returns the pending runtime-action batch stored on the session, if any. */
+export declare function getPendingRuntimeActionBatch(state: SessionStateMap | undefined): PendingRuntimeActionBatch | undefined;
+/**
+ * Returns true when the session is parked on a pending runtime-action batch.
+ */
+export declare function hasPendingRuntimeActionBatch(state: SessionStateMap | undefined): boolean;
+export declare function clearPendingRuntimeActionBatch(session: HarnessSession): HarnessSession;
+/**
+ * Stores one pending runtime-action batch on the session.
+ */
+export declare function setPendingRuntimeActionBatch(input: {
+    readonly actions: readonly RuntimeActionRequest[];
+    readonly event: PendingRuntimeActionEventMetadata;
+    readonly responseMessages: readonly ModelMessage[];
+    readonly session: HarnessSession;
+}): HarnessSession;
+/**
+ * Records the child continuation token for a dispatched subagent-call
+ * so {@link resolvePendingRuntimeActions} can clear proxy-input
+ * entries when the child finishes.
+ */
+export declare function recordPendingSubagentChildToken(input: {
+    readonly callId: string;
+    readonly childContinuationToken: string;
+    readonly session: HarnessSession;
+}): HarnessSession;
+/**
+ * Discriminated item consumed by {@link accumulateRuntimeActionResults}
+ * so the loop can process interleaved deliveries and results without
+ * coupling to a concrete `HookPayload` shape.
+ */
+type RuntimeActionAccumulatorItem<TDeliver> = {
+    readonly kind: "deliver";
+    readonly value: TDeliver;
+} | {
+    readonly kind: "runtime-action-result";
+    readonly results: readonly RuntimeActionResult[];
+};
+/**
+ * Accumulates runtime-action results until every pending key has a
+ * matching result. The caller passes the ordered key list so the
+ * workflow runtime can drive the loop without hydrating a session.
+ */
+export declare function accumulateRuntimeActionResults<TDeliver>(input: {
+    readonly bufferedDeliveries: TDeliver[];
+    readonly getNext: () => Promise<RuntimeActionAccumulatorItem<TDeliver> | null>;
+    readonly initialResults?: readonly RuntimeActionResult[];
+    readonly pendingActionKeys: readonly string[] | undefined;
+}): Promise<RuntimeActionResult[] | null>;
+/**
+ * Resolves one pending runtime-action batch back into model history.
+ *
+ * When all expected runtime action results are present, this appends the
+ * stored assistant tool-call messages plus synthesized tool-result messages to
+ * history, clears the pending batch, and emits `subagent.completed` and
+ * `action.result` events back onto the parent stream.
+ */
+export declare function resolvePendingRuntimeActions(input: {
+    readonly emit?: HarnessEmitFn;
+    readonly session: HarnessSession;
+    readonly stepInput?: StepInput;
+}): Promise<ResolvePendingRuntimeActionsResult>;
+/**
+ * Projects one AI SDK tool call into the Eve runtime-action contract.
+ */
+export declare function createRuntimeActionRequestFromToolCall(input: {
+    readonly toolCall: TypedToolCall<ToolSet>;
+    readonly tools: HarnessToolMap;
+}): RuntimeActionRequest;
+export {};

package/dist/src/harness/runtime-actions.js

@@ -0,0 +1 @@
+import{createActionResultEvent}from"#protocol/message.js";import{parseJsonObject}from"#shared/json.js";import{clearProxyInputRequestsForChild}from"#harness/proxy-input-requests.js";import{getRuntimeActionRequestKey,getRuntimeActionResultKey}from"#runtime/actions/keys.js";const PENDING_RUNTIME_ACTION_BATCH_KEY=`eve.runtime.pendingActionBatch`;function getPendingRuntimeActionBatch(e){let t=e?.[PENDING_RUNTIME_ACTION_BATCH_KEY];if(typeof t!=`object`||!t)return;let n=t;if(!(!Array.isArray(n.actions)||!Array.isArray(n.responseMessages)||typeof n.event!=`object`||n.event===null))return n}function hasPendingRuntimeActionBatch(e){return getPendingRuntimeActionBatch(e)!==void 0}function clearPendingRuntimeActionBatch(e){if(e.state?.[PENDING_RUNTIME_ACTION_BATCH_KEY]===void 0)return e;let t={...e.state};return delete t[PENDING_RUNTIME_ACTION_BATCH_KEY],{...e,state:Object.keys(t).length>0?t:void 0}}function setPendingRuntimeActionBatch(e){let t={...e.session.state};return t[PENDING_RUNTIME_ACTION_BATCH_KEY]={actions:[...e.actions],event:e.event,responseMessages:[...e.responseMessages]},{...e.session,state:t}}function recordPendingSubagentChildToken(e){let t=getPendingRuntimeActionBatch(e.session.state);if(t===void 0)return e.session;let n={...e.session.state};return n[PENDING_RUNTIME_ACTION_BATCH_KEY]={...t,childContinuationTokens:{...t.childContinuationTokens,[e.callId]:e.childContinuationToken}},{...e.session,state:n}}async function accumulateRuntimeActionResults(e){let t=e.pendingActionKeys,n=[...e.initialResults??[]];if(t!==void 0&&n.length>0){let e=resolveRuntimeActionResultsForKeys({pendingKeys:t,results:n});if(e!==void 0)return e}for(;;){let r=await e.getNext();if(r===null)return null;if(r.kind===`deliver`){e.bufferedDeliveries.push(r.value);continue}if(n.push(...r.results),t===void 0)continue;let i=resolveRuntimeActionResultsForKeys({pendingKeys:t,results:n});if(i!==void 0)return i}}function resolveReadyRuntimeActionResults(e){let t=getPendingRuntimeActionBatch(e.session.state);if(t!==void 0)return resolveRuntimeActionResultsForBatch({batch:t,results:e.results})}function resolveRuntimeActionResultsForBatch(e){return resolveRuntimeActionResultsForKeys({pendingKeys:e.batch.actions.map(e=>getRuntimeActionRequestKey(e)),results:e.results})}function resolveRuntimeActionResultsForKeys(e){let t=new Set(e.pendingKeys),n=new Map;for(let r of e.results){let e=getRuntimeActionResultKey(r);t.has(e)&&n.set(e,r)}let r=[];for(let t of e.pendingKeys){let e=n.get(t);if(e===void 0)return;r.push(e)}return r}async function resolvePendingRuntimeActions(t){let r=getPendingRuntimeActionBatch(t.session.state);if(r===void 0)return{messages:[...t.session.history],outcome:`continue`,session:t.session};let i=resolveReadyRuntimeActionResults({results:t.stepInput?.runtimeActionResults??[],session:t.session});if(i===void 0)return{messages:[...t.session.history],outcome:`unresolved`,session:t.session};if(t.emit!==void 0)for(let n of i)n.kind===`subagent-result`&&n.isError!==!0&&await t.emit({data:{callId:n.callId,output:typeof n.output==`string`?n.output:JSON.stringify(n.output),subagentName:n.subagentName},type:`subagent.completed`}),await t.emit(createActionResultEvent({result:n,sequence:r.event.sequence,stepIndex:r.event.stepIndex,turnId:r.event.turnId}));let a={...t.session.state};delete a[PENDING_RUNTIME_ACTION_BATCH_KEY];let o={...t.session,state:Object.keys(a).length>0?a:void 0},s=r.childContinuationTokens;if(s!==void 0)for(let e of i){if(e.kind!==`subagent-result`)continue;let t=s[e.callId];t!==void 0&&(o=clearProxyInputRequestsForChild(o,t))}let c=i.map(e=>{switch(e.kind){case`load-skill-result`:return{output:toToolResultOutput(e),toolCallId:e.callId,toolName:`load_skill`,type:`tool-result`};case`subagent-result`:return{output:toToolResultOutput(e),toolCallId:e.callId,toolName:e.subagentName,type:`tool-result`};case`tool-result`:return{output:toToolResultOutput(e),toolCallId:e.callId,toolName:e.toolName,type:`tool-result`}}throw Error(`Unsupported runtime action result kind "${String(e)}".`)}),l=[...o.history,...r.responseMessages];return c.length>0&&l.push({content:c,role:`tool`}),{messages:l,outcome:`resolved`,session:o}}function createRuntimeActionRequestFromToolCall(e){let t=e.tools.get(e.toolCall.toolName);return t?.runtimeAction?.kind===`subagent-call`?{callId:e.toolCall.toolCallId,description:t.description,input:resolveToolCallInputObject(e.toolCall.input,{callId:e.toolCall.toolCallId,toolName:e.toolCall.toolName}),kind:`subagent-call`,name:t.name,nodeId:t.runtimeAction.nodeId,subagentName:t.runtimeAction.subagentName}:t?.runtimeAction?.kind===`remote-agent-call`?{callId:e.toolCall.toolCallId,description:t.description,input:resolveToolCallInputObject(e.toolCall.input,{callId:e.toolCall.toolCallId,toolName:e.toolCall.toolName}),kind:`remote-agent-call`,name:t.name,nodeId:t.runtimeAction.nodeId,remoteAgentName:t.runtimeAction.remoteAgentName??t.name}:{callId:e.toolCall.toolCallId,input:resolveToolCallInputObject(e.toolCall.input,{callId:e.toolCall.toolCallId,toolName:e.toolCall.toolName}),kind:`tool-call`,toolName:e.toolCall.toolName}}function resolveToolCallInputObject(e,n){if(e==null)return{};try{return parseJsonObject(e)}catch(e){let t=e instanceof Error?e.message:String(e);throw TypeError(`Failed to parse tool-call arguments for "${n.toolName}" (${n.callId}): ${t}`,{cause:e})}}function toToolResultOutput(e){return typeof e.output==`string`?e.isError===!0?{type:`error-text`,value:e.output}:{type:`text`,value:e.output}:e.isError===!0?{type:`error-json`,value:toMutableJsonValue(e.output)}:{type:`json`,value:toMutableJsonValue(e.output)}}function toMutableJsonValue(e){if(e===null||typeof e==`string`||typeof e==`number`||typeof e==`boolean`)return e;if(Array.isArray(e))return e.map(e=>toMutableJsonValue(e));let t={};for(let[n,r]of Object.entries(e))t[n]=toMutableJsonValue(r);return t}export{accumulateRuntimeActionResults,clearPendingRuntimeActionBatch,createRuntimeActionRequestFromToolCall,getPendingRuntimeActionBatch,hasPendingRuntimeActionBatch,recordPendingSubagentChildToken,resolvePendingRuntimeActions,setPendingRuntimeActionBatch};

package/dist/src/harness/sandbox-surface.d.ts

@@ -0,0 +1,68 @@
+import type { ToolSet } from "ai";
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+/**
+ * A model-facing code-execution sandbox over a *subset* of the agent's tools.
+ *
+ * `code_mode` and `Workflow` are two instances of this one concept: each is a
+ * QuickJS sandbox the model drives by writing JavaScript, differing only in
+ * which tools it exposes and how it presents itself. Modeling them as surfaces
+ * (rather than parallel boolean branches) keeps the partition uniform and makes
+ * a third sandbox a one-line addition.
+ */
+export interface SandboxSurface {
+    /** Reserved model-facing tool name (e.g. `"code_mode"`, `"Workflow"`). */
+    readonly toolName: string;
+    /**
+     * Whether this surface wraps the given tool into its sandbox. A tool enters
+     * *every* active surface that claims it, so an agent tool — claimed by both
+     * surfaces — is callable from either sandbox when both are enabled.
+     */
+    readonly claims: (harnessTool: HarnessToolDefinition | undefined, tool: ToolSet[string]) => boolean;
+    /**
+     * Optional transform applied to the description auto-generated by
+     * `createCodeModeTool`. Receives the generated text (which lists the callable
+     * tool signatures) and the names of the tools in this sandbox, so the framing
+     * can adapt to what is actually callable. Omit to use the generated
+     * description as-is.
+     */
+    readonly describe?: (input: {
+        readonly generated: string;
+        readonly toolNames: readonly string[];
+    }) => string;
+}
+/**
+ * The `Workflow` sandbox: agents only. Its sole callable operations are the
+ * agent's subagents and remote agents, for orchestrating them from
+ * model-authored JavaScript.
+ */
+export declare const WORKFLOW_SURFACE: SandboxSurface;
+/**
+ * The `code_mode` sandbox: every sandboxable tool — subagent/remote-agent
+ * (`runtimeAction`) tools and ordinary executable host tools (bash, fs, web,
+ * skills). Provider-managed tools with no executor are never sandboxed. This is
+ * unchanged by whether `Workflow` is also enabled.
+ */
+export declare const CODE_MODE_SURFACE: SandboxSurface;
+/**
+ * Active sandbox surfaces for a harness config. A tool enters every surface
+ * that claims it, so the two compose without interfering: `code_mode` is the
+ * full sandbox (agents + host tools) regardless of `Workflow`, and `Workflow`
+ * is an additional agents-only sandbox. When both are enabled, agents are
+ * callable from either; other host tools remain only in `code_mode`. Order is
+ * the emission order and does not affect routing.
+ */
+export declare function selectSandboxSurfaces(config: {
+    readonly codeMode?: boolean;
+    readonly workflow?: boolean;
+}): SandboxSurface[];
+/** Whether any sandbox surface is active — i.e. the model gets a sandbox tool. */
+export declare function isSandboxEnabled(config: {
+    readonly codeMode?: boolean;
+    readonly workflow?: boolean;
+}): boolean;
+/**
+ * Every known surface. Used on replay to rebuild the full sandbox tool set
+ * without knowing which surface a pending interrupt came from — a script only
+ * references its own tools, so the superset is safe.
+ */
+export declare const ALL_SANDBOX_SURFACES: readonly SandboxSurface[];

package/dist/src/harness/sandbox-surface.js

@@ -0,0 +1 @@
+import{CODE_MODE_TOOL_NAME,WORKFLOW_TOOL_NAME}from"#shared/code-mode.js";import{workflowToolDescription}from"#harness/workflow-tool-description.js";const WORKFLOW_SURFACE={toolName:WORKFLOW_TOOL_NAME,claims:e=>e?.runtimeAction!==void 0,describe:({generated:e,toolNames:t})=>{let n=workflowToolDescription(t);return e.length>0?`${n}\n\n${e}`:n}},CODE_MODE_SURFACE={toolName:CODE_MODE_TOOL_NAME,claims:(e,t)=>e?.runtimeAction!==void 0||t.execute!==void 0};function selectSandboxSurfaces(e){let t=[];return e.workflow===!0&&t.push(WORKFLOW_SURFACE),e.codeMode===!0&&t.push(CODE_MODE_SURFACE),t}function isSandboxEnabled(e){return e.codeMode===!0||e.workflow===!0}const ALL_SANDBOX_SURFACES=[WORKFLOW_SURFACE,CODE_MODE_SURFACE];export{ALL_SANDBOX_SURFACES,CODE_MODE_SURFACE,WORKFLOW_SURFACE,isSandboxEnabled,selectSandboxSurfaces};

package/dist/src/harness/step-hooks.d.ts

@@ -0,0 +1,109 @@
+import type { PrepareStepFunction, StepResult, ToolSet, TypedToolCall } from "ai";
+import type { HarnessEmissionState } from "#harness/emission.js";
+import { type AnthropicCacheMarker, type PromptCachePath } from "#harness/prompt-cache.js";
+import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
+/**
+ * The subset of `StepResult` that the harness reads after a step completes.
+ *
+ * Used by both the streaming (`onStepFinish` callback) and non-streaming
+ * (`generateText` result) code paths.
+ */
+export type HarnessStepResult = Pick<StepResult<ToolSet>, "content" | "finishReason" | "response" | "text" | "toolCalls" | "toolResults" | "usage">;
+/**
+ * Input for {@link buildStepHooks}.
+ */
+interface StepHooksInput {
+    readonly cachePath: PromptCachePath;
+    readonly emit?: HarnessEmitFn;
+    readonly emissionState: HarnessEmissionState;
+    /**
+     * When `false`, `prepareStep` skips the `step.started` emission.
+     * Used by the harness recovery path to avoid emitting `step.started`
+     * twice when retrying the same step with a degraded toolset.
+     *
+     * Defaults to `true`.
+     */
+    readonly emitStepStarted?: boolean;
+    /**
+     * When set on the `gateway-auto` cache path, merges
+     * `providerOptions.gateway.only = [gatewayPinProvider]` so the AI
+     * Gateway only routes to the given provider. Used to keep
+     * provider-specific tools (e.g. Anthropic's `web_search_20250305`)
+     * on a provider that can serve them, converting a transient outage
+     * into a clean retryable 503 rather than a fallback-to-incompatible
+     * provider 400.
+     *
+     * Ignored when the author already set `gateway.only` or
+     * `gateway.order` on the model reference's provider options.
+     */
+    readonly gatewayPinProvider?: string;
+    readonly marker: AnthropicCacheMarker | undefined;
+    readonly session: HarnessSession;
+}
+/**
+ * Composable hooks returned by {@link buildStepHooks}.
+ */
+interface StepHooks {
+    /**
+     * `ToolLoopAgent` `onStepFinish` callback.
+     *
+     * Emits `actions.requested`, `action.result`, and `step.completed` events
+     * from the captured step result.
+     */
+    readonly onStepFinish: (step: StepResult<ToolSet>) => Promise<void>;
+    /**
+     * `ToolLoopAgent` `prepareStep` callback.
+     *
+     * Handles `step.started` emission and cache/provider metadata. Compaction
+     * happens in the tool-loop before `agent.stream()`.
+     */
+    readonly prepareStep: PrepareStepFunction<ToolSet>;
+    /**
+     * Promise that resolves when `onStepFinish` has completed.
+     *
+     * Await this after consuming the stream to ensure all step events
+     * have been emitted before proceeding to post-step handling.
+     */
+    readonly stepResult: Promise<HarnessStepResult>;
+}
+/**
+ * Builds composable `prepareStep` and `onStepFinish` closures that
+ * own all step-internal work: emission, compaction, and prompt caching.
+ *
+ * The harness passes these hooks to `ToolLoopAgent` and reads the
+ * results via `stepResult` after the agent finishes.
+ */
+export declare function buildStepHooks(input: StepHooksInput): StepHooks;
+/**
+ * Emits `actions.requested`, `action.result`, and `step.completed` events
+ * from a captured step result.
+ *
+ * Tool calls and results that match `excludedActionToolNames`, belong to
+ * tool-approval requests, or are marked `invalid` by the AI SDK (e.g. the
+ * model emitted unparsable JSON) are filtered out of the emitted events.
+ * The AI SDK feeds the invalid-call error back to the model on the next
+ * step via `step.response.messages` so it can retry with well-formed
+ * arguments — the runtime event stream only sees successfully parsed
+ * tool calls.
+ *
+ * `inlineActionResultCallIds` lists tool-result call ids the stream
+ * already surfaced as `action.result` events (approval-resume path —
+ * see `emitStreamContent`). This skips them to avoid double-emission.
+ */
+export declare function emitStepActions(emitFn: HarnessEmitFn, state: HarnessEmissionState, step: HarnessStepResult, options: {
+    readonly excludedActionToolNames: ReadonlySet<string>;
+    readonly inlineActionResultCallIds?: ReadonlySet<string>;
+    readonly tools: ToolLoopHarnessConfig["tools"];
+}): Promise<void>;
+/**
+ * Returns true when the AI SDK marked the tool call `invalid` (typically
+ * because the model emitted unparsable JSON or targeted an unknown tool).
+ *
+ * Invalid calls have a raw-string or partial `input` payload that cannot
+ * satisfy the runtime-action contract. The AI SDK synthesizes a tool-error
+ * result for the next model step automatically; callers must skip invalid
+ * calls when projecting to `RuntimeActionRequest` values or the harness
+ * will throw on the JSON-object invariant.
+ */
+export declare function isInvalidToolCall(toolCall: TypedToolCall<ToolSet>): boolean;
+export {};

package/dist/src/harness/step-hooks.js

@@ -0,0 +1 @@
+import{createActionResultEvent,createActionsRequestedEvent,createStepCompletedEvent}from"#protocol/message.js";import{createRuntimeActionRequestFromToolCall}from"#harness/runtime-actions.js";import{emitStepStarted,normalizeAssistantStepFinishReason}from"#harness/emission.js";import{createRuntimeToolResultFromMessagePart,createRuntimeToolResultFromStepResult}from"#harness/action-result-helpers.js";import{extractToolApprovalInputRequests}from"#harness/input-extraction.js";import{applyConversationCacheControl,mergeGatewayAutoCaching}from"#harness/prompt-cache.js";import{mergeGatewayProviderPin}from"#harness/provider-tools.js";function buildStepHooks(e){let t=e.session,n=e.emit,r;return{onStepFinish:async e=>{r(e)},prepareStep:async({messages:r})=>{let a=r;n&&e.emitStepStarted!==!1&&await emitStepStarted(n,e.emissionState,r),e.cachePath.kind===`anthropic-direct`&&e.marker&&(a=applyConversationCacheControl([...r],e.marker));let o={messages:a};if(e.cachePath.kind===`gateway-auto`){let n=mergeGatewayAutoCaching(t.agent.modelReference.providerOptions);e.gatewayPinProvider!==void 0&&(n=mergeGatewayProviderPin(n,e.gatewayPinProvider)),o.providerOptions=n}return o},stepResult:new Promise(e=>{r=e})}}async function emitStepActions(i,o,s,c){let l=new Set(s.toolCalls.filter(isProviderExecutedToolCall).map(e=>e.toolCallId)),u=new Set([...l,...extractToolApprovalInputRequests({content:s.content??[]}).map(e=>e.action.callId),...s.toolCalls.filter(isInvalidToolCall).map(e=>e.toolCallId)]),isExcluded=(e,t)=>u.has(e)||c.excludedActionToolNames.has(t),d=s.toolCalls.filter(e=>!isExcluded(e.toolCallId,e.toolName)).map(e=>createRuntimeActionRequestFromToolCall({toolCall:e,tools:c.tools}));d.length>0&&await i(createActionsRequestedEvent({actions:d,sequence:o.sequence,stepIndex:o.stepIndex,turnId:o.turnId}));let f=c.inlineActionResultCallIds;for(let t of reconcileToolResults(s))isExcluded(t.callId,t.toolName)||f?.has(t.callId)||await i(createActionResultEvent({result:t,sequence:o.sequence,stepIndex:o.stepIndex,turnId:o.turnId}));await i(createStepCompletedEvent({finishReason:normalizeAssistantStepFinishReason(s.finishReason),sequence:o.sequence,stepIndex:o.stepIndex,turnId:o.turnId,usage:extractStepUsage(s.usage)}))}function isInvalidToolCall(e){return e.invalid===!0}function isProviderExecutedToolCall(e){return e.providerExecuted===!0}function reconcileToolResults(e){let t=new Map;for(let n of e.toolResults)n.providerExecuted!==!0&&t.set(n.toolCallId,createRuntimeToolResultFromStepResult(n));for(let n of extractToolResultParts(e.response.messages))n.providerExecuted!==!0&&(t.has(n.toolCallId)||t.set(n.toolCallId,createRuntimeToolResultFromMessagePart(n)));return[...t.values()]}function extractToolResultParts(e){let t=[];for(let n of e)if(!(n.role!==`tool`||!Array.isArray(n.content)))for(let e of n.content)e.type===`tool-result`&&t.push(e);return t}function extractStepUsage(e){if(e===void 0)return;let t={};return e.inputTokens!==void 0&&(t.inputTokens=e.inputTokens),e.outputTokens!==void 0&&(t.outputTokens=e.outputTokens),e.inputTokenDetails?.cacheReadTokens!==void 0&&(t.cacheReadTokens=e.inputTokenDetails.cacheReadTokens),e.inputTokenDetails?.cacheWriteTokens!==void 0&&(t.cacheWriteTokens=e.inputTokenDetails.cacheWriteTokens),Object.keys(t).length>0?t:void 0}export{buildStepHooks,emitStepActions,isInvalidToolCall};