experimental-ash 0.21.0 → 0.22.1

package/dist/src/context/hook-lifecycle.js

@@ -2,8 +2,10 @@ import { getAdapterKind } from "../channel/adapter.js";
 import { emitRecoverableFailedTurn, emitTurnPreamble, getHarnessEmissionState, setHarnessEmissionState, } from "../harness/emission.js";
 import { createLogger } from "../internal/logging.js";
 import { toErrorMessage } from "../shared/errors.js";
+import { normalizeSkillPackage, writeSkillPackageToSandbox, } from "../shared/skill-package.js";
+import { formatAvailableSkillsSection } from "#execution/skills/instructions.js";
 import { contextStorage } from "./container.js";
-import { BundleKey, ChannelKey, ContinuationTokenKey, SessionIdKey, SessionPreparedKey, } from "./keys.js";
+import { BundleKey, ChannelKey, ContinuationTokenKey, SandboxKey, SessionIdKey, SessionPreparedKey, } from "./keys.js";
 const log = createLogger("hooks.lifecycle");
 /**
  * Runs the per-turn hook lifecycle inside the active ALS scope and
@@ -20,11 +22,12 @@ const log = createLogger("hooks.lifecycle");
  *
  *  2. `lifecycle.turn` — runs once per fresh delivery (the caller
  *     gates dispatch with `isHarnessBetweenTurns(session)`). Each
- *     hook may return `{ modelContext }`; contributions are
- *     concatenated in registry order. A thrown hook is caught here,
- *     the recoverable `turn.failed` cascade is emitted, and the
- *     dispatcher returns `kind: "turn-failed"` so the caller can park
- *     the session.
+ *     hook may return `{ modelContext, skills }`; model-context
+ *     contributions are concatenated in registry order and skills are
+ *     materialized into the live sandbox before the model call. A
+ *     thrown hook is caught here, the recoverable `turn.failed`
+ *     cascade is emitted, and the dispatcher returns
+ *     `kind: "turn-failed"` so the caller can park the session.
  *
  *  Errors:
  *
@@ -48,56 +51,63 @@ export async function dispatchHookLifecycle(input) {
         turn: { sequence, turnId },
     };
     const modelContext = [];
+    let nextSession = input.session;
     // ---------- lifecycle.session ----------
     if (registry.session.length > 0 && ctx.get(SessionPreparedKey) !== true) {
         // Set the flag BEFORE running the chain. A thrown session hook is
         // a terminal session failure; the next turn must not retry.
         ctx.set(SessionPreparedKey, true);
+        const stageSkills = [];
         for (const entry of registry.session) {
             const result = (await entry.handler(lifecycleInput, hookCtx));
             if (result?.modelContext !== undefined && result.modelContext.length > 0) {
                 modelContext.push(...result.modelContext);
             }
+            stageSkills.push(...normalizeLifecycleSkillResults(ctx, result));
         }
+        nextSession = await materializeLifecycleSkills(ctx, nextSession, stageSkills);
     }
     // ---------- lifecycle.turn ----------
     let preambleEmitted = false;
     let preambleState = emissionState;
-    for (const entry of registry.turn) {
-        try {
+    try {
+        const stageSkills = [];
+        for (const entry of registry.turn) {
             const result = (await entry.handler(lifecycleInput, hookCtx));
             if (result?.modelContext !== undefined && result.modelContext.length > 0) {
                 modelContext.push(...result.modelContext);
             }
+            stageSkills.push(...normalizeLifecycleSkillResults(ctx, result));
         }
-        catch (error) {
-            const message = toErrorMessage(error);
-            try {
-                if (!preambleEmitted) {
-                    preambleState = await emitTurnPreamble(emit, { message: input.input.message }, emissionState, input.runtimeIdentity);
-                    preambleEmitted = true;
-                }
-                const failedState = await emitRecoverableFailedTurn(emit, preambleState, {
-                    code: "HOOK_TURN_FAILED",
-                    message,
-                });
-                return {
-                    kind: "turn-failed",
-                    message,
-                    nextSession: setHarnessEmissionState(input.session, failedState),
-                };
-            }
-            catch (cascadeError) {
-                // An event hook subscribed to one of the failure-cascade
-                // events (eg. `events["turn.failed"]`) threw while we were
-                // emitting the recoverable failure. Re-throwing escalates to
-                // a terminal `session.failed` via the runtime's outer error
-                // path. Document this as the bounded second-order behavior:
-                // when both a `lifecycle.turn` and a `turn.failed` event hook
-                // throw, the session ends.
-                log.error(`Event hook threw while emitting the turn.failed cascade for hook "${entry.slug}" — escalating to session.failed.`, { error: toErrorMessage(cascadeError) });
-                throw cascadeError;
+        nextSession = await materializeLifecycleSkills(ctx, nextSession, stageSkills);
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        try {
+            if (!preambleEmitted) {
+                preambleState = await emitTurnPreamble(emit, { message: input.input.message }, emissionState, input.runtimeIdentity);
+                preambleEmitted = true;
             }
+            const failedState = await emitRecoverableFailedTurn(emit, preambleState, {
+                code: "HOOK_TURN_FAILED",
+                message,
+            });
+            return {
+                kind: "turn-failed",
+                message,
+                nextSession: setHarnessEmissionState(nextSession, failedState),
+            };
+        }
+        catch (cascadeError) {
+            // An event hook subscribed to one of the failure-cascade events
+            // (eg. `events["turn.failed"]`) threw while we were emitting the
+            // recoverable failure. Re-throwing escalates to a terminal
+            // `session.failed` via the runtime's outer error path. Document
+            // this as the bounded second-order behavior: when both a
+            // `lifecycle.turn` and a `turn.failed` event hook throw, the
+            // session ends.
+            log.error("Event hook threw while emitting the turn.failed cascade for a lifecycle.turn failure — escalating to session.failed.", { error: toErrorMessage(cascadeError) });
+            throw cascadeError;
         }
     }
     const channelContext = input.input.modelContext ?? [];
@@ -107,7 +117,49 @@ export async function dispatchHookLifecycle(input) {
         input: mergedModelContext.length > 0
             ? { ...input.input, modelContext: mergedModelContext }
             : input.input,
-        nextSession: input.session,
+        nextSession,
+    };
+}
+function normalizeLifecycleSkillResults(ctx, result) {
+    if (result?.skills === undefined || result.skills.length === 0) {
+        return [];
+    }
+    const authoredSkillNames = new Set(ctx.require(BundleKey).resolvedAgent.skills.map((skill) => skill.name));
+    const dynamicSkills = new Map();
+    for (const skill of result.skills) {
+        const normalized = normalizeSkillPackage(skill);
+        if (authoredSkillNames.has(normalized.name)) {
+            throw new Error(`Hook-contributed skill "${normalized.name}" conflicts with an authored skill.`);
+        }
+        dynamicSkills.set(normalized.name, normalized);
+    }
+    return [...dynamicSkills.values()];
+}
+async function materializeLifecycleSkills(ctx, session, skills) {
+    if (skills.length === 0) {
+        return session;
+    }
+    const dedupedSkills = new Map(skills.map((skill) => [skill.name, skill]));
+    const sandbox = await ctx.require(SandboxKey).get();
+    if (sandbox === null) {
+        throw new Error("Dynamic skills require a sandbox for the current agent.");
+    }
+    for (const skill of dedupedSkills.values()) {
+        await writeSkillPackageToSandbox({ sandbox, skill });
+    }
+    const announcement = formatAvailableSkillsSection([...dedupedSkills.values()]);
+    if (announcement === null) {
+        return session;
+    }
+    return {
+        ...session,
+        history: [
+            ...session.history,
+            {
+                role: "system",
+                content: announcement,
+            },
+        ],
     };
 }
 /**

package/dist/src/evals/cli/eval.js

@@ -1 +1 @@
-import{n as e}from"../../chunks/paths-BgL4fqtv.js";import{loadDevelopmentEnvironmentFiles as t}from"../../cli/dev/environment.js";import{a as n,n as r,t as i}from"../../chunks/client-CKsU8Li3.js";import{n as a}from"../../chunks/host-CyC15ErG.js";import{discoverAndImportSuites as o,discoverSuiteFiles as s,importSuiteFile as c}from"../runner/discover.js";import{executeSuite as l}from"../runner/execute-suite.js";import{ConsoleReporter as u}from"../runner/reporters/console.js";var d=n();function f(e,t){e.command(`eval`).description(`Run eval suites against an Ash agent.`).option(`--suite <id...>`,`Suite IDs to run (repeatable)`).option(`--all`,`Run all discovered suites`).option(`--url <url>`,`Remote agent URL (skip local host startup)`).option(`--timeout <ms>`,`Per-case timeout in milliseconds`).option(`--max-concurrency <n>`,`Max concurrent case executions per suite`).option(`--json`,`Output results as JSON`).option(`--list-suites`,`List discovered suites and exit`).option(`--skip-report`,`Skip suite-defined reporters (e.g. Braintrust)`).action(async e=>{await p(e,t)})}async function p(n,r){let i=e();if(t(i),n.listSuites){await y(i,r);return}let s=n.suite,c=await o(i,s);if(c.length===0){s&&s.length>0?r.error(`No suites found matching: ${s.join(`, `)}`):r.error(`No eval suites found. Create suite files under evals/ with the *.eval.ts extension.`),process.exitCode=1;return}let u,d;n.url?d={kind:`remote`,url:n.url}:(u=await a(i,{host:`127.0.0.1`,port:0}),d={kind:`local`,url:u.url});let f=m(d);try{let e=[];for(let t of c){let r=_(t,n),a=v(r,{json:n.json===!0,skipReport:n.skipReport===!0}),o=await l({suite:r,target:d,reporters:a,appRoot:i,client:f});e.push(o)}n.json&&r.log(JSON.stringify(e,null,2)),e.some(e=>e.errored>0)&&(process.exitCode=1)}finally{u&&await u.close()}process.exit(process.exitCode??0)}function m(e){if(e.kind===`local`)return new i({host:e.url});let t={},n=process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();return n&&(t[r]=n),new i({auth:h(),headers:Object.keys(t).length>0?t:void 0,host:e.url})}function h(){let e=process.env.ASH_EVAL_AUTH_TOKEN?.trim();return e?{bearer:e}:{bearer:g}}async function g(){try{let e=(await(0,d.getVercelOidcToken)()).trim();if(e.length>0)return e}catch{}return process.env.VERCEL_OIDC_TOKEN?.trim()??``}function _(e,t){let n=t.maxConcurrency?Number.parseInt(t.maxConcurrency,10):void 0,r=t.timeout?Number.parseInt(t.timeout,10):void 0;if(n===void 0&&r===void 0)return e;let i={...e};return n!==void 0&&(i.maxConcurrency=n),r!==void 0&&(i.timeoutMs=r),i}function v(e,t){let n=t.json?[]:[new u];return!t.skipReport&&e.reporters&&n.push(...e.reporters),n}async function y(e,t){let n=await s(e);if(n.length===0){t.log(`No eval suites found.`);return}t.log(`Found ${n.length} eval suite file(s):\n`);for(let r of n){let n=await c(e,r);t.log(`  ${n.id}${n.description?`  - ${n.description}`:``}`)}}export{f as registerEvalCommand,p as runEvalCommand};
+import{n as e}from"../../chunks/paths-DxgjK2PI.js";import{loadDevelopmentEnvironmentFiles as t}from"../../cli/dev/environment.js";import{a as n,n as r,t as i}from"../../chunks/client-CKsU8Li3.js";import{n as a}from"../../chunks/host-BDf7A9G7.js";import{discoverAndImportSuites as o,discoverSuiteFiles as s,importSuiteFile as c}from"../runner/discover.js";import{executeSuite as l}from"../runner/execute-suite.js";import{ConsoleReporter as u}from"../runner/reporters/console.js";var d=n();function f(e,t){e.command(`eval`).description(`Run eval suites against an Ash agent.`).option(`--suite <id...>`,`Suite IDs to run (repeatable)`).option(`--all`,`Run all discovered suites`).option(`--url <url>`,`Remote agent URL (skip local host startup)`).option(`--timeout <ms>`,`Per-case timeout in milliseconds`).option(`--max-concurrency <n>`,`Max concurrent case executions per suite`).option(`--json`,`Output results as JSON`).option(`--list-suites`,`List discovered suites and exit`).option(`--skip-report`,`Skip suite-defined reporters (e.g. Braintrust)`).action(async e=>{await p(e,t)})}async function p(n,r){let i=e();if(t(i),n.listSuites){await y(i,r);return}let s=n.suite,c=await o(i,s);if(c.length===0){s&&s.length>0?r.error(`No suites found matching: ${s.join(`, `)}`):r.error(`No eval suites found. Create suite files under evals/ with the *.eval.ts extension.`),process.exitCode=1;return}let u,d;n.url?d={kind:`remote`,url:n.url}:(u=await a(i,{host:`127.0.0.1`,port:0}),d={kind:`local`,url:u.url});let f=m(d);try{let e=[];for(let t of c){let r=_(t,n),a=v(r,{json:n.json===!0,skipReport:n.skipReport===!0}),o=await l({suite:r,target:d,reporters:a,appRoot:i,client:f});e.push(o)}n.json&&r.log(JSON.stringify(e,null,2)),e.some(e=>e.errored>0)&&(process.exitCode=1)}finally{u&&await u.close()}process.exit(process.exitCode??0)}function m(e){if(e.kind===`local`)return new i({host:e.url});let t={},n=process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();return n&&(t[r]=n),new i({auth:h(),headers:Object.keys(t).length>0?t:void 0,host:e.url})}function h(){let e=process.env.ASH_EVAL_AUTH_TOKEN?.trim();return e?{bearer:e}:{bearer:g}}async function g(){try{let e=(await(0,d.getVercelOidcToken)()).trim();if(e.length>0)return e}catch{}return process.env.VERCEL_OIDC_TOKEN?.trim()??``}function _(e,t){let n=t.maxConcurrency?Number.parseInt(t.maxConcurrency,10):void 0,r=t.timeout?Number.parseInt(t.timeout,10):void 0;if(n===void 0&&r===void 0)return e;let i={...e};return n!==void 0&&(i.maxConcurrency=n),r!==void 0&&(i.timeoutMs=r),i}function v(e,t){let n=t.json?[]:[new u];return!t.skipReport&&e.reporters&&n.push(...e.reporters),n}async function y(e,t){let n=await s(e);if(n.length===0){t.log(`No eval suites found.`);return}t.log(`Found ${n.length} eval suite file(s):\n`);for(let r of n){let n=await c(e,r);t.log(`  ${n.id}${n.description?`  - ${n.description}`:``}`)}}export{f as registerEvalCommand,p as runEvalCommand};

package/dist/src/execution/skills/instructions.d.ts

@@ -1,4 +1,7 @@
-import type { ResolvedSkillDefinition } from "#runtime/types.js";
+export interface AvailableSkillDescription {
+    readonly description: string;
+    readonly name: string;
+}
 /**
  * Formats the "Available skills" system prompt section.
  *
@@ -7,7 +10,8 @@ import type { ResolvedSkillDefinition } from "#runtime/types.js";
  * has them from the `load_skill` tool result. This keeps the system
  * prompt identical across the entire session, preserving prompt caching.
  *
- * Called at graph resolution time so the section is part of the turn
- * agent's static instructions rather than injected per-step.
+ * Authored skills call this at graph resolution time so the section is
+ * part of the turn agent's static instructions. Hook-contributed skills
+ * reuse the same formatter for durable history announcements.
  */
-export declare function formatAvailableSkillsSection(skills: readonly ResolvedSkillDefinition[]): string | null;
+export declare function formatAvailableSkillsSection(skills: readonly AvailableSkillDescription[]): string | null;

package/dist/src/execution/skills/instructions.js

@@ -7,8 +7,9 @@ import { WORKSPACE_ROOT } from "#runtime/workspace/types.js";
  * has them from the `load_skill` tool result. This keeps the system
  * prompt identical across the entire session, preserving prompt caching.
  *
- * Called at graph resolution time so the section is part of the turn
- * agent's static instructions rather than injected per-step.
+ * Authored skills call this at graph resolution time so the section is
+ * part of the turn agent's static instructions. Hook-contributed skills
+ * reuse the same formatter for durable history announcements.
  */
 export function formatAvailableSkillsSection(skills) {
     if (skills.length === 0) {

package/dist/src/harness/action-result-helpers.d.ts

@@ -1,5 +1,6 @@
 import type { ModelMessage, ToolSet, TypedToolResult } from "ai";
 import type { RuntimeToolResultActionResult } from "#runtime/actions/types.js";
+import type { JsonValue } from "#shared/json.js";
 type ToolResponsePart = Extract<ModelMessage, {
     role: "tool";
 }>["content"][number];
@@ -7,14 +8,16 @@ type ToolResultPart = Extract<ToolResponsePart, {
     type: "tool-result";
 }>;
 /**
- * Serializes an arbitrary tool result payload to a stable string form.
+ * Coerces an arbitrary value to a JSON-safe {@link JsonValue} without
+ * premature stringification.
  *
- * String inputs pass through. `Error` instances surface their message so
- * stack traces never leak into protocol events. Everything else is
- * `JSON.stringify`'d, with a `String(value)` fallback for values JSON
- * cannot represent (functions, symbols, BigInts).
+ * - Strings, numbers, booleans, and `null` pass through as primitives.
+ * - `Error` instances surface only their message (no stack leak).
+ * - Plain objects and arrays pass through structurally.
+ * - Non-JSON-representable values (functions, symbols, BigInts) fall
+ *   back to `String(value)`.
  */
-export declare function serializeActionOutput(value: unknown): string;
+export declare function toJsonValue(value: unknown): JsonValue;
 /**
  * Builds a `RuntimeToolResultActionResult` from one AI SDK
  * {@link TypedToolResult}. Used for tool results captured on the AI SDK

package/dist/src/harness/action-result-helpers.js

@@ -1,20 +1,27 @@
 /**
- * Serializes an arbitrary tool result payload to a stable string form.
+ * Coerces an arbitrary value to a JSON-safe {@link JsonValue} without
+ * premature stringification.
  *
- * String inputs pass through. `Error` instances surface their message so
- * stack traces never leak into protocol events. Everything else is
- * `JSON.stringify`'d, with a `String(value)` fallback for values JSON
- * cannot represent (functions, symbols, BigInts).
+ * - Strings, numbers, booleans, and `null` pass through as primitives.
+ * - `Error` instances surface only their message (no stack leak).
+ * - Plain objects and arrays pass through structurally.
+ * - Non-JSON-representable values (functions, symbols, BigInts) fall
+ *   back to `String(value)`.
  */
-export function serializeActionOutput(value) {
-    if (typeof value === "string") {
+export function toJsonValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
         return value;
     }
     if (value instanceof Error) {
         return value.message;
     }
-    const serialized = JSON.stringify(value);
-    return serialized === undefined ? String(value) : serialized;
+    if (typeof value === "object") {
+        return value;
+    }
+    return String(value);
 }
 /**
  * Builds a `RuntimeToolResultActionResult` from one AI SDK
@@ -25,7 +32,7 @@ export function createRuntimeToolResultFromStepResult(toolResult) {
     return {
         callId: toolResult.toolCallId,
         kind: "tool-result",
-        output: serializeActionOutput(toolResult.output),
+        output: toJsonValue(toolResult.output),
         toolName: toolResult.toolName,
     };
 }
@@ -40,7 +47,7 @@ export function createRuntimeToolResultFromMessagePart(part) {
     const result = {
         callId: part.toolCallId,
         kind: "tool-result",
-        output: serializeToolResultOutput(part.output),
+        output: toolResultOutputToJsonValue(part.output),
         toolName: part.toolName,
     };
     if (isToolResultError(part.output)) {
@@ -51,21 +58,21 @@ export function createRuntimeToolResultFromMessagePart(part) {
     }
     return result;
 }
-function serializeToolResultOutput(output) {
+function toolResultOutputToJsonValue(output) {
     switch (output.type) {
         case "text":
         case "error-text":
             return output.value;
         case "json":
         case "error-json":
-            return serializeActionOutput(output.value);
+            return toJsonValue(output.value);
         case "execution-denied":
-            return serializeActionOutput({
+            return {
                 code: "TOOL_EXECUTION_DENIED",
                 message: output.reason ?? "Tool execution was denied.",
-            });
+            };
         case "content":
-            return serializeActionOutput(output.value);
+            return toJsonValue(output.value);
     }
 }
 function isToolResultError(output) {

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

@@ -24,6 +24,22 @@ export declare function summarizeKnownModelCallConfigError(error: unknown): Mode
  * 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

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

@@ -1,6 +1,17 @@
 import { isObject } from "#shared/guards.js";
 const RESPONSE_BODY_SNIPPET_LIMIT = 1_000;
 const GATEWAY_MODEL_REQUEST_REJECTED_MESSAGE = "AI Gateway rejected the model request before the agent produced a response.";
+/**
+ * Anchored regex for the upstream "unsupported tool" rejection message
+ * that AI Gateway returns when a fallback provider cannot serve a
+ * provider-specific tool (e.g. Bedrock rejecting `web_search_20250305`).
+ *
+ * The phrasing comes from the gateway's own provider attempt projection
+ * and is stable across the Bedrock and Vertex Anthropic backends. We
+ * anchor the match on the literal `tool type` prefix to avoid sweeping
+ * in unrelated "not supported" errors.
+ */
+const UNSUPPORTED_TOOL_TYPE_REGEX = /tool type ['"]([\w.-]+)['"] is not supported/i;
 /**
  * Returns a concise actionable summary for known terminal configuration
  * errors raised during a model call. Returns `null` for everything else
@@ -56,6 +67,66 @@ export function summarizeKnownModelCallRequestError(error) {
     }
     return 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 function extractUnsupportedProviderToolTypes(error) {
+    const found = new Set();
+    for (const candidate of walkCauseChain(error)) {
+        collectUnsupportedToolTypesFromValue(readObjectField(candidate, "data"), found);
+        const responseBody = readStringField(candidate, "responseBody");
+        if (responseBody !== undefined) {
+            try {
+                collectUnsupportedToolTypesFromValue(JSON.parse(responseBody), found);
+            }
+            catch {
+                // The response body may be truncated mid-JSON when the upstream
+                // includes a large request snapshot. Fall back to a raw string
+                // scan so we still surface the tool name when the regex match
+                // lies before the truncation boundary.
+                const match = UNSUPPORTED_TOOL_TYPE_REGEX.exec(responseBody);
+                if (match?.[1] !== undefined) {
+                    found.add(match[1]);
+                }
+            }
+        }
+    }
+    return [...found];
+}
+function collectUnsupportedToolTypesFromValue(value, out) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === "string") {
+        const match = UNSUPPORTED_TOOL_TYPE_REGEX.exec(value);
+        if (match?.[1] !== undefined) {
+            out.add(match[1]);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            collectUnsupportedToolTypesFromValue(entry, out);
+        }
+        return;
+    }
+    if (isObject(value)) {
+        for (const entry of Object.values(value)) {
+            collectUnsupportedToolTypesFromValue(entry, out);
+        }
+    }
+}
 /**
  * Extracts compact, structured diagnostics from AI SDK / AI Gateway model-call
  * errors. The full SDK error can include very large request bodies (especially

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

@@ -3,7 +3,39 @@ import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
 /**
  * The provider backend resolved for one web search tool invocation.
  */
-type WebSearchBackend = "anthropic" | "gateway" | "google" | "openai";
+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 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.
  *
@@ -22,4 +54,3 @@ export declare function resolveWebSearchBackend(modelRef: RuntimeModelReference)
  * provider matching the current model is loaded.
  */
 export declare function resolveWebSearchProviderTool(backend: WebSearchBackend): Promise<ToolSet[string]>;
-export {};

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

@@ -1,3 +1,84 @@
+import { WEB_SEARCH_TOOL_DEFINITION } from "#runtime/framework-tools/web-search.js";
+import { isObject } from "#shared/guards.js";
+/**
+ * Maps an upstream provider tool type (the literal `type` string the AI SDK
+ * sends to the provider) back to the framework tool name that injected it.
+ *
+ * Used when the AI Gateway routes a request to a fallback provider that
+ * does not support a provider-specific tool — the upstream error references
+ * the provider-specific type (e.g. `web_search_20250305`), but the harness
+ * needs to drop the framework tool by its public name (`web_search`).
+ *
+ * Adding a new provider tool requires adding the corresponding mapping
+ * entry here alongside its {@link resolveWebSearchProviderTool} switch
+ * arm so detection stays in lockstep with injection.
+ */
+const UPSTREAM_TOOL_TYPE_TO_FRAMEWORK_NAME = {
+    // Anthropic's stable web search tool. The Bedrock and Vertex
+    // Anthropic backends reject this type because they only host the
+    // older Claude Messages surface.
+    web_search_20250305: WEB_SEARCH_TOOL_DEFINITION.name,
+};
+/**
+ * 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 function resolveFrameworkToolFromUpstreamType(type) {
+    return UPSTREAM_TOOL_TYPE_TO_FRAMEWORK_NAME[type] ?? 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 function resolveGatewayPinForWebSearchBackend(backend) {
+    switch (backend) {
+        case "anthropic":
+            return "anthropic";
+        case "openai":
+            return "openai";
+        case "google":
+            return "google";
+        case "gateway":
+            return null;
+    }
+}
+/**
+ * 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 function mergeGatewayProviderPin(base, provider) {
+    const baseGateway = isObject(base?.gateway)
+        ? base.gateway
+        : undefined;
+    if (baseGateway?.only !== undefined || baseGateway?.order !== undefined) {
+        return { ...base };
+    }
+    const mergedGateway = {
+        ...baseGateway,
+        only: [provider],
+    };
+    return {
+        ...base,
+        gateway: mergedGateway,
+    };
+}
 /**
  * Determines the web search backend for a model reference.
  *

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

@@ -16,6 +16,27 @@ export 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;
 }

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

@@ -3,6 +3,7 @@ import { createRuntimeToolResultFromMessagePart, createRuntimeToolResultFromStep
 import { emitStepStarted, normalizeAssistantStepFinishReason } from "#harness/emission.js";
 import { extractToolApprovalInputRequests } from "#harness/input-extraction.js";
 import { applyConversationCacheControl, mergeGatewayAutoCaching, } from "#harness/prompt-cache.js";
+import { mergeGatewayProviderPin } from "#harness/provider-tools.js";
 import { createRuntimeActionRequestFromToolCall } from "#harness/runtime-actions.js";
 // ---------------------------------------------------------------------------
 // Builder
@@ -31,7 +32,7 @@ export function buildStepHooks(input) {
     // -------------------------------------------------------------------------
     const prepareStep = async ({ messages }) => {
         let processed = messages;
-        if (emit) {
+        if (emit && input.emitStepStarted !== false) {
             await emitStepStarted(emit, input.emissionState);
         }
         if (input.cachePath.kind === "anthropic-direct" && input.marker) {
@@ -41,7 +42,11 @@ export function buildStepHooks(input) {
             messages: processed,
         };
         if (input.cachePath.kind === "gateway-auto") {
-            stepResult.providerOptions = mergeGatewayAutoCaching(session.agent.modelReference.providerOptions);
+            let providerOptions = mergeGatewayAutoCaching(session.agent.modelReference.providerOptions);
+            if (input.gatewayPinProvider !== undefined) {
+                providerOptions = mergeGatewayProviderPin(providerOptions, input.gatewayPinProvider);
+            }
+            stepResult.providerOptions = providerOptions;
         }
         return stepResult;
     };