experimental-ash 0.53.0 → 0.55.0

package/dist/src/runtime/framework-tools/connection-search-dynamic.js

@@ -1 +1 @@
-import{createLogger}from"#internal/logging.js";import{loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";import{ConnectionRegistryKey}from"#context/providers/connection.js";import{getAuthorizationResult,getHookUrl,requestAuthorization}from"#harness/authorization.js";import{supportsInteractiveAuthorization}from"#runtime/connections/types.js";import{isConnectionAuthorizationFailedError,isConnectionAuthorizationRequiredError}from"#public/connections/errors.js";import{writeCachedToken}from"#runtime/connections/authorization-tokens.js";import{principalKey,resolveConnectionPrincipal}from"#runtime/connections/principal.js";const logger=createLogger(`framework.connection-search-dynamic`),ConnectionSearchResultsKey=new ContextKey(`ash.connectionSearchResults`);function qualifiedConnectionToolName(e,t){return`${e}__${t}`}function tokenize(e){return e.toLowerCase().split(/[\s_\-./]+/).filter(e=>e.length>1)}function scoreMatch(e,t){let n=tokenize(t.name),r=tokenize(t.description),i=0;for(let t of e){for(let e of n)(e.includes(t)||t.includes(e))&&(i+=3);for(let e of r)(e.includes(t)||t.includes(e))&&(i+=1)}return i}function resolveInteractiveAuth(e,t){let n=e.getConnections().find(e=>e.connectionName===t);if(n?.authorization&&supportsInteractiveAuthorization(n.authorization))return n.authorization}async function completePendingAuthorizations(e){let n=loadContext();for(let t of e.getConnections()){let r=getAuthorizationResult(t.connectionName);if(!r)continue;let a=resolveInteractiveAuth(e,t.connectionName);if(!a)continue;let o=resolveConnectionPrincipal(t.connectionName,a),s=await a.completeAuthorization({callbackUrl:r.hookUrl,connection:{url:t.url??``},principal:o,request:r.callback,state:r.state});writeCachedToken(n,t.connectionName,principalKey(o),s)}}async function executeConnectionSearch(e){let n=loadContext(),i=n.get(ConnectionRegistryKey);if(i===void 0)return[];await completePendingAuthorizations(i);let s=e.limit??10,l=tokenize(e.keywords),u=[],p=[],m=e.connection!==void 0&&e.connection!==``?i.getConnections().filter(t=>t.connectionName===e.connection):i.getConnections(),h=[];for(let e of m){let t;try{t=await i.getClient(e.connectionName).getToolMetadata()}catch(t){if(isConnectionAuthorizationRequiredError(t)){let t=resolveInteractiveAuth(i,e.connectionName);if(t){let n=getHookUrl(e.connectionName);if(n){let r=resolveConnectionPrincipal(e.connectionName,t);try{let{challenge:i,state:a}=await t.startAuthorization({callbackUrl:n,connection:{url:e.url??``},principal:r});h.push({name:e.connectionName,challenge:i,hookUrl:n,state:a})}catch(t){logger.warn(`startAuthorization failed`,{connection:e.connectionName,error:t instanceof Error?t:Error(String(t))})}}}p.push({connection:e.connectionName,description:e.description,needsAuthorization:!0});continue}if(isConnectionAuthorizationFailedError(t)){logger.warn(`connection authorization failed`,{connection:e.connectionName,reason:t.reason,retryable:t.retryable,error:t}),p.push({connection:e.connectionName,description:e.description,error:`Authorization failed for ${e.connectionName}: ${t.message}`});continue}let n=t instanceof Error?t.message:`unknown error`;logger.warn(`failed to load connection tools`,{connection:e.connectionName,error:t instanceof Error?t:Error(n)}),p.push({connection:e.connectionName,description:e.description,error:`Failed to load tools for "${e.connectionName}": ${n}`});continue}for(let n of t){let t=scoreMatch(l,n);t>0&&u.push({item:{connection:e.connectionName,description:n.description,inputSchema:n.inputSchema,qualifiedName:`connection__${qualifiedConnectionToolName(e.connectionName,n.name)}`,tool:n.name},score:t})}}if(h.length>0)return requestAuthorization(h);u.sort((e,t)=>t.score-e.score);let g=u.slice(0,s).map(e=>e.item);if(g.length>0){let e=[...g,...p],t=n.get(ConnectionSearchResultsKey)??[],r=new Map(t.map(e=>[e.qualifiedName,e]));for(let e of g)e.qualifiedName&&r.set(e.qualifiedName,e);return n.set(ConnectionSearchResultsKey,[...r.values()]),e}return m.map(e=>p.find(t=>t.connection===e.connectionName)||{connection:e.connectionName,description:e.description})}function extractDiscoveredTools(e){let t=new Map;for(let n of e){if(n.role!==`tool`)continue;let e=n.content;for(let n of e){if(n.type!==`tool-result`||n.toolName!==`connection__search`)continue;let e=n.output;if(e==null)continue;let r=typeof e==`object`&&`type`in e&&`value`in e?e.value:e;if(Array.isArray(r))for(let e of r)e.tool&&e.qualifiedName&&t.set(e.qualifiedName,e)}}return[...t.values()]}function createConnectionSearchEvents(){return{"step.started":async(e,n)=>{let c=loadContext().get(ConnectionRegistryKey);if(!c||c.getConnections().length===0)return null;let d=c.getConnections().map(e=>e.connectionName),p=extractDiscoveredTools(n.messages),m=loadContext().get(ConnectionSearchResultsKey)??[],h=new Map;for(let e of m)e.qualifiedName&&h.set(e.qualifiedName,e);for(let e of p)e.qualifiedName&&h.set(e.qualifiedName,e);let g=[...h.values()],_={};_.search={description:`Search for tools across your connections. Discovered tools become directly callable by their qualified name (e.g. \`connection__linear__list_issues\`) in your next response. Available connections: ${d.join(`, `)}.`,inputSchema:{type:`object`,additionalProperties:!1,properties:{keywords:{description:`Search keywords and expanded aliases. Distill intent into keywords; avoid stop words like 'a', 'the', 'in'.`,type:`string`},connection:{description:`Optional: limit search to a specific connection name.`,type:`string`},limit:{description:`Max results to return. Default 10.`,type:`number`}},required:[`keywords`]},async execute(e){return executeConnectionSearch(e)}};for(let e of g){let n=e.connection,c=e.tool;_[qualifiedConnectionToolName(n,c)]={description:e.description,inputSchema:e.inputSchema??{type:`object`},async execute(e){let d=loadContext().get(ConnectionRegistryKey),f=d.getConnections().find(e=>e.connectionName===n),p=f?.authorization&&supportsInteractiveAuthorization(f.authorization)?f.authorization:void 0;if(p){let e=getAuthorizationResult(n);if(e){let r=loadContext(),i=resolveConnectionPrincipal(n,p),a=await p.completeAuthorization({callbackUrl:e.hookUrl,connection:{url:f?.url??``},principal:i,request:e.callback,state:e.state});writeCachedToken(r,n,principalKey(i),a)}}try{let t=(await d.getClient(n).getTools())[c];if(!t?.execute)throw Error(`Connection tool "${qualifiedConnectionToolName(n,c)}" has no execute function.`);return t.execute(e,{})}catch(e){if(!isConnectionAuthorizationRequiredError(e)||!p)throw e;let t=getHookUrl(n);if(!t)throw e;let r=resolveConnectionPrincipal(n,p),{challenge:i,state:s}=await p.startAuthorization({callbackUrl:t,connection:{url:f?.url??``},principal:r});return requestAuthorization([{name:n,challenge:i,hookUrl:t,state:s}])}}}}return _}}}function createConnectionSearchResolver(){let e=createConnectionSearchEvents();return{slug:`connection`,eventNames:Object.keys(e),events:e,sourceId:`ash:connection-search-dynamic`,sourceKind:`module`,logicalPath:`ash:framework/connection-search-dynamic`}}export{createConnectionSearchEvents,createConnectionSearchResolver,extractDiscoveredTools};
+import{createLogger}from"#internal/logging.js";import{loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";import{ConnectionRegistryKey}from"#context/providers/connection.js";import{getAuthorizationResult,getHookUrl,requestAuthorization}from"#harness/authorization.js";import{supportsInteractiveAuthorization}from"#runtime/connections/types.js";import{isConnectionAuthorizationFailedError,isConnectionAuthorizationRequiredError}from"#public/connections/errors.js";import{writeCachedToken}from"#runtime/connections/authorization-tokens.js";import{principalKey,resolveConnectionPrincipal}from"#runtime/connections/principal.js";const logger=createLogger(`framework.connection-search-dynamic`),ConnectionSearchResultsKey=new ContextKey(`ash.connectionSearchResults`);function qualifiedConnectionToolName(e,t){return`${e}__${t}`}function tokenize(e){return e.toLowerCase().split(/[\s_\-./]+/).filter(e=>e.length>1)}function scoreMatch(e,t){let n=tokenize(t.name),r=tokenize(t.description),i=0;for(let t of e){for(let e of n)(e.includes(t)||t.includes(e))&&(i+=3);for(let e of r)(e.includes(t)||t.includes(e))&&(i+=1)}return i}function resolveInteractiveAuth(e,t){let n=e.getConnections().find(e=>e.connectionName===t);if(n?.authorization&&supportsInteractiveAuthorization(n.authorization))return n.authorization}async function completePendingAuthorizations(e){let n=loadContext();for(let t of e.getConnections()){let r=getAuthorizationResult(t.connectionName);if(!r)continue;let a=resolveInteractiveAuth(e,t.connectionName);if(!a)continue;let o=resolveConnectionPrincipal(t.connectionName,a),s=await a.completeAuthorization({callbackUrl:r.hookUrl,connection:{url:t.url??``},principal:o,request:r.callback,state:r.state});writeCachedToken(n,t.connectionName,principalKey(o),s)}}async function executeConnectionSearch(e){let n=loadContext(),i=n.get(ConnectionRegistryKey);if(i===void 0)return[];await completePendingAuthorizations(i);let s=e.limit??10,l=tokenize(e.keywords),u=[],p=[],m=e.connection!==void 0&&e.connection!==``?i.getConnections().filter(t=>t.connectionName===e.connection):i.getConnections(),h=[];for(let e of m){let t;try{t=await i.getClient(e.connectionName).getToolMetadata()}catch(t){if(isConnectionAuthorizationRequiredError(t)){let t=resolveInteractiveAuth(i,e.connectionName);if(t){let n=getHookUrl(e.connectionName);if(n){let r=resolveConnectionPrincipal(e.connectionName,t);try{let{challenge:i,state:a}=await t.startAuthorization({callbackUrl:n,connection:{url:e.url??``},principal:r});h.push({name:e.connectionName,challenge:i,hookUrl:n,state:a})}catch(t){logger.warn(`startAuthorization failed`,{connection:e.connectionName,error:t instanceof Error?t:Error(String(t))})}}}p.push({connection:e.connectionName,description:e.description,needsAuthorization:!0});continue}if(isConnectionAuthorizationFailedError(t)){logger.warn(`connection authorization failed`,{connection:e.connectionName,reason:t.reason,retryable:t.retryable,error:t}),p.push({connection:e.connectionName,description:e.description,error:`Authorization failed for ${e.connectionName}: ${t.message}`});continue}let n=t instanceof Error?t.message:`unknown error`;logger.warn(`failed to load connection tools`,{connection:e.connectionName,error:t instanceof Error?t:Error(n)}),p.push({connection:e.connectionName,description:e.description,error:`Failed to load tools for "${e.connectionName}": ${n}`});continue}for(let n of t){let t=scoreMatch(l,n);t>0&&u.push({item:{connection:e.connectionName,description:n.description,inputSchema:n.inputSchema,qualifiedName:`connection__${qualifiedConnectionToolName(e.connectionName,n.name)}`,tool:n.name},score:t})}}if(h.length>0)return requestAuthorization(h);u.sort((e,t)=>t.score-e.score);let g=u.slice(0,s).map(e=>e.item);if(g.length>0){let e=[...g,...p],t=n.get(ConnectionSearchResultsKey)??[],r=new Map(t.map(e=>[e.qualifiedName,e]));for(let e of g)e.qualifiedName&&r.set(e.qualifiedName,e);return n.set(ConnectionSearchResultsKey,[...r.values()]),e}return m.map(e=>p.find(t=>t.connection===e.connectionName)||{connection:e.connectionName,description:e.description})}function extractDiscoveredTools(e){let t=new Map;for(let n of e){if(n.role!==`tool`)continue;let e=n.content;for(let n of e){if(n.type!==`tool-result`||n.toolName!==`connection__search`)continue;let e=n.output;if(e==null)continue;let r=typeof e==`object`&&`type`in e&&`value`in e?e.value:e;if(Array.isArray(r))for(let e of r)e.tool&&e.qualifiedName&&t.set(e.qualifiedName,e)}}return[...t.values()]}function createConnectionSearchEvents(){return{"step.started":async(e,n)=>{let c=loadContext().get(ConnectionRegistryKey);if(!c||c.getConnections().length===0)return null;let d=c.getConnections().map(e=>e.connectionName),p=extractDiscoveredTools(n.messages),m=loadContext().get(ConnectionSearchResultsKey)??[],h=new Map;for(let e of m)e.qualifiedName&&h.set(e.qualifiedName,e);for(let e of p)e.qualifiedName&&h.set(e.qualifiedName,e);let g=[...h.values()],_={};_.search={description:`Search for tools across your connections. Discovered tools become directly callable by their qualified name (e.g. \`connection__linear__list_issues\`) in your next response. Available connections: ${d.join(`, `)}.`,inputSchema:{type:`object`,additionalProperties:!1,properties:{keywords:{description:`Search keywords and expanded aliases. Distill intent into keywords; avoid stop words like 'a', 'the', 'in'.`,type:`string`},connection:{description:`Optional: limit search to a specific connection name.`,type:`string`},limit:{description:`Max results to return. Default 10.`,type:`number`}},required:[`keywords`]},async execute(e){return executeConnectionSearch(e)}};for(let e of g){let n=e.connection,d=e.tool,f=c.getConnectionApproval(n);_[qualifiedConnectionToolName(n,d)]={description:e.description,inputSchema:e.inputSchema??{type:`object`},needsApproval:f,async execute(e){let c=loadContext().get(ConnectionRegistryKey),f=c.getConnections().find(e=>e.connectionName===n),p=f?.authorization&&supportsInteractiveAuthorization(f.authorization)?f.authorization:void 0;if(p){let e=getAuthorizationResult(n);if(e){let r=loadContext(),i=resolveConnectionPrincipal(n,p),a=await p.completeAuthorization({callbackUrl:e.hookUrl,connection:{url:f?.url??``},principal:i,request:e.callback,state:e.state});writeCachedToken(r,n,principalKey(i),a)}}try{let t=(await c.getClient(n).getTools())[d];if(!t?.execute)throw Error(`Connection tool "${qualifiedConnectionToolName(n,d)}" has no execute function.`);return t.execute(e,{})}catch(e){if(!isConnectionAuthorizationRequiredError(e)||!p)throw e;let t=getHookUrl(n);if(!t)throw e;let r=resolveConnectionPrincipal(n,p),{challenge:i,state:s}=await p.startAuthorization({callbackUrl:t,connection:{url:f?.url??``},principal:r});return requestAuthorization([{name:n,challenge:i,hookUrl:t,state:s}])}}}}return _}}}function createConnectionSearchResolver(){let e=createConnectionSearchEvents();return{slug:`connection`,eventNames:Object.keys(e),events:e,sourceId:`ash:connection-search-dynamic`,sourceKind:`module`,logicalPath:`ash:framework/connection-search-dynamic`}}export{createConnectionSearchEvents,createConnectionSearchResolver,extractDiscoveredTools};

package/dist/src/runtime/sandbox/keys.d.ts

@@ -1,4 +1,5 @@
 import { type RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import type { RuntimeSandboxTemplatePlan } from "#runtime/sandbox/template-plan.js";
 /**
  * Input for deriving the stable runtime keys used for one sandbox definition.
  */
@@ -8,6 +9,7 @@ interface CreateRuntimeSandboxKeysInput {
     readonly nodeId: string;
     readonly sessionId: string;
     readonly sourceId: string;
+    readonly templatePlan: RuntimeSandboxTemplatePlan;
 }
 /**
  * Creates the stable runtime template and session keys for one sandbox
@@ -15,10 +17,11 @@ interface CreateRuntimeSandboxKeysInput {
  */
 export declare function createRuntimeSandboxKeys(input: CreateRuntimeSandboxKeysInput): Promise<{
     readonly sessionKey: string;
-    readonly templateKey: string;
+    readonly templateKey: string | null;
 }>;
 /**
- * Creates the stable reusable template key for one sandbox definition.
+ * Creates the stable reusable template key for one sandbox definition,
+ * or `null` when the sandbox should start from a fresh backend runtime.
  *
  * The template key factors in the graph `nodeId` so that two
  * runtime agents (root and subagents) do not collide on the same
@@ -30,5 +33,6 @@ export declare function createRuntimeSandboxTemplateKey(input: {
     readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
     readonly nodeId: string;
     readonly sourceId: string;
-}): Promise<string>;
+    readonly templatePlan: RuntimeSandboxTemplatePlan;
+}): Promise<string | null>;
 export {};

package/dist/src/runtime/sandbox/keys.js

@@ -1 +1 @@
-import{realpath}from"node:fs/promises";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createHash}from"node:crypto";import{getRuntimeCompiledArtifactsAppRoot,getRuntimeCompiledArtifactsCacheKey}from"#runtime/compiled-artifacts-source.js";import{loadCompileMetadata}from"#runtime/loaders/compile-metadata.js";async function createRuntimeSandboxKeys(e){return{sessionKey:await createRuntimeSandboxSessionKey(e),templateKey:await createRuntimeSandboxTemplateKey(e)}}async function createRuntimeSandboxTemplateKey(e){let n=await resolveRuntimeSandboxScope(e.backendName,e.compiledArtifactsSource),r=await resolveRuntimeSandboxVersionHash({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:e.nodeId,sourceId:e.sourceId}),i=createStableHash(`${resolveInstalledPackageInfo().version}:2:${r}`).slice(0,20);return sanitizeRuntimeSandboxKey(`ash-sbx-tpl-${e.backendName}-${n}-${i}`)}async function createRuntimeSandboxSessionKey(e){let t=await resolveRuntimeSandboxScope(e.backendName,e.compiledArtifactsSource),n=sanitizeRuntimeSandboxKey(e.nodeId);return sanitizeRuntimeSandboxKey(`ash-sbx-ses-${e.backendName}-${t}-${e.sessionId}-${n}`)}async function resolveRuntimeSandboxScope(t,n){if(t===`vercel`){let e=process.env.VERCEL_DEPLOYMENT_ID?.trim();if(e!==void 0&&e.length>0)return createStableHash(e).slice(0,16)}let a=getRuntimeCompiledArtifactsAppRoot(n);return a===void 0?createStableHash(getRuntimeCompiledArtifactsCacheKey(n)).slice(0,16):createStableHash(await realpath(a)).slice(0,16)}async function resolveRuntimeSandboxVersionHash(e){return createStableHash(`${(await loadCompileMetadata({compiledArtifactsSource:e.compiledArtifactsSource}))?.discovery.sourceGraphHash??getRuntimeCompiledArtifactsCacheKey(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`)}function createStableHash(e){return createHash(`sha256`).update(e).digest(`hex`)}function sanitizeRuntimeSandboxKey(e){return e.replaceAll(/[^a-zA-Z0-9._-]+/g,`-`).slice(0,120)}export{createRuntimeSandboxKeys,createRuntimeSandboxTemplateKey};
+import{realpath}from"node:fs/promises";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createHash}from"node:crypto";import{getRuntimeCompiledArtifactsAppRoot,getRuntimeCompiledArtifactsCacheKey}from"#runtime/compiled-artifacts-source.js";import{loadCompileMetadata}from"#runtime/loaders/compile-metadata.js";async function createRuntimeSandboxKeys(e){return{sessionKey:await createRuntimeSandboxSessionKey(e),templateKey:await createRuntimeSandboxTemplateKey(e)}}async function createRuntimeSandboxTemplateKey(e){if(e.templatePlan.kind===`none`)return null;let n=await resolveRuntimeSandboxScope({backendName:e.backendName,compiledArtifactsSource:e.compiledArtifactsSource,scopeKind:e.templatePlan.kind===`source-graph`?`deployment`:`stable`}),r=await resolveRuntimeSandboxVersionHash({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:e.nodeId,sourceId:e.sourceId,templatePlan:e.templatePlan}),i=createStableHash(`${resolveInstalledPackageInfo().version}:3:${r}`).slice(0,20);return sanitizeRuntimeSandboxKey(`ash-sbx-tpl-${e.backendName}-${n}-${i}`)}async function createRuntimeSandboxSessionKey(e){let t=await resolveRuntimeSandboxScope({backendName:e.backendName,compiledArtifactsSource:e.compiledArtifactsSource,scopeKind:`deployment`}),n=sanitizeRuntimeSandboxKey(e.nodeId);return sanitizeRuntimeSandboxKey(`ash-sbx-ses-${e.backendName}-${t}-${e.sessionId}-${n}`)}async function resolveRuntimeSandboxScope(t){if(t.backendName===`vercel`){if(t.scopeKind===`stable`){let e=resolveVercelProjectScope();if(e!==void 0)return createStableHash(e).slice(0,16)}let e=process.env.VERCEL_DEPLOYMENT_ID?.trim();if(e!==void 0&&e.length>0)return createStableHash(e).slice(0,16)}let n=getRuntimeCompiledArtifactsAppRoot(t.compiledArtifactsSource);return n===void 0?createStableHash(getRuntimeCompiledArtifactsCacheKey(t.compiledArtifactsSource)).slice(0,16):createStableHash(await realpath(n)).slice(0,16)}async function resolveRuntimeSandboxVersionHash(e){return e.templatePlan.kind===`workspace-content`?createStableHash(`workspace-content:${e.templatePlan.contentHash??await resolveSourceGraphHash(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`):createStableHash(`source-graph:${await resolveSourceGraphHash(e.compiledArtifactsSource)}:${e.nodeId}:${e.sourceId}`)}async function resolveSourceGraphHash(e){return(await loadCompileMetadata({compiledArtifactsSource:e}))?.discovery.sourceGraphHash??getRuntimeCompiledArtifactsCacheKey(e)}function resolveVercelProjectScope(){let e=process.env.VERCEL_PROJECT_ID?.trim();if(e===void 0||e.length===0)return;let t=process.env.VERCEL_TEAM_ID?.trim();return t===void 0||t.length===0?`vercel-project:${e}`:`vercel-project:${t}:${e}`}function createStableHash(e){return createHash(`sha256`).update(e).digest(`hex`)}function sanitizeRuntimeSandboxKey(e){return e.replaceAll(/[^a-zA-Z0-9._-]+/g,`-`).slice(0,120)}export{createRuntimeSandboxKeys,createRuntimeSandboxTemplateKey};

package/dist/src/runtime/sandbox/template-plan.d.ts

@@ -0,0 +1,21 @@
+import type { CompiledWorkspaceResourceRoot } from "#compiler/manifest.js";
+import type { ResolvedSandboxDefinition } from "#runtime/types.js";
+/**
+ * Describes whether one sandbox needs a prewarmed template and, if so,
+ * which inputs must participate in the template key.
+ */
+export type RuntimeSandboxTemplatePlan = {
+    readonly kind: "none";
+} | {
+    readonly contentHash?: string;
+    readonly kind: "workspace-content";
+} | {
+    readonly kind: "source-graph";
+};
+/**
+ * Chooses the template strategy for one resolved sandbox definition.
+ */
+export declare function createRuntimeSandboxTemplatePlan(input: {
+    readonly definition: ResolvedSandboxDefinition;
+    readonly workspaceResourceRoot: CompiledWorkspaceResourceRoot;
+}): RuntimeSandboxTemplatePlan;

package/dist/src/runtime/sandbox/template-plan.js

@@ -0,0 +1 @@
+function createRuntimeSandboxTemplatePlan(e){return e.definition.bootstrap===void 0?e.workspaceResourceRoot.rootEntries.length===0?{kind:`none`}:{contentHash:e.workspaceResourceRoot.contentHash,kind:`workspace-content`}:{kind:`source-graph`}}export{createRuntimeSandboxTemplatePlan};

package/dist/src/shared/dynamic-tool-definition.d.ts

@@ -1,6 +1,7 @@
 import type { ModelMessage } from "ai";
 import type { PublicToolInputSchema, ToolModelOutput } from "#shared/tool-definition.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
+import type { NeedsApprovalContext } from "#public/definitions/tool.js";
 import type { SessionAuth } from "#context/keys.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 type ToolContext = SessionContext;
@@ -35,6 +36,7 @@ export interface DynamicResolveContext {
     readonly channel: {
         readonly kind?: string;
         readonly continuationToken?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
     };
     readonly messages: readonly ModelMessage[];
 }
@@ -55,6 +57,15 @@ export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = an
     readonly inputSchema: PublicToolInputSchema<TInput>;
     execute(input: TInput, ctx: ToolContext): TOutput | Promise<TOutput>;
     readonly toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
+    /**
+     * Optional per-call approval gate. Mirrors the authored-tool
+     * `needsApproval` contract: return `true` to require user approval
+     * before the call executes. Only honored for step-scoped dynamic
+     * tools (whose live `execute` closures survive into the harness);
+     * session/turn-scoped tools replay from durable metadata and cannot
+     * carry a function across replay.
+     */
+    readonly needsApproval?: (ctx: NeedsApprovalContext) => boolean;
 }
 /**
  * A resolved tool set: keys are entry identifiers, values are tool

package/dist/src/shared/sandbox-backend.d.ts

@@ -59,7 +59,13 @@ export interface SandboxBackendRuntimeContext {
  * live sandbox session.
  */
 export interface SandboxBackendCreateInput {
-    readonly templateKey: string;
+    /**
+     * Reusable template key to open this session from. `null` means Ash
+     * intentionally skipped template prewarm because the sandbox has no
+     * `bootstrap()` and no seed files, so the backend should create a
+     * fresh session from its default base runtime.
+     */
+    readonly templateKey: string | null;
     readonly sessionKey: string;
     readonly existingMetadata?: Record<string, unknown>;
     /**
@@ -85,6 +91,20 @@ export interface SandboxBackendPrewarmInput<BO = Record<string, never>> {
     readonly runtimeContext: SandboxBackendRuntimeContext;
     readonly seedFiles: ReadonlyArray<SandboxSeedFile>;
 }
+/**
+ * Outcome of one {@link SandboxBackend.prewarm} call.
+ *
+ * The build pipeline uses this to report in the build logs whether a
+ * template snapshot was reused from a prior deploy or captured fresh, so
+ * a cache hit is distinguishable from an expensive rebuild.
+ */
+export interface SandboxBackendPrewarmResult {
+    /**
+     * `true` when an existing template snapshot was reused without
+     * rebuilding it; `false` when the backend captured a fresh snapshot.
+     */
+    readonly reused: boolean;
+}
 /**
  * Pluggable sandbox backend.
  *
@@ -119,6 +139,9 @@ export interface SandboxBackend<BO = Record<string, never>, SO = Record<string,
      * sandbox in the compiled graph before serving traffic so the backend
      * can capture a reusable template snapshot. Idempotent against an
      * existing snapshot keyed by `templateKey`.
+     *
+     * Returns whether the snapshot was reused from a prior run or captured
+     * fresh so the build pipeline can surface that in its logs.
      */
-    prewarm(input: SandboxBackendPrewarmInput<BO>): Promise<void>;
+    prewarm(input: SandboxBackendPrewarmInput<BO>): Promise<SandboxBackendPrewarmResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"