experimental-ash 0.22.0 → 0.22.2

package/dist/src/chunks/{prewarm-BELT37PI.js → prewarm-hz8p2jlZ.js}

@@ -1,4 +1,4 @@
-import{E as e,S as t,T as n,_ as r,a as i,c as a,d as o,g as s,h as c,l,m as u,p as ee,s as te,u as d,x as f,y as p}from"./paths-DZTgjrW-.js";import{t as m}from"./authored-module-loader-XcFLnl49.js";import{t as h}from"./errors-DsO9xmQL.js";import{i as g,t as _}from"./package-DmsQgn4v.js";import{join as v,posix as y}from"node:path";import{mkdir as ne,readFile as re,readdir as ie,realpath as b,writeFile as x}from"node:fs/promises";import{createHash as S}from"node:crypto";import{existsSync as C}from"node:fs";function w(e){return e.dev?{appRoot:e.appRoot,dev:e.dev,moduleMapLoaderPath:g(`src/internal/authored-module-map-loader.ts`)}:{appRoot:e.appRoot,dev:e.dev}}const T=`#ash-channel/`;function E(e){let t=e.compileResult.manifest.channels,n=new Set,r=[],i=new Set,o=a();for(let e of t){if(e.kind===`disabled`){if(!o.has(e.name))throw Error(`agent/channels/${e.name}.ts exports disableRoute() but "${e.name}" is not a framework channel. Rename the file to one of: ${[...o].sort().join(`, `)}.`);i.add(e.name);continue}n.add(e.name),r.push({method:e.method,route:e.urlPath})}let s=l().filter(e=>!n.has(e.name)&&!i.has(e.name)).map(e=>({method:e.method,route:e.urlPath})),c=new Set,u=[];for(let e of[...s,...r]){let t=k(e);c.has(t)||(c.add(t),u.push(e))}return u}function D(e,t){for(let n of t.registrations)A(e,{artifactsConfig:t.artifactsConfig,method:n.method,route:n.route})}function O(e,t){return N(t.previous,t.next)?!1:(j(e),D(e,{artifactsConfig:t.artifactsConfig,registrations:t.next}),e.routing.sync(),!0)}function k(e){return`${e.method.toUpperCase()} ${e.route}`}function A(e,t){let r=k(t),i=`${T}${r}`,a=n(g(`src/internal/nitro/routes/channel-dispatch.ts`));e.options.handlers.push({handler:i,method:t.method,route:t.route}),e.options.virtual[i]=[`import { dispatchChannelRequest } from ${a};`,`const config = ${JSON.stringify(t.artifactsConfig)};`,`export default (event) => dispatchChannelRequest(event, ${JSON.stringify(r)}, config);`].join(`
+import{E as e,S as t,T as n,_ as r,a as i,c as a,d as o,g as s,h as c,l,m as u,p as ee,s as te,u as d,x as f,y as p}from"./paths-C6sp4T2U.js";import{t as m}from"./authored-module-loader-XcFLnl49.js";import{t as h}from"./errors-DsO9xmQL.js";import{i as g,t as _}from"./package-DmsQgn4v.js";import{join as v,posix as y}from"node:path";import{mkdir as ne,readFile as re,readdir as ie,realpath as b,writeFile as x}from"node:fs/promises";import{createHash as S}from"node:crypto";import{existsSync as C}from"node:fs";function w(e){return e.dev?{appRoot:e.appRoot,dev:e.dev,moduleMapLoaderPath:g(`src/internal/authored-module-map-loader.ts`)}:{appRoot:e.appRoot,dev:e.dev}}const T=`#ash-channel/`;function E(e){let t=e.compileResult.manifest.channels,n=new Set,r=[],i=new Set,o=a();for(let e of t){if(e.kind===`disabled`){if(!o.has(e.name))throw Error(`agent/channels/${e.name}.ts exports disableRoute() but "${e.name}" is not a framework channel. Rename the file to one of: ${[...o].sort().join(`, `)}.`);i.add(e.name);continue}n.add(e.name),r.push({method:e.method,route:e.urlPath})}let s=l().filter(e=>!n.has(e.name)&&!i.has(e.name)).map(e=>({method:e.method,route:e.urlPath})),c=new Set,u=[];for(let e of[...s,...r]){let t=k(e);c.has(t)||(c.add(t),u.push(e))}return u}function D(e,t){for(let n of t.registrations)A(e,{artifactsConfig:t.artifactsConfig,method:n.method,route:n.route})}function O(e,t){return N(t.previous,t.next)?!1:(j(e),D(e,{artifactsConfig:t.artifactsConfig,registrations:t.next}),e.routing.sync(),!0)}function k(e){return`${e.method.toUpperCase()} ${e.route}`}function A(e,t){let r=k(t),i=`${T}${r}`,a=n(g(`src/internal/nitro/routes/channel-dispatch.ts`));e.options.handlers.push({handler:i,method:t.method,route:t.route}),e.options.virtual[i]=[`import { dispatchChannelRequest } from ${a};`,`const config = ${JSON.stringify(t.artifactsConfig)};`,`export default (event) => dispatchChannelRequest(event, ${JSON.stringify(r)}, config);`].join(`
 `)}function j(e){for(let t=e.options.handlers.length-1;t>=0;--t){let n=e.options.handlers[t];n!==void 0&&M(n)&&e.options.handlers.splice(t,1)}for(let t of Object.keys(e.options.virtual))t.startsWith(T)&&delete e.options.virtual[t]}function M(e){return e.handler.startsWith(T)}function N(e,t){if(e.length!==t.length)return!1;for(let n=0;n<e.length;n+=1){let r=e[n],i=t[n];if(r===void 0||i===void 0||r.method!==i.method||r.route!==i.route)return!1}return!0}const P=`ash.schedule.`;var F=class extends Error{scheduleId;sourceId;taskName;constructor(e,t={}){super(e),this.name=`ScheduleRegistrationError`,t.scheduleId!==void 0&&(this.scheduleId=t.scheduleId),t.sourceId!==void 0&&(this.sourceId=t.sourceId),t.taskName!==void 0&&(this.taskName=t.taskName)}};function I(e){let t=e.map(e=>({cron:e.cron,description:`Run Ash schedule "${e.name}" from "${e.logicalPath}".`,logicalPath:e.logicalPath,scheduleId:e.name,sourceId:e.sourceId,taskName:R(e.sourceId)})).sort((e,t)=>e.sourceId.localeCompare(t.sourceId));return L(t),t}function L(e){let t=new Map;for(let n of e){let e=t.get(n.scheduleId);if(e===void 0){t.set(n.scheduleId,n);continue}throw new F(`Duplicate authored schedule id "${n.scheduleId}" found in "${e.logicalPath}" and "${n.logicalPath}".`,{scheduleId:n.scheduleId,sourceId:n.sourceId,taskName:n.taskName})}}function R(e){return`${P}${Buffer.from(e,`utf8`).toString(`base64url`)}`}const z=`#ash-schedule-task/`;function B(e,t){if(t.registrations.length!==0){e.options.experimental.tasks=!0;for(let n of t.registrations)U(e,{artifactsConfig:t.artifactsConfig,dispatchModulePath:t.dispatchModulePath,registration:n})}}function V(e,t){let n=!G(t.previous,t.next);return H(e),B(e,{artifactsConfig:t.artifactsConfig,dispatchModulePath:t.dispatchModulePath,registrations:t.next}),n}function H(e){for(let t of Object.keys(e.options.tasks))t.startsWith(`ash.schedule.`)&&delete e.options.tasks[t];for(let t of Object.keys(e.options.virtual))t.startsWith(z)&&delete e.options.virtual[t];for(let[t,n]of Object.entries(e.options.scheduledTasks)){let r=W(n).filter(e=>!e.startsWith(P));if(r.length===0){delete e.options.scheduledTasks[t];continue}if(r.length===1){let[n]=r;n!==void 0&&(e.options.scheduledTasks[t]=n);continue}e.options.scheduledTasks[t]=r}}function U(e,t){let r=`${z}${t.registration.taskName}`,i=n(t.dispatchModulePath);e.options.tasks[t.registration.taskName]={description:t.registration.description,handler:r},e.options.virtual[r]=[`import { dispatchScheduleTask } from ${i};`,`const config = ${JSON.stringify(t.artifactsConfig)};`,`export default {`,`  meta: { description: ${JSON.stringify(t.registration.description)} },`,`  async run(event) {`,`    return { result: await dispatchScheduleTask(event.name, config) };`,`  },`,`};`].join(`
 `),ae(e,t.registration.cron,t.registration.taskName)}function ae(e,t,n){let r=e.options.scheduledTasks[t];if(r===void 0){e.options.scheduledTasks[t]=n;return}if(typeof r==`string`){e.options.scheduledTasks[t]=[r,n];return}r.includes(n)||r.push(n)}function W(e){return typeof e==`string`?[e]:[...e]}function G(e,t){if(e.length!==t.length)return!1;for(let n=0;n<e.length;n+=1){let r=e[n],i=t[n];if(r===void 0||i===void 0||r.cron!==i.cron||r.description!==i.description||r.logicalPath!==i.logicalPath||r.scheduleId!==i.scheduleId||r.sourceId!==i.sourceId||r.taskName!==i.taskName)return!1}return!0}async function K(e){return[...e.manifest.schedules].map(e=>{let t={cron:e.cron,hasRun:e.hasRun,logicalPath:e.logicalPath,name:e.name,sourceId:e.sourceId,sourceKind:e.sourceKind};return e.markdown===void 0?t:{...t,markdown:e.markdown}})}async function q(e){return await K({manifest:await o({compiledArtifactsSource:e.compiledArtifactsSource})})}async function J(e){let t=v(e.outDir,`compiled-artifacts-bootstrap.mjs`),n=v(e.outDir,`compiled-artifacts-instrumentation.mjs`),r=se(e.compileResult.manifest.agentRoot);await ne(e.outDir,{recursive:!0}),await x(t,await le({compileResult:e.compileResult,installModulePath:g(`src/runtime/loaders/bundled-artifacts.ts`),moduleMapPath:t,metadata:e.compileResult.metadata})),r!==void 0&&await x(n,ue({agentName:e.compileResult.manifest.config.name,instrumentationPath:r,registerConfigPath:g(`src/harness/instrumentation-config.ts`)}));let i={bootstrapPath:t};return r!==void 0&&(i.instrumentationPluginPath=n,i.instrumentationSourcePath=r),i}const oe=[`.ts`,`.mts`,`.js`,`.mjs`];function se(e){for(let t of oe){let n=v(e,`instrumentation${t}`);if(C(n))return n}}function ce(e){return e.replace(/^export const moduleMap = /m,`const moduleMap = `).replace(/\nexport default moduleMap;\n?$/,`
 `)}async function le(e){let r=ce(t({importSpecifierStyle:`absolute`,manifest:e.compileResult.manifest,moduleMapPath:e.moduleMapPath})).trim();return[`// Generated by Ash. Do not edit by hand.`,`import { installBundledCompiledArtifacts } from ${n(e.installModulePath)};`,``,r,``,`const metadata = ${JSON.stringify(e.metadata,null,2)};`,``,`const manifest = ${JSON.stringify(e.compileResult.manifest,null,2)};`,``,`export function installCompiledArtifactsBootstrap() {`,`  installBundledCompiledArtifacts({`,`    manifest,`,`    metadata,`,`    moduleMap,`,`  });`,`}`,``,`installCompiledArtifactsBootstrap();`,``,`// Default export satisfies the Nitro plugin contract so this file`,`// can be used directly as a Nitro plugin without a separate wrapper.`,`export default function installCompiledArtifactsPlugin() {`,`  // Already installed on import above.`,`}`,``,`export async function __ashInstallCompiledArtifactsStep() {`,`  "use step";`,`  return null;`,`}`,``].join(`

package/dist/src/cli/commands/info.js

@@ -1,2 +1,2 @@
-import{D as e,b as t,t as n,v as r,y as i}from"../../chunks/paths-DZTgjrW-.js";import{d as a,f as o,h as s}from"../../chunks/types-MZUhN0Zy.js";import{createCliTheme as c,renderCliBanner as l,renderCliSection as u}from"../ui/output.js";async function d(e){let t=await f(e);return{application:n(t?.project.appRoot??e),compiledState:t,messaging:{createSessionRoutePath:o,continueSessionRoutePattern:a,streamRoutePattern:s}}}async function f(n){try{return await i({startPath:n})}catch(n){if(n instanceof r)return n.result;if(n instanceof e||n instanceof t)return null;throw n}}function p(e,t){return`${e} ${t}${e===1?``:`s`}`}function m(e,t){return`${`${e} error${e===1?``:`s`}`}, ${`${t} warning${t===1?``:`s`}`}`}function h(e){switch(e){case`ready`:return`success`;case`failed`:return`danger`;default:return`warning`}}async function g(e,t){let n=await d(t),r=n.compiledState,i=n.application,a=c(),o=[{label:`App Root`,value:i.appRoot}],s=[{label:`Workflow Build`,value:i.workflowBuildDir},{label:`Output`,value:i.outputDir}],f=[];r===null?o.push({label:`Compile`,tone:`warning`,value:`unavailable`}):(o.push({label:`Agent Root`,value:r.project.agentRoot},{label:`Layout`,value:r.project.layout},{label:`Compile`,tone:h(r.metadata.status),value:r.metadata.status},{label:`Diagnostics`,tone:r.metadata.discovery.summary.errors>0?`danger`:r.metadata.discovery.summary.warnings>0?`warning`:`success`,value:m(r.metadata.discovery.summary.errors,r.metadata.discovery.summary.warnings)},{label:`Instructions`,value:r.manifest.instructions?.logicalPath??`none`},{label:`Skills`,value:p(r.manifest.skills.length,`skill`)}),s.unshift({label:`Compiled Manifest`,value:r.paths.compiledManifestPath},{label:`Discovery Manifest`,value:r.paths.discoveryManifestPath},{label:`Diagnostics`,value:r.paths.diagnosticsPath},{label:`Module Map`,value:r.paths.moduleMapPath},{label:`Metadata`,value:r.paths.compileMetadataPath}),f.push(r.manifest.instructions===void 0?{label:`Instructions`,value:`No instructions prompt discovered.`}:{label:`Instructions`,value:r.manifest.instructions.logicalPath})),e.log([l(a,{subtitle:`Resolved application paths and the active message contract.`,title:`Ash Info`}),``,u(a,{rows:o,title:`Application`}),``,u(a,{rows:s,title:`Artifacts`}),...r===null?[]:[``,u(a,{rows:f,title:`Instructions`})],``,u(a,{rows:[{label:`Workflow ID`,value:i.workflowId},{label:`Source Dir`,value:i.workflowSourceDir},{label:`Create`,tone:`info`,value:`POST ${n.messaging.createSessionRoutePath}`},{label:`Continue`,tone:`info`,value:`POST ${n.messaging.continueSessionRoutePattern}`},{label:`Stream`,tone:`info`,value:`GET ${n.messaging.streamRoutePattern}`}],title:`Messaging`})].join(`
+import{D as e,b as t,t as n,v as r,y as i}from"../../chunks/paths-C6sp4T2U.js";import{d as a,f as o,h as s}from"../../chunks/types-MZUhN0Zy.js";import{createCliTheme as c,renderCliBanner as l,renderCliSection as u}from"../ui/output.js";async function d(e){let t=await f(e);return{application:n(t?.project.appRoot??e),compiledState:t,messaging:{createSessionRoutePath:o,continueSessionRoutePattern:a,streamRoutePattern:s}}}async function f(n){try{return await i({startPath:n})}catch(n){if(n instanceof r)return n.result;if(n instanceof e||n instanceof t)return null;throw n}}function p(e,t){return`${e} ${t}${e===1?``:`s`}`}function m(e,t){return`${`${e} error${e===1?``:`s`}`}, ${`${t} warning${t===1?``:`s`}`}`}function h(e){switch(e){case`ready`:return`success`;case`failed`:return`danger`;default:return`warning`}}async function g(e,t){let n=await d(t),r=n.compiledState,i=n.application,a=c(),o=[{label:`App Root`,value:i.appRoot}],s=[{label:`Workflow Build`,value:i.workflowBuildDir},{label:`Output`,value:i.outputDir}],f=[];r===null?o.push({label:`Compile`,tone:`warning`,value:`unavailable`}):(o.push({label:`Agent Root`,value:r.project.agentRoot},{label:`Layout`,value:r.project.layout},{label:`Compile`,tone:h(r.metadata.status),value:r.metadata.status},{label:`Diagnostics`,tone:r.metadata.discovery.summary.errors>0?`danger`:r.metadata.discovery.summary.warnings>0?`warning`:`success`,value:m(r.metadata.discovery.summary.errors,r.metadata.discovery.summary.warnings)},{label:`Instructions`,value:r.manifest.instructions?.logicalPath??`none`},{label:`Skills`,value:p(r.manifest.skills.length,`skill`)}),s.unshift({label:`Compiled Manifest`,value:r.paths.compiledManifestPath},{label:`Discovery Manifest`,value:r.paths.discoveryManifestPath},{label:`Diagnostics`,value:r.paths.diagnosticsPath},{label:`Module Map`,value:r.paths.moduleMapPath},{label:`Metadata`,value:r.paths.compileMetadataPath}),f.push(r.manifest.instructions===void 0?{label:`Instructions`,value:`No instructions prompt discovered.`}:{label:`Instructions`,value:r.manifest.instructions.logicalPath})),e.log([l(a,{subtitle:`Resolved application paths and the active message contract.`,title:`Ash Info`}),``,u(a,{rows:o,title:`Application`}),``,u(a,{rows:s,title:`Artifacts`}),...r===null?[]:[``,u(a,{rows:f,title:`Instructions`})],``,u(a,{rows:[{label:`Workflow ID`,value:i.workflowId},{label:`Source Dir`,value:i.workflowSourceDir},{label:`Create`,tone:`info`,value:`POST ${n.messaging.createSessionRoutePath}`},{label:`Continue`,tone:`info`,value:`POST ${n.messaging.continueSessionRoutePattern}`},{label:`Stream`,tone:`info`,value:`GET ${n.messaging.streamRoutePattern}`}],title:`Messaging`})].join(`
 `))}export{g as printApplicationInfo};

package/dist/src/cli/run.js

@@ -1,3 +1,3 @@
-import{t as e}from"../chunks/package-DmsQgn4v.js";import{createCliTheme as t,renderCliTaggedLine as n}from"./ui/output.js";import{i as r,n as i,r as a,t as o}from"../chunks/url-BVRhVE2O.js";import{resolve as s}from"node:path";async function c(){return(await import(`../chunks/host-Btr4S69C.js`).then(e=>e.t)).buildHost}async function l(){return(await import(`./commands/info.js`)).printApplicationInfo}async function u(){return(await import(`./dev/repl.js`)).runDevelopmentRepl}async function d(){return(await import(`../evals/cli/eval.js`)).runEvalCommand}async function f(){return(await import(`../chunks/host-Btr4S69C.js`).then(e=>e.t)).startHost}function p(e=process.cwd()){return s(e)}function m(e){return`Ash (v${e})`}function h(e){return e.name()===`info`||e.name()===`dev`}async function g(e){await new Promise((t,n)=>{let r=!1,i=()=>{process.off(`SIGINT`,a),process.off(`SIGTERM`,a)},a=()=>{r||(r=!0,i(),e.close().then(t,n))};process.once(`SIGINT`,a),process.once(`SIGTERM`,a)})}function _(e){if(!/^-?\d+$/.test(e))throw new r(`Expected a numeric port, received "${e}".`);let t=Number(e);if(!Number.isInteger(t))throw new r(`Expected a numeric port, received "${e}".`);if(t<0||t>65535)throw new r(`Expected a port between 0 and 65535, received "${e}".`);return t}function v(){return!!(process.stdin.isTTY&&process.stdout.isTTY)}function y(e){let t=e[1];return e[0]!==`dev`||e.length!==2||t===void 0||t.startsWith(`-`)?[...e]:[`dev`,`--url`,t]}function b(e){if(e.url){if(e.host!==void 0)throw new r(`The --host option cannot be used with --url.`);if(e.port!==void 0)throw new r(`The --port option cannot be used with --url.`);if(e.repl===!1)throw new r(`The --no-repl option cannot be used with --url.`);return e.url}}function x(r,a){let s=p(),y=e().version,x=new i,S=t();return x.name(`ash`).description(`Build and run an Ash application.`).version(y).showHelpAfterError().exitOverride().hook(`preAction`,(e,t)=>{h(t)&&r.log(m(y))}).configureOutput({writeErr:e=>{r.error(e.trimEnd())},writeOut:e=>{r.log(e.trimEnd())}}),x.command(`build`).description(`Build the current Ash application.`).action(async()=>{let{loadDevelopmentEnvironmentFiles:e}=await import(`./dev/environment.js`);e(s);let t=await(a.buildHost??await c())(s);r.log(n(S,{message:`built output at ${t}`,tag:`build`,tone:`success`}))}),x.command(`dev`).description(`Start the Ash development server or connect the REPL to an existing URL.`).option(`--host <host>`,`Host interface to bind`).option(`--no-repl`,`Start the server without the interactive REPL`).option(`--port <port>`,`Port to listen on (defaults to $PORT, then 3000)`,_).option(`--schedules`,`Run scheduled tasks during development (off by default)`).option(`-u, --url <url>`,`Connect the REPL to an existing server URL`,o).addHelpText(`after`,`
+import{t as e}from"../chunks/package-DmsQgn4v.js";import{createCliTheme as t,renderCliTaggedLine as n}from"./ui/output.js";import{i as r,n as i,r as a,t as o}from"../chunks/url-BVRhVE2O.js";import{resolve as s}from"node:path";async function c(){return(await import(`../chunks/host-DREC8e8Z.js`).then(e=>e.t)).buildHost}async function l(){return(await import(`./commands/info.js`)).printApplicationInfo}async function u(){return(await import(`./dev/repl.js`)).runDevelopmentRepl}async function d(){return(await import(`../evals/cli/eval.js`)).runEvalCommand}async function f(){return(await import(`../chunks/host-DREC8e8Z.js`).then(e=>e.t)).startHost}function p(e=process.cwd()){return s(e)}function m(e){return`Ash (v${e})`}function h(e){return e.name()===`info`||e.name()===`dev`}async function g(e){await new Promise((t,n)=>{let r=!1,i=()=>{process.off(`SIGINT`,a),process.off(`SIGTERM`,a)},a=()=>{r||(r=!0,i(),e.close().then(t,n))};process.once(`SIGINT`,a),process.once(`SIGTERM`,a)})}function _(e){if(!/^-?\d+$/.test(e))throw new r(`Expected a numeric port, received "${e}".`);let t=Number(e);if(!Number.isInteger(t))throw new r(`Expected a numeric port, received "${e}".`);if(t<0||t>65535)throw new r(`Expected a port between 0 and 65535, received "${e}".`);return t}function v(){return!!(process.stdin.isTTY&&process.stdout.isTTY)}function y(e){let t=e[1];return e[0]!==`dev`||e.length!==2||t===void 0||t.startsWith(`-`)?[...e]:[`dev`,`--url`,t]}function b(e){if(e.url){if(e.host!==void 0)throw new r(`The --host option cannot be used with --url.`);if(e.port!==void 0)throw new r(`The --port option cannot be used with --url.`);if(e.repl===!1)throw new r(`The --no-repl option cannot be used with --url.`);return e.url}}function x(r,a){let s=p(),y=e().version,x=new i,S=t();return x.name(`ash`).description(`Build and run an Ash application.`).version(y).showHelpAfterError().exitOverride().hook(`preAction`,(e,t)=>{h(t)&&r.log(m(y))}).configureOutput({writeErr:e=>{r.error(e.trimEnd())},writeOut:e=>{r.log(e.trimEnd())}}),x.command(`build`).description(`Build the current Ash application.`).action(async()=>{let{loadDevelopmentEnvironmentFiles:e}=await import(`./dev/environment.js`);e(s);let t=await(a.buildHost??await c())(s);r.log(n(S,{message:`built output at ${t}`,tag:`build`,tone:`success`}))}),x.command(`dev`).description(`Start the Ash development server or connect the REPL to an existing URL.`).option(`--host <host>`,`Host interface to bind`).option(`--no-repl`,`Start the server without the interactive REPL`).option(`--port <port>`,`Port to listen on (defaults to $PORT, then 3000)`,_).option(`--schedules`,`Run scheduled tasks during development (off by default)`).option(`-u, --url <url>`,`Connect the REPL to an existing server URL`,o).addHelpText(`after`,`
 You can also pass a bare URL as the only argument, for example: ash dev https://example.com
 `).action(async e=>{let t=b(e),{loadDevelopmentEnvironmentFiles:i}=await import(`./dev/environment.js`);if(i(s),t){if(r.log(n(S,{message:`REPL connecting to ${t}`,tag:`dev`,tone:`info`})),!v()){r.log(n(S,{message:`Interactive REPL disabled because the current terminal is not a TTY.`,tag:`dev`,tone:`warning`}));return}r.log(``),await(a.runDevelopmentRepl??await u())({serverUrl:t});return}let o=await(a.startHost??await f())(s,{host:e.host,port:e.port,schedules:e.schedules===!0}),c=!1,l=async()=>{c||(c=!0,await o.close())};try{if(r.log(n(S,{message:`server listening at ${o.url}`,tag:`dev`,tone:`success`})),e.repl===!1)return await g({close:l});if(!v())return r.log(n(S,{message:`Interactive REPL disabled because the current terminal is not a TTY.`,tag:`dev`,tone:`warning`})),await g({close:l});r.log(``),await(a.runDevelopmentRepl??await u())({serverUrl:o.url})}finally{await l()}}),x.command(`info`).description(`Print resolved application information.`).action(async()=>{await(a.printApplicationInfo??await l())(r,s)}),x.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(a.runEvalCommand??await d())(e,r)}),x}async function S(e=process.argv.slice(2),t=console,n={}){let r=x(t,n),i=e.length===0?[`info`]:y(e);try{await r.parseAsync(i,{from:`user`})}catch(e){if(e instanceof a){if(e.exitCode===0)return;throw Error(e.message)}throw e}}export{S as runCli};

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

@@ -1 +1 @@
-import{n as e}from"../../chunks/paths-DZTgjrW-.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-Btr4S69C.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-C6sp4T2U.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-DREC8e8Z.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/sandbox/bindings/vercel.d.ts

@@ -6,7 +6,7 @@ type VercelSandboxModule = typeof VercelSandboxSdk;
 /**
  * User-controllable subset of `Sandbox.create` parameters.
  */
-export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "persistent" | "source" | "signal">;
+export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "persistent" | "signal">;
 /**
  * Construction input for {@link createVercelSandboxBackend}. Internal —
  * the public surface is the `vercelBackend()` factory under

package/dist/src/execution/sandbox/bindings/vercel.js

@@ -115,7 +115,21 @@ async function ensureTemplate(input) {
     else {
         await ensureVercelSandboxTags(sandbox, tags);
     }
-    if (typeof sandbox.currentSnapshotId === "string" && sandbox.currentSnapshotId.length > 0) {
+    /*
+     * A non-empty `currentSnapshotId` normally means "this template was
+     * prewarmed in a previous run — reuse it." But with an author-supplied
+     * `source: snapshot`, the SDK pre-populates `currentSnapshotId` with
+     * the *author's* snapshotId both on a fresh create and on every
+     * subsequent `getNamedSandbox` reuse until we run our own snapshot.
+     * So we ignore that exact value: it's the author's base layer, not a
+     * framework snapshot, and we still owe `ensureSandboxWorkingDirectory`,
+     * bootstrap, seed file writes, and `sandbox.snapshot()` on top.
+     */
+    const authorSnapshotId = extractAuthorSnapshotId(input.createOptions);
+    const hasFrameworkSnapshot = typeof sandbox.currentSnapshotId === "string" &&
+        sandbox.currentSnapshotId.length > 0 &&
+        sandbox.currentSnapshotId !== authorSnapshotId;
+    if (hasFrameworkSnapshot) {
         return {
             sandboxName: sandbox.name,
             snapshotId: sandbox.currentSnapshotId,
@@ -156,11 +170,16 @@ async function ensureSession(input) {
         await ensureVercelSandboxTags(existing, input.tags);
         return existing;
     }
-    // The Vercel SDK rejects `runtime` when `source` is a snapshot — the
-    // runtime is already baked into the snapshot's filesystem. Strip it
-    // from the consumer-supplied create options for the session path
-    // only; template prewarm still honors `runtime`.
-    const { runtime: _runtime, ...sessionCreateOptions } = input.createOptions;
+    /*
+     * Strip both `source` and `runtime` from author-supplied create
+     * options for the session path. The framework owns the session
+     * source — sessions always derive from the prewarmed template's
+     * snapshot, never the author's external source. And the Vercel SDK
+     * rejects `runtime` when `source` is a snapshot because the runtime
+     * is already baked into the snapshot's filesystem. Template prewarm
+     * still honors both fields.
+     */
+    const { runtime: _runtime, source: _source, ...sessionCreateOptions } = input.createOptions;
     const createParams = {
         ...sessionCreateOptions,
         name: sandboxName,
@@ -276,6 +295,19 @@ function isSandboxMissingError(error) {
         error.cause?.response?.status;
     return status === 404;
 }
+/**
+ * Pulls the snapshotId out of an author-supplied `source: { type:
+ * "snapshot", ... }`. Returns undefined for git/tarball sources or when
+ * no source was supplied — those don't seed `currentSnapshotId` with a
+ * pre-existing value the way snapshot sources do.
+ */
+function extractAuthorSnapshotId(createOptions) {
+    const source = createOptions.source;
+    if (source?.type === "snapshot" && typeof source.snapshotId === "string") {
+        return source.snapshotId;
+    }
+    return undefined;
+}
 function getVercelSandboxName(metadata) {
     const sandboxName = metadata?.sandboxName;
     return typeof sandboxName === "string" ? sandboxName : undefined;

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;
     };