experimental-ash 0.28.1 → 0.30.0

package/dist/src/execution/dispatch-runtime-actions-step.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Starts every pending runtime action for the parked parent session.
+ *
+ * Each child run starts in task mode, emits a parent `subagent.called`
+ * control-plane event, and then runs independently on its own child
+ * stream. Records each child's continuation token on the parent
+ * session and appends the updated snapshot to `ash.session`.
+ */
+import type { RuntimeSubagentResultActionResult } from "#runtime/actions/types.js";
+import { type DurableSessionSnapshot, type DurableSessionState } from "#execution/durable-session-store.js";
+export declare function dispatchRuntimeActionsStep(input: {
+    readonly callbackBaseUrl?: string;
+    readonly parentWritable: WritableStream<Uint8Array>;
+    readonly serializedContext: Record<string, unknown>;
+    readonly sessionState: DurableSessionState;
+    readonly sessionWritable: WritableStream<DurableSessionSnapshot>;
+}): Promise<{
+    readonly results: readonly RuntimeSubagentResultActionResult[];
+    readonly sessionState: DurableSessionState;
+}>;

package/dist/src/execution/dispatch-runtime-actions-step.js

@@ -0,0 +1 @@
+import{toErrorMessage}from"#shared/errors.js";import{AuthKey,CapabilitiesKey,InitiatorAuthKey}from"#context/keys.js";import{createSubagentCalledEvent,encodeMessageStreamEvent,timestampHandleMessageStreamEvent}from"#protocol/message.js";import{callAdapterEventHandler}from"#channel/adapter.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{buildAdapterContext}from"#channel/adapter-context.js";import{deserializeContext}from"#context/serialize.js";import{readDurableSession,writeDurableSession}from"#execution/durable-session-store.js";import{hydrateDurableSession}from"#execution/session.js";import{getPendingRuntimeActionBatch,recordPendingSubagentChildToken}from"#harness/runtime-actions.js";import{resolveRemoteAgentForAction,startRemoteAgentSession}from"#execution/remote-agent-dispatch.js";import{buildSubagentRunInput}from"#execution/subagent-tool.js";import{createWorkflowRuntime,workflowEntryReference}from"#execution/workflow-runtime.js";async function dispatchRuntimeActionsStep(e){"use step";let u=await readDurableSession(e.sessionState),d=getPendingRuntimeActionBatch(u.state);if(d===void 0||d.actions.length===0)return{results:[],sessionState:e.sessionState};let f=await deserializeContext(e.serializedContext),p=f.require(BundleKey),m=hydrateDurableSession({compactionOverrides:{thresholdPercent:p.resolvedAgent.config.compaction?.thresholdPercent},durable:u,turnAgent:p.turnAgent}),h=f.require(ChannelKey),g=f.get(AuthKey)??null,_=f.get(CapabilitiesKey),v=f.get(InitiatorAuthKey)??null,y=e.parentWritable.getWriter(),b=buildAdapterContext(h,f),x=m,S=[];try{for(let t of d.actions){let n,r,s,c;switch(t.kind){case`subagent-call`:{let e=createWorkflowRuntime({compiledArtifactsSource:p.compiledArtifactsSource,nodeId:t.nodeId}),{childContinuationToken:i,runInput:a}=buildSubagentRunInput({action:t,auth:g,batchEvent:d.event,capabilities:_,initiatorAuth:v,session:m}),o=await e.run(a);x=recordPendingSubagentChildToken({callId:t.callId,childContinuationToken:i,session:x}),n=o.sessionId,r=t.name,c=t.subagentName;break}case`remote-agent-call`:{let i;try{i=resolveRemoteAgentForAction({nodeId:t.nodeId,remoteAgentName:t.remoteAgentName,registry:p.subagentRegistry.subagentsByNodeId}),n=await startRemoteAgentSession({action:t,callbackBaseUrl:e.callbackBaseUrl,remote:i,session:m})}catch(e){S.push(createRemoteAgentStartFailureResult({action:t,error:e}));continue}r=t.name,s={url:i.url},c=t.remoteAgentName;break}default:throw Error(`Unsupported runtime action kind "${t.kind}" in workflow runtime.`)}let l=await callAdapterEventHandler(h,createSubagentCalledEvent({callId:t.callId,childSessionId:n,name:r,remote:s,sequence:d.event.sequence,sessionId:m.sessionId,toolName:c,turnId:d.event.turnId,workflowId:workflowEntryReference.workflowId}),b);await y.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(l)))}}finally{y.releaseLock()}return{results:S,sessionState:x===m?e.sessionState:await writeDurableSession({session:x,writable:e.sessionWritable})}}function createRemoteAgentStartFailureResult(t){return{callId:t.action.callId,isError:!0,kind:`subagent-result`,output:{code:`REMOTE_AGENT_START_FAILED`,message:toErrorMessage(t.error)},subagentName:t.action.remoteAgentName}}export{dispatchRuntimeActionsStep};

package/dist/src/execution/durable-session-migrations/chain.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generic version-walking migration framework for versioned durable
+ * wire shapes. Each migration steps a value one version forward; the
+ * runner chains them so a value written at any historic version can
+ * be read at the current one.
+ */
+/**
+ * One migration step in a version chain. `to` MUST equal `from + 1`
+ * and `migrate` MUST stamp the returned value's `version` field with
+ * `to`; the runner verifies both.
+ */
+export interface VersionMigration {
+    readonly from: number;
+    readonly to: number;
+    migrate: (prior: unknown) => {
+        readonly version: number;
+    };
+}
+/**
+ * Walks `value` through `migrations` until its `version` matches
+ * `targetVersion`. Throws on missing migrations, malformed steps, or
+ * a value newer than the runner supports.
+ */
+export declare function runMigrationChain<TOut extends {
+    readonly version: number;
+}>(input: {
+    readonly value: unknown;
+    readonly migrations: readonly VersionMigration[];
+    readonly targetVersion: number;
+    readonly label: string;
+}): TOut;

package/dist/src/execution/durable-session-migrations/chain.js

@@ -0,0 +1 @@
+function runMigrationChain(e){if(typeof e.value!=`object`||e.value===null||!(`version`in e.value)||typeof e.value.version!=`number`)throw Error(`${e.label}: value has no numeric "version" field.`);let t=e.value;if(!Number.isInteger(t.version)||t.version<1)throw Error(`${e.label}: version ${t.version} is not a positive integer.`);if(t.version>e.targetVersion)throw Error(`${e.label}: encountered version ${t.version}, which is newer than the supported version ${e.targetVersion}. This usually indicates the wire was written by a newer Ash deployment than the one reading it.`);for(;t.version<e.targetVersion;){let n=e.migrations.find(e=>e.from===t.version);if(!n)throw Error(`${e.label}: no migration registered for version ${t.version} → ${t.version+1}.`);if(n.to!==n.from+1)throw Error(`${e.label}: migration ${n.from} → ${n.to} must step exactly one version at a time.`);let r=n.migrate(t);if(r.version!==n.to)throw Error(`${e.label}: migration ${n.from} → ${n.to} produced a value with version ${r.version}.`);t=r}return t}export{runMigrationChain};

package/dist/src/execution/durable-session-migrations/snapshot.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Durable session snapshot migrations.
+ *
+ * ## Adding a new snapshot version
+ *
+ * When a shape change cannot be expressed as a purely additive field:
+ *
+ * 1. Bump `DURABLE_SESSION_VERSION` in `durable-session-store.ts`.
+ * 2. Update {@link DurableSessionSnapshot}, {@link DurableSession},
+ *    `projectToDurableSession`, and `hydrateDurableSession`.
+ * 3. Add `snapshot-v{N}-to-v{N+1}.ts` exporting one
+ *    {@link VersionMigration} (`from: N`, `to: N + 1`, pure
+ *    function, stamps the new `version`).
+ * 4. Append the migration to {@link snapshotMigrations}.
+ * 5. Cover it in `snapshot.test.ts`.
+ */
+import type { DurableSessionSnapshot } from "#execution/durable-session-store.js";
+/**
+ * Migrates a {@link DurableSessionSnapshot} up to
+ * {@link DURABLE_SESSION_VERSION}. Pure; safe to call inline.
+ */
+export declare function migrateDurableSessionSnapshot(value: unknown): DurableSessionSnapshot;

package/dist/src/execution/durable-session-migrations/snapshot.js

@@ -0,0 +1 @@
+import{runMigrationChain}from"./chain.js";import{DURABLE_SESSION_VERSION}from"#execution/durable-session-store.js";const snapshotMigrations=[];function migrateDurableSessionSnapshot(e){return runMigrationChain({label:`durable session snapshot`,migrations:snapshotMigrations,targetVersion:DURABLE_SESSION_VERSION,value:e})}export{migrateDurableSessionSnapshot};

package/dist/src/execution/durable-session-store.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Durable session storage.
+ *
+ * Each driver workflow run owns one stream at namespace `"ash.session"`.
+ * Session-mutating steps append one snapshot per mutation; reads pull
+ * the tail (`startIndex: -1`). Step inputs, step results, and hook
+ * payloads carry a small {@link DurableSessionState} value — never the
+ * full {@link HarnessSession}.
+ *
+ * The driver workflow run is pinned to the deployment that called
+ * `start()`; child turn workflows run on latest. Both
+ * {@link DurableSessionState} and {@link DurableSessionSnapshot} carry
+ * a `version` so a pinned driver can ferry shapes written by newer
+ * steps. Adding optional fields is forward-compatible (devalue
+ * preserves unknown POJO fields); shape-breaking changes bump
+ * `version` and add a migrator.
+ */
+import type { ModelMessage } from "ai";
+import { type HarnessEmissionState } from "#harness/emission.js";
+import type { HarnessSession, SessionStateMap } from "#harness/types.js";
+import type { SandboxState } from "#sandbox/state.js";
+/** Workflow stream namespace where every session snapshot lands. */
+export declare const ASH_SESSION_STREAM_NAMESPACE = "ash.session";
+/** Current wire version for {@link DurableSessionState} and {@link DurableSessionSnapshot}. */
+export declare const DURABLE_SESSION_VERSION = 1;
+/**
+ * Serializable handle to a durable session.
+ *
+ * Carries only the small projections the workflow body needs without
+ * taking a step boundary: identity, the hook continuation token,
+ * `hasProxyInputRequests` (a closed-contract short-circuit that lets
+ * the driver skip a per-delivery proxy-routing step when no
+ * descendant subagent is active), and `emissionState` (so workflow-body
+ * orchestrators — eg. await-authorization — can stamp protocol events
+ * with `{ turnId, sequence, stepIndex }` without reading the full
+ * durable session). All other control-plane state travels via
+ * {@link import("#execution/next-driver-action.js").NextDriverAction}.
+ */
+export interface DurableSessionState {
+    readonly version: typeof DURABLE_SESSION_VERSION;
+    readonly sessionId: string;
+    readonly continuationToken: string;
+    readonly hasProxyInputRequests: boolean;
+    readonly emissionState: HarnessEmissionState;
+}
+/**
+ * Durable projection of {@link HarnessSession} written to the
+ * `ash.session` stream.
+ *
+ * Omits `agent.modelReference`, `agent.tools`,
+ * `agent.compactionModelReference`, and the `compaction` thresholds —
+ * those are rebuilt every turn from `bundle.turnAgent` by
+ * {@link import("#execution/session.js").hydrateDurableSession}.
+ * `agent.system` is the session-start prompt snapshot, pinned at
+ * `createSession`.
+ */
+export interface DurableSession {
+    readonly sessionId: string;
+    readonly continuationToken: string;
+    readonly history: ModelMessage[];
+    readonly state?: SessionStateMap;
+    readonly sandboxState?: SandboxState;
+    readonly agent: {
+        readonly system: string;
+    };
+    readonly compaction?: {
+        readonly lastKnownInputTokens?: number;
+        readonly lastKnownPromptMessageCount?: number;
+    };
+}
+/** Versioned wrapper around a {@link DurableSession} on the wire. */
+export interface DurableSessionSnapshot {
+    readonly version: typeof DURABLE_SESSION_VERSION;
+    readonly session: DurableSession;
+}
+/** Projects a {@link HarnessSession} into the boundary-safe state value. */
+export declare function projectSessionState(input: {
+    readonly session: HarnessSession;
+}): DurableSessionState;
+/**
+ * Reads the latest snapshot from the `ash.session` stream and returns
+ * the {@link DurableSession} inside.
+ *
+ * Always pulls the tail chunk (`startIndex: -1`); the
+ * single-writer-per-session-stream invariant makes that safe. The
+ * snapshot is migrated to {@link DURABLE_SESSION_VERSION} before
+ * return; unknown versions throw.
+ *
+ * Devalue handles encode/decode so rich types in the session (URL
+ * `FilePart.data`, Buffer, Date, Map, Set) round-trip structurally.
+ *
+ * MUST be called from inside a `"use step"` body.
+ */
+export declare function readDurableSession(state: DurableSessionState): Promise<DurableSession>;
+/**
+ * Appends one snapshot to the `ash.session` stream and returns the
+ * projected {@link DurableSessionState}.
+ *
+ * MUST be called from inside a `"use step"` body.
+ */
+export declare function writeDurableSession(input: {
+    readonly session: HarnessSession;
+    readonly writable: WritableStream<DurableSessionSnapshot>;
+}): Promise<DurableSessionState>;

package/dist/src/execution/durable-session-store.js

@@ -0,0 +1 @@
+import{getHarnessEmissionState}from"#harness/emission.js";import{projectToDurableSession}from"#execution/session.js";import{hasProxyInputRequests}from"#harness/proxy-input-requests.js";import{migrateDurableSessionSnapshot}from"#execution/durable-session-migrations/snapshot.js";const ASH_SESSION_STREAM_NAMESPACE=`ash.session`,DURABLE_SESSION_VERSION=1;function projectSessionState(t){return{continuationToken:t.session.continuationToken,emissionState:getHarnessEmissionState(t.session.state),hasProxyInputRequests:hasProxyInputRequests(t.session.state),sessionId:t.session.sessionId,version:1}}async function readDurableSession(e){let{getRun:t}=await import(`#compiled/@workflow/core/runtime.js`),{value:n,done:i}=await t(e.sessionId).getReadable({namespace:ASH_SESSION_STREAM_NAMESPACE,startIndex:-1}).getReader().read();if(i||n===void 0)throw Error(`No durable session snapshot found in stream "${ASH_SESSION_STREAM_NAMESPACE}" for run ${e.sessionId}.`);return migrateDurableSessionSnapshot(n).session}async function writeDurableSession(e){let n={session:projectToDurableSession(e.session),version:1},r=e.writable.getWriter();try{await r.write(n)}finally{r.releaseLock()}return projectSessionState({session:e.session})}export{ASH_SESSION_STREAM_NAMESPACE,DURABLE_SESSION_VERSION,projectSessionState,readDurableSession,writeDurableSession};

package/dist/src/execution/next-driver-action.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Closed-contract dispatch surface between session-mutating step
+ * bodies (latest deployment) and the durable driver workflow (pinned
+ * to whichever deployment called `start()`).
+ *
+ * The driver matches on `kind` and follows a fixed playbook per arm.
+ * Adding a new arm is breaking (pinned drivers can't dispatch an
+ * unknown `kind`); adding optional fields inside an existing arm is
+ * forward-compatible because the driver passes the action through by
+ * reference and devalue preserves unknown POJO fields. Do not
+ * destructure-and-rebuild a `NextDriverAction` — full destructuring
+ * strips unknown fields.
+ */
+import type { DurableSessionState } from "#execution/durable-session-store.js";
+/** Discriminated union the driver workflow body dispatches on. */
+export type NextDriverAction = {
+    readonly kind: "done";
+    readonly output: string;
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+} | {
+    readonly kind: "park";
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+} | {
+    readonly kind: "dispatch-runtime-actions";
+    readonly pendingActionKeys: readonly string[];
+    readonly sessionState: DurableSessionState;
+    readonly serializedContext: Record<string, unknown>;
+};

package/dist/src/execution/next-driver-action.js

@@ -0,0 +1 @@
+export{};

package/dist/src/execution/sandbox/prewarm.d.ts

@@ -1,5 +1,5 @@
 import type { SandboxBackend, SandboxBackendPrewarmInput } from "#public/definitions/sandbox-backend.js";
-import type { RuntimeDiskCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { type RuntimeCompiledArtifactsSource, type RuntimeDiskCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
 import { type ResolvedAgentGraphBundle } from "#runtime/graph.js";
 /**
  * Optional dispatch override that intercepts every `backend.prewarm`
@@ -13,7 +13,8 @@ export type SandboxBackendPrewarmDispatch = (input: {
     readonly input: SandboxBackendPrewarmInput;
 }) => Promise<void>;
 interface PrewarmSandboxesInput {
-    readonly compiledArtifactsSource: RuntimeDiskCompiledArtifactsSource;
+    readonly appRoot: string;
+    readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
     readonly graph: ResolvedAgentGraphBundle;
     readonly log?: (message: string) => void;
     readonly dispatch?: SandboxBackendPrewarmDispatch;
@@ -43,4 +44,13 @@ export declare function prewarmAppSandboxes(input: {
     readonly log?: (message: string) => void;
     readonly dispatch?: SandboxBackendPrewarmDispatch;
 }): Promise<void>;
+/**
+ * Loads one built app's bundled compiled artifacts and prewarms the sandbox
+ * templates that its production Nitro runtime will request.
+ */
+export declare function prewarmBuiltAppSandboxes(input: {
+    readonly appRoot: string;
+    readonly log?: (message: string) => void;
+    readonly dispatch?: SandboxBackendPrewarmDispatch;
+}): Promise<void>;
 export {};

package/dist/src/execution/sandbox/prewarm.js

@@ -1 +1 @@
-import{toErrorMessage}from"#shared/errors.js";import{createRuntimeSandboxTemplateKey}from"#runtime/sandbox/keys.js";import{loadCompiledModuleMapFromAuthoredSource}from"#internal/authored-module-map-loader.js";import{createAuthoredSourceRuntimeCompiledArtifactsSource}from"#internal/application/runtime-compiled-artifacts-source.js";import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{loadCompiledManifest}from"#runtime/loaders/manifest.js";import{resolveRuntimeCompilerArtifactPaths}from"#runtime/loaders/artifact-paths.js";import{resolveRuntimeAgentGraph}from"#runtime/resolve-agent-graph.js";import{materializeWorkspaceDirectory}from"#runtime/workspace/seed-files.js";async function prewarmSandboxes(t){let n=await collectPrewarmTargets(t);if(n.length===0)return;t.log?.(`Ash: initializing ${n.length} sandbox ${pluralize(n.length,`template`)}...`);let r=t.dispatch??(async({backend:e,input:t})=>{await e.prewarm(t)});await Promise.all(n.map(async({backend:n,label:i,input:a})=>{t.log?.(`Ash: initializing sandbox template "${i}"...`);try{await r({backend:n,input:a})}catch(r){throw t.log?.(`Ash: failed to initialize sandbox template "${i}" on backend "${n.name}": ${toErrorMessage(r)}`),r}t.log?.(`Ash: sandbox template "${i}" initialized.`)})),t.log?.(`Ash: initialized ${n.length} sandbox ${pluralize(n.length,`template`)}.`)}async function prewarmAppSandboxes(e){let t=createAuthoredSourceRuntimeCompiledArtifactsSource(e.appRoot),n=await(e.loadAgentGraph??loadGraphFromArtifacts)({compiledArtifactsSource:t});await prewarmSandboxes({compiledArtifactsSource:t,dispatch:e.dispatch,graph:n,log:e.log})}async function collectPrewarmTargets(e){let n=resolveRuntimeCompilerArtifactPaths(e.compiledArtifactsSource.appRoot).compileDirectoryPath,r={appRoot:e.compiledArtifactsSource.appRoot};return[...await Promise.all(collectNodeSandboxes(e.graph).map(async({definition:i,nodeId:a,workspaceResourceRoot:o})=>{let s=await createRuntimeSandboxTemplateKey({backendName:i.backend.name,compiledArtifactsSource:e.compiledArtifactsSource,nodeId:a,sourceId:i.sourceId});return{backend:i.backend,label:formatLabel(a),input:{bootstrap:i.bootstrap,seedFiles:await loadResourceRootSeedFiles({compileDirectoryPath:n,workspaceResourceRoot:o}),runtimeContext:r,templateKey:s}}}))].sort((e,t)=>e.label.localeCompare(t.label))}async function loadResourceRootSeedFiles(e){return e.workspaceResourceRoot.rootEntries.length===0?[]:(await materializeWorkspaceDirectory(`${e.compileDirectoryPath}/${e.workspaceResourceRoot.logicalPath}`)).map(e=>({content:e.content,path:e.path}))}async function loadGraphFromArtifacts(e){let[t,r]=await Promise.all([loadCompiledManifest({compiledArtifactsSource:e.compiledArtifactsSource}),loadCompiledModuleMapFromAuthoredSource({compiledArtifactsSource:e.compiledArtifactsSource})]);return await resolveRuntimeAgentGraph({manifest:t,moduleMap:r})}function collectNodeSandboxes(e){return[...e.nodesByNodeId.entries()].flatMap(([e,t])=>{let n=t.sandboxRegistry.sandbox;return n===null?[]:[{...n,nodeId:e}]})}function pluralize(e,t){return e===1?t:`${t}s`}function formatLabel(e){return e===ROOT_RUNTIME_AGENT_NODE_ID?`root`:e}export{prewarmAppSandboxes,prewarmSandboxes};
+import{toErrorMessage}from"#shared/errors.js";import{createBundledRuntimeCompiledArtifactsSource}from"#runtime/compiled-artifacts-source.js";import{createRuntimeSandboxTemplateKey}from"#runtime/sandbox/keys.js";import{loadCompiledModuleMapFromAuthoredSource}from"#internal/authored-module-map-loader.js";import{createAuthoredSourceRuntimeCompiledArtifactsSource}from"#internal/application/runtime-compiled-artifacts-source.js";import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{loadCompileMetadata}from"#runtime/loaders/compile-metadata.js";import{withBundledCompiledArtifacts}from"#runtime/loaders/bundled-artifacts.js";import{loadCompiledManifest}from"#runtime/loaders/manifest.js";import{resolveRuntimeCompilerArtifactPaths}from"#runtime/loaders/artifact-paths.js";import{resolveRuntimeAgentGraph}from"#runtime/resolve-agent-graph.js";import{materializeWorkspaceDirectory}from"#runtime/workspace/seed-files.js";async function prewarmSandboxes(t){let n=await collectPrewarmTargets(t);if(n.length===0)return;t.log?.(`Ash: initializing ${n.length} sandbox ${pluralize(n.length,`template`)}...`);let r=t.dispatch??(async({backend:e,input:t})=>{await e.prewarm(t)});await Promise.all(n.map(async({backend:n,label:i,input:a})=>{t.log?.(`Ash: initializing sandbox template "${i}"...`);try{await r({backend:n,input:a})}catch(r){throw t.log?.(`Ash: failed to initialize sandbox template "${i}" on backend "${n.name}": ${toErrorMessage(r)}`),r}t.log?.(`Ash: sandbox template "${i}" initialized.`)})),t.log?.(`Ash: initialized ${n.length} sandbox ${pluralize(n.length,`template`)}.`)}async function prewarmAppSandboxes(e){let t=createAuthoredSourceRuntimeCompiledArtifactsSource(e.appRoot),n=await(e.loadAgentGraph??loadGraphFromArtifacts)({compiledArtifactsSource:t});await prewarmSandboxes({appRoot:e.appRoot,compiledArtifactsSource:t,dispatch:e.dispatch,graph:n,log:e.log})}async function prewarmBuiltAppSandboxes(e){let n=createAuthoredSourceRuntimeCompiledArtifactsSource(e.appRoot),[a,c,l]=await Promise.all([loadCompileMetadata({compiledArtifactsSource:n}),loadCompiledManifest({compiledArtifactsSource:n}),loadCompiledModuleMapFromAuthoredSource({compiledArtifactsSource:n})]);await withBundledCompiledArtifacts({manifest:c,metadata:a??void 0,moduleMap:l,sessionId:`built-app-prewarm`},async()=>{let n=createBundledRuntimeCompiledArtifactsSource(),r=await resolveRuntimeAgentGraph({manifest:c,moduleMap:l});await prewarmSandboxes({appRoot:e.appRoot,compiledArtifactsSource:n,dispatch:e.dispatch,graph:r,log:e.log})})}async function collectPrewarmTargets(e){let t=resolveRuntimeCompilerArtifactPaths(e.appRoot).compileDirectoryPath,r={appRoot:e.appRoot};return[...await Promise.all(collectNodeSandboxes(e.graph).map(async({definition:i,nodeId:a,workspaceResourceRoot:o})=>{let s=await createRuntimeSandboxTemplateKey({backendName:i.backend.name,compiledArtifactsSource:e.compiledArtifactsSource,nodeId:a,sourceId:i.sourceId});return{backend:i.backend,label:formatLabel(a),input:{bootstrap:i.bootstrap,seedFiles:await loadResourceRootSeedFiles({compileDirectoryPath:t,workspaceResourceRoot:o}),runtimeContext:r,templateKey:s}}}))].sort((e,t)=>e.label.localeCompare(t.label))}async function loadResourceRootSeedFiles(e){return e.workspaceResourceRoot.rootEntries.length===0?[]:(await materializeWorkspaceDirectory(`${e.compileDirectoryPath}/${e.workspaceResourceRoot.logicalPath}`)).map(e=>({content:e.content,path:e.path}))}async function loadGraphFromArtifacts(e){let[t,n]=await Promise.all([loadCompiledManifest({compiledArtifactsSource:e.compiledArtifactsSource}),loadCompiledModuleMapFromAuthoredSource({compiledArtifactsSource:e.compiledArtifactsSource})]);return await resolveRuntimeAgentGraph({manifest:t,moduleMap:n})}function collectNodeSandboxes(e){return[...e.nodesByNodeId.entries()].flatMap(([e,t])=>{let n=t.sandboxRegistry.sandbox;return n===null?[]:[{...n,nodeId:e}]})}function pluralize(e,t){return e===1?t:`${t}s`}function formatLabel(e){return e===ROOT_RUNTIME_AGENT_NODE_ID?`root`:e}export{prewarmAppSandboxes,prewarmBuiltAppSandboxes,prewarmSandboxes};

package/dist/src/execution/session.d.ts

@@ -1,3 +1,4 @@
+import type { DurableSession } from "#execution/durable-session-store.js";
 import type { HarnessSession } from "#harness/types.js";
 import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";
 /**
@@ -17,17 +18,6 @@ export declare function createCompactionConfig(input?: {
     lastKnownInputTokens: number;
     lastKnownPromptMessageCount: number | undefined;
 };
-/**
- * Input for {@link createSession}.
- *
- * `turnAgent` is the already-resolved agent definition that will drive the
- * session — either the root turn agent from a compiled bundle, or a child
- * subagent's turn agent from a resolved graph node.
- *
- * `compactionOverrides` lets the caller override compaction defaults (e.g. a
- * root caller forwarding an authored `thresholdPercent` from the resolved
- * agent config). Subagent callers typically omit this.
- */
 export interface CreateSessionInput {
     readonly continuationToken: string;
     readonly compactionOverrides?: {
@@ -37,22 +27,15 @@ export interface CreateSessionInput {
     readonly turnAgent: RuntimeTurnAgent;
 }
 /**
- * Creates a fresh serializable {@link HarnessSession} for a harness run.
- *
- * This is the only place that derives `session.agent.system` from a
- * `turnAgent`. The system prompt is a session-start snapshot: once
- * created here it is preserved unchanged for every subsequent turn.
- * Use {@link refreshSessionFromTurnAgent} to update model/tool metadata
- * on an existing session without touching the system prompt.
+ * Creates a fresh {@link HarnessSession}. The only site that derives
+ * `session.agent.system` from a `turnAgent` — every subsequent turn
+ * preserves the prompt via {@link refreshSessionFromTurnAgent}.
  */
 export declare function createSession(input: CreateSessionInput): HarnessSession;
 /**
- * Refreshes one existing session with the latest resolved turn-agent shape.
- *
- * Preserves durable history, state, and the system prompt while replacing
- * model/tool metadata and recalculating compaction thresholds from current
- * authored config. The system prompt is a session-start snapshot set by
- * {@link createSession} and is never rebuilt during refresh.
+ * Refreshes a session with the latest `turnAgent` — replaces model/tool
+ * metadata and recalculates compaction thresholds; preserves history,
+ * state, and the session-start `agent.system` prompt.
  */
 export declare function refreshSessionFromTurnAgent(input: {
     readonly session: HarnessSession;
@@ -63,9 +46,27 @@ export declare function refreshSessionFromTurnAgent(input: {
 }): HarnessSession;
 /**
  * Mints a continuation token for a delegated subagent session.
- *
- * The `subagent:` prefix identifies the token as a child run handle. The
- * token is deterministic per parent call when `suffix` is provided so runtime
- * retries can address the same delegated child hook token.
+ * Deterministic when `suffix` is provided so retries address the same
+ * child hook.
  */
 export declare function mintSubagentContinuationToken(suffix?: string): string;
+/**
+ * Projects a {@link HarnessSession} to {@link DurableSession}.
+ *
+ * Drops fields rebuilt every turn from `bundle.turnAgent`; keeps
+ * `agent.system` and `compaction.lastKnown*` so compaction stays
+ * informed after rehydration.
+ */
+export declare function projectToDurableSession(session: HarnessSession): DurableSession;
+/**
+ * Rehydrates a {@link HarnessSession} from a {@link DurableSession}
+ * plus the current `turnAgent`, rebuilding the runtime-only agent and
+ * compaction fields the durable shape omits.
+ */
+export declare function hydrateDurableSession(input: {
+    readonly durable: DurableSession;
+    readonly turnAgent: RuntimeTurnAgent;
+    readonly compactionOverrides?: {
+        readonly thresholdPercent?: number;
+    };
+}): HarnessSession;

package/dist/src/execution/session.js

@@ -1,3 +1,3 @@
 function createCompactionConfig(e={}){let t=e.thresholdPercent??.9,n={recentWindowSize:10,threshold:e.contextWindowTokens===void 0?1e5:Math.max(1,Math.floor(e.contextWindowTokens*t))};return e.lastKnownInputTokens===void 0?n:{...n,lastKnownInputTokens:e.lastKnownInputTokens,lastKnownPromptMessageCount:e.lastKnownPromptMessageCount}}function createSession(e){let{turnAgent:t}=e,n=createSessionToolDefinitions(t);return{agent:{compactionModelReference:t.compactionModel,modelReference:t.model,system:t.instructions.join(`
 
-`),tools:n},compaction:createCompactionConfig({contextWindowTokens:t.model.contextWindowTokens,thresholdPercent:e.compactionOverrides?.thresholdPercent}),continuationToken:e.continuationToken,history:[],sessionId:e.sessionId}}function refreshSessionFromTurnAgent(e){return{...e.session,agent:{compactionModelReference:e.turnAgent.compactionModel,modelReference:e.turnAgent.model,system:e.session.agent.system,tools:createSessionToolDefinitions(e.turnAgent)},compaction:createCompactionConfig({contextWindowTokens:e.turnAgent.model.contextWindowTokens,lastKnownInputTokens:e.session.compaction.lastKnownInputTokens,lastKnownPromptMessageCount:e.session.compaction.lastKnownPromptMessageCount,thresholdPercent:e.compactionOverrides?.thresholdPercent})}}function mintSubagentContinuationToken(e){return`subagent:${e??crypto.randomUUID()}`}function createSessionToolDefinitions(e){return e.tools.map(e=>({description:e.description??``,inputSchema:e.inputSchema,name:e.name}))}export{createCompactionConfig,createSession,mintSubagentContinuationToken,refreshSessionFromTurnAgent};
+`),tools:n},compaction:createCompactionConfig({contextWindowTokens:t.model.contextWindowTokens,thresholdPercent:e.compactionOverrides?.thresholdPercent}),continuationToken:e.continuationToken,history:[],sessionId:e.sessionId}}function refreshSessionFromTurnAgent(e){return{...e.session,agent:{compactionModelReference:e.turnAgent.compactionModel,modelReference:e.turnAgent.model,system:e.session.agent.system,tools:createSessionToolDefinitions(e.turnAgent)},compaction:createCompactionConfig({contextWindowTokens:e.turnAgent.model.contextWindowTokens,lastKnownInputTokens:e.session.compaction.lastKnownInputTokens,lastKnownPromptMessageCount:e.session.compaction.lastKnownPromptMessageCount,thresholdPercent:e.compactionOverrides?.thresholdPercent})}}function mintSubagentContinuationToken(e){return`subagent:${e??crypto.randomUUID()}`}function projectToDurableSession(e){let t={agent:{system:e.agent.system},continuationToken:e.continuationToken,history:e.history,sessionId:e.sessionId};return(e.compaction.lastKnownInputTokens!==void 0||e.compaction.lastKnownPromptMessageCount!==void 0)&&(t.compaction={lastKnownInputTokens:e.compaction.lastKnownInputTokens,lastKnownPromptMessageCount:e.compaction.lastKnownPromptMessageCount}),e.sandboxState!==void 0&&(t.sandboxState=e.sandboxState),e.state!==void 0&&(t.state=e.state),t}function hydrateDurableSession(e){let{durable:t,turnAgent:n}=e,r=createSessionToolDefinitions(n),i={agent:{compactionModelReference:n.compactionModel,modelReference:n.model,system:t.agent.system,tools:r},compaction:createCompactionConfig({contextWindowTokens:n.model.contextWindowTokens,lastKnownInputTokens:t.compaction?.lastKnownInputTokens,lastKnownPromptMessageCount:t.compaction?.lastKnownPromptMessageCount,thresholdPercent:e.compactionOverrides?.thresholdPercent}),continuationToken:t.continuationToken,history:t.history,sessionId:t.sessionId};return t.sandboxState!==void 0&&(i.sandboxState=t.sandboxState),t.state!==void 0&&(i.state=t.state),i}function createSessionToolDefinitions(e){return e.tools.map(e=>({description:e.description??``,inputSchema:e.inputSchema,name:e.name}))}export{createCompactionConfig,createSession,hydrateDurableSession,mintSubagentContinuationToken,projectToDurableSession,refreshSessionFromTurnAgent};

package/dist/src/execution/subagent-hitl-proxy.d.ts

@@ -1,13 +1,10 @@
 import type { DeliverPayload, SubagentInputRequestHookPayload } from "#channel/types.js";
-import type { HarnessEmitFn, HarnessSession } from "#harness/types.js";
+import type { HarnessEmitFn, HarnessSession, SessionStateMap } from "#harness/types.js";
 import type { RunMode } from "#shared/run-mode.js";
 import type { InputResponse } from "#runtime/input/types.js";
 /**
- * Runs the parent-side work when a `subagent-input-request` arrives at
- * the workflow runtime.
- *
- * Conversation mode emits a waiting boundary on the parent stream while
- * the parent harness remains parked on the child call; the returned proxy
+ * Runs the parent-side work for a `subagent-input-request`. Conversation
+ * mode emits a waiting boundary on the parent stream; the returned proxy
  * entries route the eventual response back down to the child.
  */
 export declare function emitProxiedInputRequest(input: {
@@ -20,16 +17,9 @@ export declare function emitProxiedInputRequest(input: {
     readonly session: HarnessSession;
 }>;
 /**
- * Outcome of splitting one deliver payload into parent-local and
- * proxied-child buckets.
- *
- * `forSelf` carries the payload the parent's own harness should see —
- * every non-`inputResponses` field is preserved verbatim, and any
- * response whose `requestId` does not match a proxy entry stays here.
- *
- * `forChildren` carries one payload per distinct descendant
- * continuation token. Each payload contains only the responses that
- * target that child.
+ * Outcome of splitting one deliver payload by the session's proxy map.
+ * `forSelf` is the parent-local remainder (or `undefined` when fully
+ * routed); `forChildren` carries one entry per descendant token.
  */
 export interface RoutedDeliverPayload {
     readonly forChildren: readonly {
@@ -40,15 +30,8 @@ export interface RoutedDeliverPayload {
     }[];
     readonly forSelf: DeliverPayload | undefined;
 }
-/**
- * Splits an inbound {@link DeliverPayload} into parent-local and
- * proxied-child buckets based on the session's proxy map.
- *
- * When a payload carries neither a parent-local response nor any
- * adapter-specific field, `forSelf` is `undefined` and the parent
- * should re-park without running a model turn.
- */
+/** Splits a deliver payload into parent-local and proxied-child buckets. */
 export declare function routeDeliverPayload(input: {
     readonly payload: DeliverPayload;
-    readonly session: HarnessSession;
+    readonly state: SessionStateMap | undefined;
 }): RoutedDeliverPayload;

package/dist/src/execution/subagent-hitl-proxy.js

@@ -1 +1 @@
-import{createInputRequestedEvent}from"#protocol/message.js";import{emitTurnEpilogue,getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";import{getProxyInputRequests,toProxyInputRequestEntries}from"#harness/proxy-input-requests.js";async function emitProxiedInputRequest(i){await i.emit(createInputRequestedEvent({requests:i.hookPayload.event.requests,sequence:i.hookPayload.event.sequence,stepIndex:i.hookPayload.event.stepIndex,turnId:i.hookPayload.event.turnId}));let o=i.session;if(i.mode===`conversation`){let e=getHarnessEmissionState(i.session),a=await emitTurnEpilogue(i.emit,e,i.mode);o=setHarnessEmissionState(i.session,a)}return{entries:toProxyInputRequestEntries(i.hookPayload),session:o}}function routeDeliverPayload(e){let t=getProxyInputRequests(e.session),n=e.payload.inputResponses??[],r=new Map,a=[];for(let e of n){let n=t.get(e.requestId);if(n===void 0){a.push(e);continue}let i=r.get(n);i===void 0?r.set(n,[e]):i.push(e)}let o=[...r.entries()].map(([e,t])=>({childContinuationToken:e,payload:{inputResponses:t}})),s={};for(let[t,n]of Object.entries(e.payload))t===`inputResponses`||n===void 0||(s[t]=n);return a.length>0&&(s.inputResponses=a),{forChildren:o,forSelf:Object.keys(s).length>0?s:void 0}}export{emitProxiedInputRequest,routeDeliverPayload};
+import{createInputRequestedEvent}from"#protocol/message.js";import{emitTurnEpilogue,getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";import{getProxyInputRequests,toProxyInputRequestEntries}from"#harness/proxy-input-requests.js";async function emitProxiedInputRequest(i){await i.emit(createInputRequestedEvent({requests:i.hookPayload.event.requests,sequence:i.hookPayload.event.sequence,stepIndex:i.hookPayload.event.stepIndex,turnId:i.hookPayload.event.turnId}));let o=i.session;if(i.mode===`conversation`){let e=getHarnessEmissionState(i.session.state),a=await emitTurnEpilogue(i.emit,e,i.mode);o=setHarnessEmissionState(i.session,a)}return{entries:toProxyInputRequestEntries(i.hookPayload),session:o}}function routeDeliverPayload(e){let t=getProxyInputRequests(e.state),n=e.payload.inputResponses??[],r=new Map,a=[];for(let e of n){let n=t.get(e.requestId);if(n===void 0){a.push(e);continue}let i=r.get(n);i===void 0?r.set(n,[e]):i.push(e)}let o=[...r.entries()].map(([e,t])=>({childContinuationToken:e,payload:{inputResponses:t}})),s={};for(let[t,n]of Object.entries(e.payload))t===`inputResponses`||n===void 0||(s[t]=n);return a.length>0&&(s.inputResponses=a),{forChildren:o,forSelf:Object.keys(s).length>0?s:void 0}}export{emitProxiedInputRequest,routeDeliverPayload};

package/dist/src/execution/subagent-tool.js

@@ -1 +1 @@
-import{formatSubagentInvocation}from"#execution/subagent-invocation.js";import{SUBAGENT_ADAPTER_KIND}from"#execution/subagent-adapter.js";import{mintSubagentContinuationToken}from"#execution/session.js";function buildSubagentRunInput(e){let{action:r,auth:i,batchEvent:a,capabilities:o,initiatorAuth:s,session:c}=e,l=mintSubagentContinuationToken(`${c.sessionId}:${r.callId}`);return{childContinuationToken:l,runInput:{adapter:{kind:SUBAGENT_ADAPTER_KIND,state:{callId:r.callId,parentContinuationToken:c.continuationToken,parentSessionId:c.sessionId,subagentName:r.subagentName}},auth:i,capabilities:o,continuationToken:l,initiatorAuth:s,input:{message:formatSubagentCallInputMessage(r)},mode:`task`,parent:{sessionId:c.sessionId,turn:{id:a.turnId,sequence:a.sequence}}}}}function formatSubagentCallInputMessage(t){let{message:n}=t.input;return formatSubagentInvocation({description:t.description,message:n,name:t.subagentName}).message}export{buildSubagentRunInput};
+import{mintSubagentContinuationToken}from"#execution/session.js";import{SUBAGENT_ADAPTER_KIND}from"#execution/subagent-adapter.js";import{formatSubagentInvocation}from"#execution/subagent-invocation.js";function buildSubagentRunInput(n){let{action:r,auth:i,batchEvent:a,capabilities:o,initiatorAuth:s,session:c}=n,l=mintSubagentContinuationToken(`${c.sessionId}:${r.callId}`);return{childContinuationToken:l,runInput:{adapter:{kind:SUBAGENT_ADAPTER_KIND,state:{callId:r.callId,parentContinuationToken:c.continuationToken,parentSessionId:c.sessionId,subagentName:r.subagentName}},auth:i,capabilities:o,continuationToken:l,initiatorAuth:s,input:{message:formatSubagentCallInputMessage(r)},mode:`task`,parent:{sessionId:c.sessionId,turn:{id:a.turnId,sequence:a.sequence}}}}}function formatSubagentCallInputMessage(e){let{message:t}=e.input;return formatSubagentInvocation({description:e.description,message:t,name:e.subagentName}).message}export{buildSubagentRunInput};

package/dist/src/execution/turn-workflow.d.ts

@@ -1,18 +1,20 @@
 import type { HookPayload, SessionCapabilities } from "#channel/types.js";
-import type { HarnessSession } from "#harness/types.js";
 import type { RunMode } from "#shared/run-mode.js";
-export interface TurnResultPayload {
-    readonly action: "done" | "park";
+import type { DurableSessionSnapshot, DurableSessionState } from "#execution/durable-session-store.js";
+import type { NextDriverAction } from "#execution/next-driver-action.js";
+/**
+ * Hook payload the turn child workflow delivers to the parent driver
+ * on completion. `turn-result` wraps a {@link NextDriverAction} the
+ * driver dispatches on; `turn-error` carries a normalized error the
+ * driver rethrows.
+ */
+export type TurnCompletionPayload = {
     readonly kind: "turn-result";
-    readonly output?: string;
-    readonly serializedContext: Record<string, unknown>;
-    readonly session: HarnessSession;
-}
-export interface TurnErrorPayload {
-    readonly error: unknown;
+    readonly action: NextDriverAction;
+} | {
     readonly kind: "turn-error";
-}
-export type TurnCompletionPayload = TurnResultPayload | TurnErrorPayload;
+    readonly error: unknown;
+};
 export interface TurnWorkflowInput {
     readonly capabilities: SessionCapabilities | undefined;
     readonly completionToken: string;
@@ -20,21 +22,19 @@ export interface TurnWorkflowInput {
     readonly mode: RunMode;
     readonly parentWritable: WritableStream<Uint8Array>;
     readonly serializedContext: Record<string, unknown>;
-    readonly session: HarnessSession;
+    readonly sessionState: DurableSessionState;
+    readonly sessionWritable: WritableStream<DurableSessionSnapshot>;
 }
 /**
- * Short-lived workflow that owns one runtime turn for the durable
- * driver.
+ * Short-lived workflow that owns one runtime turn for the driver.
  *
- * `parentWritable` is received from the driver input object and
- * threaded into every step so the child's writes land directly on the
- * driver run's stream.
+ * `parentWritable` and `sessionWritable` are threaded in from the
+ * driver run so step writes land on the driver's streams. Resolves the
+ * turn into a {@link NextDriverAction} and reports it back through
+ * {@link notifyDriverStep}.
  */
 export declare function turnWorkflow(input: TurnWorkflowInput): Promise<void>;
-/**
- * Completes a driver-owned one-shot hook with the result of the child
- * turn workflow.
- */
+/** Resumes the driver's one-shot completion hook with the turn result. */
 export declare function notifyDriverStep(input: {
     readonly completionToken: string;
     readonly payload: TurnCompletionPayload;

package/dist/src/execution/turn-workflow.js

@@ -1 +1 @@
-import{hasPendingInputBatch}from"#harness/input-requests.js";import{hasPendingRuntimeActionBatch}from"#harness/runtime-actions.js";import{awaitAuthorizationAndResolve}from"#execution/await-authorization-orchestrator.js";import{normalizeSerializableError}from"#execution/workflow-errors.js";import{turnStep}from"#execution/workflow-steps.js";async function turnWorkflow(r){"use workflow";let i=r.session,a=r.serializedContext,o=r.delivery,s=r.parentWritable;try{for(;;){let n=await turnStep({input:o,parentWritable:s,serializedContext:a,session:i});if(i=n.session,a=n.serializedContext,n.action===`done`){await notifyDriverStep({completionToken:r.completionToken,payload:{action:`done`,kind:`turn-result`,output:n.output??``,serializedContext:a,session:i}});return}if(n.action===`park`){if(hasPendingRuntimeActionBatch(i)||hasPendingInputBatch(i)&&r.capabilities?.requestInput===!0||r.mode===`conversation`){await notifyDriverStep({completionToken:r.completionToken,payload:{action:`park`,kind:`turn-result`,serializedContext:a,session:i}});return}throw Error("Task mode cannot wait for follow-up input (`next: null`).")}if(n.action===`await-authorization`){let e=await awaitAuthorizationAndResolve({parentWritable:s,pendingToolCalls:n.pendingToolCalls,serializedContext:a,session:i});i=e.session,a=e.serializedContext,o=void 0;continue}o=void 0}}catch(e){throw await notifyDriverStep({completionToken:r.completionToken,payload:{error:normalizeSerializableError(e),kind:`turn-error`}}),e}}async function notifyDriverStep(e){"use step";let{resumeHook:t}=await import(`#compiled/@workflow/core/runtime.js`);await t(e.completionToken,e.payload)}export{notifyDriverStep,turnWorkflow};
+import{awaitAuthorizationAndResolve}from"#execution/await-authorization-orchestrator.js";import{normalizeSerializableError}from"#execution/workflow-errors.js";import{turnStep}from"#execution/workflow-steps.js";async function turnWorkflow(r){"use workflow";let i=r.sessionState,a=r.serializedContext,o=r.delivery,s=r.parentWritable,c=r.sessionWritable;try{for(;;){let t=await turnStep({input:o,parentWritable:s,serializedContext:a,sessionState:i,sessionWritable:c});if(i=t.sessionState,a=t.serializedContext,t.action===`done`){await notifyDriverStep({completionToken:r.completionToken,payload:{action:{kind:`done`,output:t.output??``,serializedContext:a,sessionState:i},kind:`turn-result`}});return}if(t.action===`park`){let e=t.pendingRuntimeActionKeys;if(!(e!==void 0||t.hasPendingInputBatch&&r.capabilities?.requestInput===!0||r.mode===`conversation`))throw Error("Task mode cannot wait for follow-up input (`next: null`).");let n=e===void 0?{kind:`park`,serializedContext:a,sessionState:i}:{kind:`dispatch-runtime-actions`,pendingActionKeys:e,serializedContext:a,sessionState:i};await notifyDriverStep({completionToken:r.completionToken,payload:{action:n,kind:`turn-result`}});return}if(t.action===`await-authorization`){let n=await awaitAuthorizationAndResolve({parentWritable:s,pendingToolCalls:t.pendingToolCalls,serializedContext:a,sessionState:i,sessionWritable:c});i=n.sessionState,a=n.serializedContext,o=void 0;continue}o=void 0}}catch(e){throw await notifyDriverStep({completionToken:r.completionToken,payload:{error:normalizeSerializableError(e),kind:`turn-error`}}),e}}async function notifyDriverStep(e){"use step";let{resumeHook:t}=await import(`#compiled/@workflow/core/runtime.js`);await t(e.completionToken,e.payload)}export{notifyDriverStep,turnWorkflow};

package/dist/src/execution/workflow-entry.d.ts

@@ -1,30 +1,26 @@
 import type { RunInput } from "#channel/types.js";
 /**
- * Serializable input for the workflow entrypoint.
- *
- * All runtime state is carried inside `serializedContext`, which is produced
- * by `serializeContext(ctx)` in the workflow runtime and deserialized at
- * each `"use step"` boundary. The workflow body extracts values it needs
- * for plumbing (continuation token, mode, bundle source) directly from
- * the serialized record.
+ * Serializable workflow-entry input. All runtime state travels via
+ * `serializedContext`, which is produced by `serializeContext(ctx)`
+ * and deserialized at each `"use step"` boundary.
  */
 export interface WorkflowEntryInput {
     readonly input: RunInput["input"];
     readonly serializedContext: Record<string, unknown>;
 }
-/**
- * Value returned when the workflow terminates (harness signals done).
- */
 export interface WorkflowEntryResult {
     readonly output: string;
 }
 /**
- * Long-lived workflow entrypoint for the durable runtime.
+ * Long-lived workflow entrypoint. Handles both root sessions and
+ * delegated child sessions: root sessions expose only parent
+ * control-plane events; delegated children publish their full progress
+ * on a child stream and resume the parked parent with a
+ * `subagent-result` on completion.
  *
- * Root sessions and delegated child sessions both run through this entrypoint.
- * Root sessions expose only the parent control-plane events for subagent
- * delegation. Delegated children publish their full progress on their own
- * child stream and resume the parked parent with a `subagent-result` when the
- * child completes.
+ * Dispatches on the closed-contract {@link NextDriverAction} returned
+ * by each step. The only session-shape flag the driver reads (besides
+ * identity) is `hasProxyInputRequests`, the documented short-circuit
+ * for hook-payload routing.
  */
 export declare function workflowEntry(input: WorkflowEntryInput): Promise<WorkflowEntryResult>;

package/dist/src/execution/workflow-entry.js

@@ -1 +1 @@
-import{toErrorMessage}from"#shared/errors.js";import{ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{createHook,getWorkflowMetadata,getWritable}from"#compiled/@workflow/core/index.js";import{deserializeContext}from"#context/serialize.js";import{hasProxyInputRequests}from"#harness/proxy-input-requests.js";import{SUBAGENT_ADAPTER_KIND}from"#execution/subagent-adapter.js";import{accumulateRuntimeActionResults,hasPendingRuntimeActionBatch}from"#harness/runtime-actions.js";import{normalizeSerializableError,rebuildSerializableError}from"#execution/workflow-errors.js";import{createSessionStep,dispatchPendingRuntimeActionsStep,dispatchTurnStep,emitTerminalSessionFailureStep,routeProxiedDeliverStep,runProxyInputRequestStep}from"#execution/workflow-steps.js";import{coalesceDeliveries}from"#harness/messages.js";import{fireSessionCallbackStep}from"#execution/session-callback-step.js";async function workflowEntry(e){"use workflow";let{workflowRunId:t}=getWorkflowMetadata(),n=e.serializedContext[`ash.continuationToken`]||``,a=e.serializedContext[`ash.mode`],o=e.serializedContext[`ash.capabilities`],s=e.serializedContext[`ash.bundle`];e.serializedContext[`ash.sessionId`]=t;let c=getWritable();try{let r=await createSessionStep({compiledArtifactsSource:s.source,continuationToken:n,nodeId:s.nodeId,sessionId:t});return await runDriverLoop({capabilities:o,driverWritable:c,initialInput:{kind:`deliver`,payloads:[{message:e.input.message,modelContext:e.input.modelContext}]},mode:a,serializedContext:e.serializedContext,session:r})}catch(t){throw await emitTerminalSessionFailureStep({error:normalizeSerializableError(t),parentWritable:c,serializedContext:e.serializedContext}),await fireSessionCallbackStep({error:normalizeSerializableError(t),serializedContext:e.serializedContext,status:`failed`}),await notifyDelegatedParentStep({result:createDelegatedSubagentErrorResult(e.serializedContext,t),serializedContext:e.serializedContext}),t}}async function runDriverLoop(e){let t=e.session,i=e.serializedContext,a=0,o=await dispatchAndAwaitTurn({capabilities:e.capabilities,delivery:e.initialInput,mode:e.mode,parentWritable:e.driverWritable,serializedContext:i,session:t,turnGeneration:++a}),s=[];if(t=o.session,i=o.serializedContext,o.action===`done`)return await fireSessionCallbackStep({output:o.output??``,serializedContext:i,status:`completed`}),await notifyDelegatedParentStep({result:createDelegatedSubagentSuccessResult(i,o.output??``),serializedContext:i}),{output:o.output??``};if(!t.continuationToken)throw Error("Cannot park: no continuation token available. The channel must post the first message during the initial turn (anchoring the session) or `send()` must be called with an explicit continuationToken.");let c=t.continuationToken,l=createHook({token:c}),u=l[Symbol.asyncIterator](),d=null,getNextPromise=()=>(d??=u.next(),d),consumeNext=()=>{d=null},rekeyHook=async e=>{e===c||!e||(await closeHookIterator(u),await disposeHook(l),c=e,l=createHook({token:c}),u=l[Symbol.asyncIterator](),d=null)};try{for(;;){if(hasPendingRuntimeActionBatch(t)){let n=await dispatchPendingRuntimeActionsStep({callbackBaseUrl:getWorkflowMetadata().url.replace(/\/$/,``),parentWritable:e.driverWritable,serializedContext:i,session:t});t=n.session;let c=await waitForPendingRuntimeActionResults({bufferedDeliveries:s,getNextPromise,consumeNext,initialResults:n.results,rekeyHook,parentWritable:e.driverWritable,serializedContext:i,session:t});if(c===null)break;t=c.session,i=c.serializedContext,o=await dispatchAndAwaitTurn({capabilities:e.capabilities,delivery:{kind:`runtime-action-result`,results:c.results},mode:e.mode,parentWritable:e.driverWritable,serializedContext:i,session:t,turnGeneration:++a})}else{let n=await waitForNextDeliver({bufferedDeliveries:s,consumeNext,getNextPromise});if(n===null)break;let r=await routeDeliverForChildren({auth:n.auth,parentWritable:e.driverWritable,payloads:n.payloads,session:t});if(r===void 0)continue;o=await dispatchAndAwaitTurn({capabilities:e.capabilities,delivery:{auth:n.auth,kind:`deliver`,payloads:[r]},mode:e.mode,parentWritable:e.driverWritable,serializedContext:i,session:t,turnGeneration:++a})}if(t=o.session,i=o.serializedContext,o.action===`done`)return await fireSessionCallbackStep({output:o.output??``,serializedContext:i,status:`completed`}),await notifyDelegatedParentStep({result:createDelegatedSubagentSuccessResult(i,o.output??``),serializedContext:i}),{output:o.output??``};await rekeyHook(t.continuationToken)}}finally{await closeHookIterator(u),await disposeHook(l)}return{output:``}}async function dispatchAndAwaitTurn(e){let t=`ash://turn/${e.session.sessionId}/${e.turnGeneration}`,r=createHook({token:t});try{await dispatchTurnStep({capabilities:e.capabilities,completionToken:t,delivery:e.delivery,mode:e.mode,parentWritable:e.parentWritable,serializedContext:e.serializedContext,session:e.session});let n=await awaitHookPayload(r);if(n.kind===`turn-error`)throw rebuildSerializableError(n.error);return n}finally{await disposeHook(r)}}async function awaitHookPayload(e){for await(let t of e)return t;throw Error(`Turn completion hook closed before delivering a result.`)}async function waitForPendingRuntimeActionResults(e){let t=e.session,n=e.serializedContext,r=await accumulateRuntimeActionResults({bufferedDeliveries:e.bufferedDeliveries,async getNext(){for(;;){let r=await e.getNextPromise();if(e.consumeNext(),r.done)return null;let i=r.value;if(i.kind===`deliver`){let n=await routeDeliverForChildren({auth:i.auth,parentWritable:e.parentWritable,payloads:i.payloads,session:t});if(n===void 0)continue;return{kind:`deliver`,value:{...i,payloads:[n]}}}if(i.kind===`runtime-action-result`)return{kind:`runtime-action-result`,results:i.results};let a=await runProxyInputRequestStep({hookPayload:i,parentWritable:e.parentWritable,serializedContext:n,session:t});t=a.session,n=a.serializedContext,await e.rekeyHook(t.continuationToken)}},initialResults:e.initialResults,session:t});return r===null?null:{results:r,serializedContext:n,session:t}}async function routeDeliverForChildren(e){let t=coalescePayloads(e.payloads);return hasProxyInputRequests(e.session)?(await routeProxiedDeliverStep({auth:e.auth,parentWritable:e.parentWritable,payload:t,session:e.session})).remainder:t}async function waitForNextDeliver(e){if(e.bufferedDeliveries.length>0)return coalesceDeliveries(e.bufferedDeliveries.splice(0));for(;;){let t=await e.getNextPromise();if(e.consumeNext(),t.done)return null;if(t.value.kind!==`deliver`)continue;let n=t.value;for(;;){let t=await takeReadyPayload(e.getNextPromise());if(t===NO_READY_MESSAGE||(e.consumeNext(),t.done))break;t.value.kind===`deliver`&&(n=coalesceDeliveries([n,t.value]))}return n}}async function notifyDelegatedParentStep(e){"use step";if(e.result===void 0)return;let n=(await deserializeContext(e.serializedContext)).get(ChannelKey);if(n?.kind!==SUBAGENT_ADAPTER_KIND)return;let r=String(n.state?.parentContinuationToken??``);if(r===``)return;let{resumeHook:i}=await import(`#compiled/@workflow/core/runtime.js`);await i(r,{kind:`runtime-action-result`,results:[e.result]})}function createDelegatedSubagentSuccessResult(e,t){let n=e[`ash.channel`];if(n?.kind===SUBAGENT_ADAPTER_KIND)return{callId:String(n.state?.callId??``),kind:`subagent-result`,output:t,subagentName:String(n.state?.subagentName??``)}}function createDelegatedSubagentErrorResult(t,n){let r=createDelegatedSubagentSuccessResult(t,``);if(r!==void 0)return{...r,isError:!0,output:{code:`SUBAGENT_EXECUTION_FAILED`,message:toErrorMessage(n)}}}function coalescePayloads(e){if(e.length===0)return{};if(e.length===1)return e[0]??{};let t={},n=[];for(let r of e){for(let[e,n]of Object.entries(r))e!==`inputResponses`&&n!==void 0&&(t[e]=n);r.inputResponses!==void 0&&n.push(...r.inputResponses)}return n.length>0&&(t.inputResponses=n),t}const NO_READY_MESSAGE=Symbol(`no-ready-message`);async function takeReadyPayload(e){return await Promise.resolve(),await Promise.race([e,Promise.resolve(NO_READY_MESSAGE)])}async function closeHookIterator(e){typeof e.return==`function`&&await e.return(void 0)}async function disposeHook(e){let t=e.dispose;if(typeof t==`function`){await t.call(e);return}let n=e[Symbol.dispose];typeof n==`function`&&await n.call(e)}export{workflowEntry};
+import{createHook,getWorkflowMetadata,getWritable}from"#compiled/@workflow/core/index.js";import{ASH_SESSION_STREAM_NAMESPACE}from"#execution/durable-session-store.js";import{accumulateRuntimeActionResults}from"#harness/runtime-actions.js";import{normalizeSerializableError,rebuildSerializableError}from"#execution/workflow-errors.js";import{dispatchTurnStep,emitTerminalSessionFailureStep,routeProxiedDeliverStep,runProxyInputRequestStep}from"#execution/workflow-steps.js";import{coalesceDeliveries}from"#harness/messages.js";import{notifyDelegatedParentStep}from"#execution/delegated-parent-notification.js";import{createDelegatedSubagentErrorResult,createDelegatedSubagentSuccessResult}from"#execution/delegated-parent-result.js";import{createSessionStep}from"#execution/create-session-step.js";import{dispatchRuntimeActionsStep}from"#execution/dispatch-runtime-actions-step.js";import{fireSessionCallbackStep}from"#execution/session-callback-step.js";async function workflowEntry(e){"use workflow";let{workflowRunId:i}=getWorkflowMetadata(),o=e.serializedContext[`ash.continuationToken`]||``,s=e.serializedContext[`ash.mode`],l=e.serializedContext[`ash.capabilities`],u=e.serializedContext[`ash.bundle`];e.serializedContext[`ash.sessionId`]=i;let d=getWritable(),f=getWritable({namespace:ASH_SESSION_STREAM_NAMESPACE});try{let t=await createSessionStep({compiledArtifactsSource:u.source,continuationToken:o,nodeId:u.nodeId,sessionId:i,sessionWritable:f});return await runDriverLoop({capabilities:l,driverWritable:d,initialInput:{kind:`deliver`,payloads:[{message:e.input.message,modelContext:e.input.modelContext}]},mode:s,serializedContext:e.serializedContext,sessionState:t,sessionWritable:f})}catch(t){throw await emitTerminalSessionFailureStep({error:normalizeSerializableError(t),parentWritable:d,serializedContext:e.serializedContext}),await fireSessionCallbackStep({error:normalizeSerializableError(t),serializedContext:e.serializedContext,status:`failed`}),await notifyDelegatedParentStep({result:createDelegatedSubagentErrorResult(e.serializedContext,t),serializedContext:e.serializedContext}),t}}async function runDriverLoop(n){let r=0,i=await dispatchAndAwaitTurn({capabilities:n.capabilities,delivery:n.initialInput,mode:n.mode,parentWritable:n.driverWritable,serializedContext:n.serializedContext,sessionState:n.sessionState,sessionWritable:n.sessionWritable,turnGeneration:++r});if(i.kind===`done`)return await finalizeDone({action:i,driverWritable:n.driverWritable});if(!i.sessionState.continuationToken)throw Error("Cannot park: no continuation token available. The channel must post the first message during the initial turn (anchoring the session) or `send()` must be called with an explicit continuationToken.");let a=i.sessionState.continuationToken,o=createHook({token:a}),s=o[Symbol.asyncIterator](),c=null,l=[],getNextPromise=()=>(c??=s.next(),c),consumeNext=()=>{c=null},rekeyHook=async t=>{t===a||!t||(await closeHookIterator(s),await disposeHook(o),a=t,o=createHook({token:a}),s=o[Symbol.asyncIterator](),c=null)};try{for(;;)switch(i.kind){case`done`:return await finalizeDone({action:i,driverWritable:n.driverWritable});case`dispatch-runtime-actions`:{let e=await dispatchRuntimeActionsStep({callbackBaseUrl:getWorkflowMetadata().url.replace(/\/$/,``),parentWritable:n.driverWritable,serializedContext:i.serializedContext,sessionState:i.sessionState,sessionWritable:n.sessionWritable}),a=await waitForPendingRuntimeActionResults({bufferedDeliveries:l,consumeNext,getNextPromise,initialResults:e.results,parentWritable:n.driverWritable,pendingActionKeys:i.pendingActionKeys,rekeyHook,serializedContext:i.serializedContext,sessionState:e.sessionState,sessionWritable:n.sessionWritable});if(a===null)return{output:``};i=await dispatchAndAwaitTurn({capabilities:n.capabilities,delivery:{kind:`runtime-action-result`,results:a.results},mode:n.mode,parentWritable:n.driverWritable,serializedContext:a.serializedContext,sessionState:a.sessionState,sessionWritable:n.sessionWritable,turnGeneration:++r}),await rekeyHook(i.sessionState.continuationToken);break}case`park`:{let e=await waitForNextDeliver({bufferedDeliveries:l,consumeNext,getNextPromise});if(e===null)return{output:``};let t=await routeDeliverForChildren({auth:e.auth,parentWritable:n.driverWritable,payloads:e.payloads,sessionState:i.sessionState});if(t===void 0)continue;i=await dispatchAndAwaitTurn({capabilities:n.capabilities,delivery:{auth:e.auth,kind:`deliver`,payloads:[t]},mode:n.mode,parentWritable:n.driverWritable,serializedContext:i.serializedContext,sessionState:i.sessionState,sessionWritable:n.sessionWritable,turnGeneration:++r}),await rekeyHook(i.sessionState.continuationToken);break}}}finally{await closeHookIterator(s),await disposeHook(o)}}async function finalizeDone(e){return await fireSessionCallbackStep({output:e.action.output,serializedContext:e.action.serializedContext,status:`completed`}),await notifyDelegatedParentStep({result:createDelegatedSubagentSuccessResult(e.action.serializedContext,e.action.output),serializedContext:e.action.serializedContext}),{output:e.action.output}}async function dispatchAndAwaitTurn(t){let n=`ash://turn/${t.sessionState.sessionId}/${t.turnGeneration}`,r=createHook({token:n});try{await dispatchTurnStep({capabilities:t.capabilities,completionToken:n,delivery:t.delivery,mode:t.mode,parentWritable:t.parentWritable,serializedContext:t.serializedContext,sessionState:t.sessionState,sessionWritable:t.sessionWritable});let e=await awaitHookPayload(r);if(e.kind===`turn-error`)throw rebuildSerializableError(e.error);return e.action}finally{await disposeHook(r)}}async function awaitHookPayload(e){for await(let t of e)return t;throw Error(`Turn completion hook closed before delivering a result.`)}async function waitForPendingRuntimeActionResults(e){let t=e.sessionState,n=e.serializedContext,r=await accumulateRuntimeActionResults({bufferedDeliveries:e.bufferedDeliveries,async getNext(){for(;;){let r=await e.getNextPromise();if(e.consumeNext(),r.done)return null;let i=r.value;if(i.kind===`deliver`){let n=await routeDeliverForChildren({auth:i.auth,parentWritable:e.parentWritable,payloads:i.payloads,sessionState:t});if(n===void 0)continue;return{kind:`deliver`,value:{...i,payloads:[n]}}}if(i.kind===`runtime-action-result`)return{kind:`runtime-action-result`,results:i.results};let a=await runProxyInputRequestStep({hookPayload:i,parentWritable:e.parentWritable,serializedContext:n,sessionState:t,sessionWritable:e.sessionWritable});t=a.sessionState,n=a.serializedContext,await e.rekeyHook(t.continuationToken)}},initialResults:e.initialResults,pendingActionKeys:e.pendingActionKeys});return r===null?null:{results:r,serializedContext:n,sessionState:t}}async function routeDeliverForChildren(e){let t=coalescePayloads(e.payloads);return e.sessionState.hasProxyInputRequests?(await routeProxiedDeliverStep({auth:e.auth,parentWritable:e.parentWritable,payload:t,sessionState:e.sessionState})).remainder:t}async function waitForNextDeliver(e){if(e.bufferedDeliveries.length>0)return coalesceDeliveries(e.bufferedDeliveries.splice(0));for(;;){let t=await e.getNextPromise();if(e.consumeNext(),t.done)return null;if(t.value.kind!==`deliver`)continue;let n=t.value;for(;;){let t=await takeReadyPayload(e.getNextPromise());if(t===NO_READY_MESSAGE||(e.consumeNext(),t.done))break;t.value.kind===`deliver`&&(n=coalesceDeliveries([n,t.value]))}return n}}function coalescePayloads(e){if(e.length===0)return{};if(e.length===1)return e[0]??{};let t={},n=[];for(let r of e){for(let[e,n]of Object.entries(r))e!==`inputResponses`&&n!==void 0&&(t[e]=n);r.inputResponses!==void 0&&n.push(...r.inputResponses)}return n.length>0&&(t.inputResponses=n),t}const NO_READY_MESSAGE=Symbol(`no-ready-message`);async function takeReadyPayload(e){return await Promise.resolve(),await Promise.race([e,Promise.resolve(NO_READY_MESSAGE)])}async function closeHookIterator(e){typeof e.return==`function`&&await e.return(void 0)}async function disposeHook(e){let t=e.dispose;if(typeof t==`function`){await t.call(e);return}let n=e[Symbol.dispose];typeof n==`function`&&await n.call(e)}export{workflowEntry};