@relayflows/sdk 2.0.35 → 2.0.37

package/src/authored-flow-executor.ts

@@ -43,6 +43,7 @@ import type { LoadedAuthoredFlowNode } from './authored-flow-loader.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import {
   AuthoredFlowExecutionError,
+  type AuthoredFlowSuspension,
   AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
@@ -54,6 +55,7 @@ import {
   verifyAuthoredOperations,
 } from './authored-flow-operation.js';
 import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
+import { AuthoredActivities } from './authored-activity.js';
 import { displayLabel, type AuthoredStepEdges } from './authored-step-index.js';
 import { JournalClient } from './journal-client.js';
 import { PluginError } from './plugin-manifest.js';
@@ -105,6 +107,7 @@ export interface AuthoredExecutionRuntime {
 }
 
 export interface AuthoredFlowExecutionResult {
+  readonly state?: undefined;
   readonly executionRuntime?: AuthoredExecutionRuntime;
   readonly rootRunId?: string;
   readonly name: string;
@@ -118,6 +121,14 @@ export interface AuthoredFlowExecutionResult {
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
 }
 
+/** A body reached a durable event boundary and released its worker lease. */
+export interface AuthoredFlowSuspendedResult {
+  readonly state: 'suspended';
+  readonly name: string;
+  readonly suspension: AuthoredFlowSuspension;
+  readonly journalSteps: readonly AuthoredFlowJournalStep[];
+}
+
 // The authoring SURFACE stays wide: `done()` accepts every
 // `FlowCompletionReason` and refuses the kernel-owned ones at runtime with a
 // diagnostic that names the alternative. The RESULT is narrow, because `done()`
@@ -174,6 +185,8 @@ export interface ExecuteAuthoredFlowOptions {
   readonly onWait?: RunLifecycleOptions['onWait'];
   readonly onProgress?: (event: ProgressEvent) => void;
   readonly localAgentStream?: string;
+  /** Environment reserved for provider probes and local agent subprocesses. */
+  readonly agentEnvironment?: NodeJS.ProcessEnv;
   /**
    * How many agent (and, separately, LLM) dispatches the attached local
    * workers hold at once. Set, it caps this body's concurrent `f.agent` /
@@ -273,6 +286,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   const journalSteps: AuthoredFlowJournalStep[] = [];
   const authoredSteps: AuthoredFlowOperation<unknown>[] = [];
   const lifecycle = new AuthoredFlowLifecycle();
+  const activities = new AuthoredActivities(journal, options.rootRunId);
   const edgeOverrides = new Map<string, AuthoredStepEdges>();
   const stepEdges = (step: string): AuthoredStepEdges | undefined => {
     const overridden = edgeOverrides.get(step);
@@ -300,6 +314,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     definition.name, journal, journalSteps, budget, {
       ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
       ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
       stepEdges,
     },
   );
@@ -307,7 +322,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   const worker = authoredWorkerRunner(
     definition, journal, flowPath, journalSteps, waitOptions,
     localAgentStream, budget, definition.header.budget, options.rootRunId, options.workerCapacity, stepEdges,
-    options.workerSlots,
+    options.workerSlots, options.agentEnvironment,
   );
 
   /**
@@ -567,6 +582,17 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, agentOp);
     },
+    on(source, activityOptions) {
+      assertOperationAllowed('on', definition.name, requestedCompletion);
+      // Activity ids are root-scoped (`activity-N`); a child's own counter would collide.
+      if ((options.dispatchDepth ?? 0) > 0) {
+        throw new AuthoredFlowExecutionError(
+          'dispatch_invalid',
+          `child flow "${definition.name}" cannot call f.on in this release; activities are root-scoped`,
+        );
+      }
+      return activities.open(source, activityOptions);
+    },
     /**
      * `f.human` (docs/SURFACE.md §1, §7). The question is not a child run: it
      * is the ROOT attempt parking on the kernel's `wait.human`. The body
@@ -661,6 +687,7 @@ export async function executeAuthoredFlow<Input = undefined>(
             dataDir: options.dataDir,
             flowPath: child.path,
             ...(localAgentStream === undefined ? {} : { localAgentStream }),
+            ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
             ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
             ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
             flowGraph: options.flowGraph,
@@ -794,6 +821,11 @@ export async function executeAuthoredFlow<Input = undefined>(
     try {
       worker.stop(bodyFailure);
       await stopAuthoredOperations(authoredSteps, bodyFailure);
+      // A durable wait hands execution back to the control plane. Its
+      // subscriptions must keep receiving events while no body is running.
+      const parked = bodyFailure instanceof AuthoredFlowExecutionError
+        && (bodyFailure.code === 'subscription_suspended' || bodyFailure.code === 'human_parked');
+      if (!parked) await activities.closeAll('canceled');
     } finally {
       lifecycle.close();
     }
@@ -821,6 +853,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     try {
       worker.stop(missingCompletion);
       await stopAuthoredOperations(authoredSteps, missingCompletion);
+      await activities.closeAll('canceled');
     } finally {
       lifecycle.close();
     }
@@ -828,6 +861,16 @@ export async function executeAuthoredFlow<Input = undefined>(
   }
   try {
     await verifyAuthoredOperations(definition.name, authoredSteps, lifecycle);
+  } catch (error) {
+    try {
+      await activities.closeAll('canceled');
+    } finally {
+      lifecycle.close();
+    }
+    throw error;
+  }
+  try {
+    await activities.closeAll('run_completed');
   } finally {
     lifecycle.close();
   }

package/src/authored-helper-effect.ts

@@ -14,6 +14,7 @@ import { helperWriteback, HelperDeliveryError } from './helper-writeback.js';
 import { checkSlackHelpers } from './slack-preflight.js';
 import { atomicJson, readSlackReceipt, receiptPath, slackWriteback, type SlackCall } from './slack-writeback.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
+import { NO_MODEL_COST } from './reported-cost.js';
 
 type ProviderCall = HelperCall | SlackCall;
 
@@ -135,11 +136,11 @@ async function completeHelperDispatch(client: JournalClient, dispatch: StepDispa
     await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
       dispatch.idempotency_key, 'worker_error', {
         output: { ...call, diagnostic: error.message },
-        started_pins: dispatch.pins, end_pins: dispatch.pins, effects: [],
+        started_pins: dispatch.pins, end_pins: dispatch.pins, effects: [], reported_cost: NO_MODEL_COST,
       });
     return;
   }
   await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
-    dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins,
+    dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins, reported_cost: NO_MODEL_COST,
       effects: [{ surface_path: `/${call.provider}`, idempotency_key: dispatch.idempotency_key }] });
 }

package/src/authored-mcp.ts

@@ -12,6 +12,7 @@ import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { readCompletedStepOutput } from './authored-step-output.js';
 import { withWorkerLease } from './worker-lease.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
+import { NO_MODEL_COST } from './reported-cost.js';
 
 /** Own keys expose precisely the preflight inventory, including prototype-like names. */
 export function buildMcpProxy(
@@ -116,6 +117,7 @@ export async function runMcpEffect(
         output: { ...receipt, output: output ?? null, ...(diagnostic ? { diagnostic } : {}) },
         started_pins: event.pins, end_pins: event.pins,
         ...(diagnostic ? { trajectory_tail: { ...receipt, diagnostic } } : {}),
+        reported_cost: NO_MODEL_COST,
         effects: confirmed ? [{ surface_path: surfacePath, idempotency_key: event.idempotency_key }] : [],
       });
   }
@@ -140,13 +142,13 @@ export async function runMcpEffect(
     childRunId = outcome.run_id;
     if (outcome.status !== 'completed') await completed;
     if (diagnostic !== undefined) {
-      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
       catch (error) {
         if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
         throw new McpStepError(diagnostic, outcome.run_id);
       }
     }
-    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
     return receipt.output;
   } finally {
     clearTimeout(timer);

package/src/authored-node-entry.ts

@@ -8,6 +8,7 @@ import { assertAuthoredNodeVersion, parseAuthoredParentPid } from './authored-ru
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import { isAgentCapacity } from './worker-slots.js';
 import type { AuthoredRootMetadata } from './authored-root.js';
+import { validatedLocalAgentEnvironment } from './local-agent-environment.js';
 
 let channelKey: string | undefined, sequence = 0;
 // Capture writers before loading authored modules; credentials never enter env.
@@ -49,7 +50,8 @@ try {
   send({ type: 'ready', runtime: { kind: 'node', version: process.versions.node,
     executableSha256: hash(process.execPath), payloadSha256: hash(process.argv[1]!) } });
   const request = await new Promise<{ channelKey: string; metadata: AuthoredRootMetadata; socketPath: string;
-    rootRunId: string; dataDir: string; localAgentStream?: string; workerCapacity?: number }>((resolve, reject) => {
+    rootRunId: string; dataDir: string; localAgentStream?: string; workerCapacity?: number;
+    agentEnvironment?: unknown }>((resolve, reject) => {
     let buffer = '';
     process.stdin.setEncoding('utf8');
     const onData = (chunk: string): void => {
@@ -65,6 +67,10 @@ try {
   if (typeof request.channelKey !== 'string' || !/^[a-f0-9]{64}$/.test(request.channelKey)) throw new Error('invalid authored channel key');
   channelKey = request.channelKey;
   controller.signal.throwIfAborted();
+  // Validate the parent handoff before evaluating any authored module. Only
+  // provider credentials may cross this channel; controls such as PATH and
+  // NODE_OPTIONS remain the child's inherited values.
+  const agentEnvironment = validatedLocalAgentEnvironment(request.agentEnvironment);
   const loaded = await loadPinnedAuthoredSource(request.metadata, true);
   if (request.localAgentStream !== request.metadata.localAgentStream) throw new Error('authored root local agent surface mismatch');
   if (request.workerCapacity !== undefined && !isAgentCapacity(request.workerCapacity)) throw new Error('invalid authored worker capacity');
@@ -78,6 +84,7 @@ try {
       flowGraph: loaded.graph,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       ...(request.workerCapacity === undefined ? {} : { workerCapacity: request.workerCapacity }),
+      ...(agentEnvironment === undefined ? {} : { agentEnvironment: { ...process.env, ...agentEnvironment } }),
       onProgress: event => send({ type: 'progress', event }),
       onWait: event => send({ type: 'wait', event }),
     });
@@ -94,7 +101,9 @@ try {
     // the only one that saw the child's classification.
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
       completionReason: error.completionReason, runId: error.runId,
-      details: error.details, parkCause: error.parkCause } : {}),
+      details: error.details,
+      parkCause: error.parkCause,
+      ...(error.suspension === undefined ? {} : { suspension: error.suspension }) } : {}),
     ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {

package/src/authored-node-runner.ts

@@ -18,6 +18,7 @@ import type {
 } from './failure-kinds.js';
 import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
+import { settlingCompletion } from './step-settling.js';
 
 let embeddedSource: string | undefined;
 /** Installed by the standalone build; never fetched or resolved from a workspace. */
@@ -133,7 +134,8 @@ export async function runAuthoredInNode(
               // Keep stdin open: EOF tells the child its lease-owning parent died.
               child.stdin!.write(JSON.stringify({ channelKey, metadata, socketPath, rootRunId,
                 dataDir: options.dataDir, localAgentStream: options.localAgentStream,
-                workerCapacity: options.workerCapacity }) + '\n');
+                workerCapacity: options.workerCapacity,
+                agentEnvironment: options.agentEnvironment }) + '\n');
             } else if (!ready || result) throw new Error('unexpected authored runtime message');
             else if (message.type === 'progress') options.onProgress?.(message.event);
             else if (message.type === 'wait') options.onWait?.(message.event);
@@ -144,7 +146,8 @@ export async function runAuthoredInNode(
               } else if (typeof message.code === 'string') {
                 const authored = new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
                   message.message, message.completionReason, message.runId,
-                  stepFailedFrame(message.details));
+                  stepFailedFrame(message.details),
+                  isSuspension(message.suspension) ? message.suspension : undefined);
                 // Validated, not trusted, like `details`: an unrecognised cause
                 // is dropped so the boundary says nothing about workers rather
                 // than acting on a value this frame could have invented.
@@ -172,6 +175,35 @@ export async function runAuthoredInNode(
   } finally { await rm(directory, { recursive: true, force: true }); }
 }
 
+function isSuspension(value: unknown): value is import('./authored-flow-error.js').AuthoredFlowSuspension {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const common = typeof record['subscriptionId'] === 'string' && record['subscriptionId'].length > 0
+    && typeof record['stream'] === 'string' && record['stream'].length > 0
+    && Number.isSafeInteger(record['deadlineAtMs']) && (record['deadlineAtMs'] as number) >= 0;
+  if (!common) return false;
+  if (record['kind'] === 'event_wait') return true;
+  return record['kind'] === 'activation'
+    && Array.isArray(record['eventTypes']) && record['eventTypes'].length > 0
+    && record['eventTypes'].every(type => typeof type === 'string' && type.length > 0)
+    && (record['pattern'] === undefined || isJsonRecord(record['pattern']))
+    && Number.isSafeInteger(record['settleMs']) && (record['settleMs'] as number) >= 0
+    && Number.isSafeInteger(record['idleMs']) && (record['idleMs'] as number) > 0
+    && typeof record['includeSelf'] === 'boolean';
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && Object.values(value).every(isJsonValue);
+}
+
+function isJsonValue(value: unknown): boolean {
+  return value === null || typeof value === 'boolean' || typeof value === 'string'
+    || (typeof value === 'number' && Number.isFinite(value))
+    || (Array.isArray(value) && value.every(isJsonValue))
+    || isJsonRecord(value);
+}
+
 /** A park signal from the child names the question the parent must journal. */
 function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
   const wait = value as Partial<AuthoredHumanWait> | null;
@@ -342,15 +374,17 @@ export async function verifyAuthoredNodeResult(
       // step a child spec may carry, and it must have completed too.
       const lowered = spec?.steps ?? [];
       const specShape = lowered.length === 1 || (lowered.length === 2 && lowered[1]?.id === `${claimed.id}.gate`);
-      const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
-      const gateCompleted = lowered.length === 2
-        ? entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === `${claimed.id}.gate`) : [];
+      // Judged against the step's SETTLING completion, the same one the
+      // authored reader returned: a retried attempt (`disposition: retry`,
+      // e.g. crash recovery's `crashed`) journals a completion of its own
+      // ahead of it, so neither a count nor the first entry is the verdict.
+      const completed = settlingCompletion(entries, claimed.id);
+      const gateCompleted = lowered.length === 2 ? settlingCompletion(entries, `${claimed.id}.gate`) : undefined;
       const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
       if (spec?.name !== `${metadata.flowName}/${claimed.id}` || !specShape
-        || step?.id !== claimed.id || completed.length !== 1
-        || completed[0]?.payload?.completionReason !== 'success'
-        || (lowered.length === 2 && (gateCompleted.length !== 1 || gateCompleted[0]?.payload?.completionReason !== 'success'))
-        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed.length}`);
+        || step?.id !== claimed.id || completed?.payload?.completionReason !== 'success'
+        || (lowered.length === 2 && gateCompleted?.payload?.completionReason !== 'success')
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed?.payload?.completionReason}`);
       if (claimed === terminal) {
         // The claimed verdict must match the marker the journal actually
         // recorded, so an IPC frame cannot claim `success` over a run whose

package/src/authored-plugin-effect.ts

@@ -11,6 +11,7 @@ import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { readCompletedStepOutput } from './authored-step-output.js';
 import { withWorkerLease } from './worker-lease.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
+import { NO_MODEL_COST } from './reported-cost.js';
 
 export class PluginStepError extends AuthoredFlowExecutionError {
   constructor(readonly diagnostic: string, runId: string) {
@@ -88,6 +89,7 @@ export async function runPluginEffect(
         output: { ...receipt, output: output ?? null, ...(diagnostic ? { diagnostic } : {}) },
         started_pins: event.pins, end_pins: event.pins,
         ...(diagnostic ? { trajectory_tail: { ...receipt, diagnostic } } : {}),
+        reported_cost: NO_MODEL_COST,
         effects: confirmed ? [{ surface_path: surfacePath, idempotency_key: event.idempotency_key }] : [],
       });
   }
@@ -125,13 +127,13 @@ export async function runPluginEffect(
       if (dispatchExpired) await cancelChildRun();
       if (outcome.status !== 'completed') await completed;
       if (diagnostic !== undefined) {
-        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
         catch (error) {
           if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
           throw new PluginStepError(diagnostic, outcome.run_id);
         }
       }
-      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
       return receipt.output;
     }, admissionKey), deadline]);
   } finally {

package/src/authored-preflight.ts

@@ -6,7 +6,7 @@ import { cliProbeKey, CliProbeError, resolvePreflight, type CliProbeOutcome } fr
 import type { FlowSpec } from './spec.js';
 
 /** Auth/model facts belong to one execution, including concurrent cold callers. */
-export function authoredPreflight(path: string) {
+export function authoredPreflight(path: string, environment?: NodeJS.ProcessEnv) {
   const probeCache = new Map<string, CliProbeOutcome>();
   const pending = new Map<string, Promise<void>>();
   const directory = dirname(resolve(path));
@@ -30,7 +30,7 @@ export function authoredPreflight(path: string) {
           try {
             probeCache.set(key, { result: await probeCliAsync(resolution.cli,
               resolution.source === 'project' ? config.directory : directory,
-              resolution.model, managed ? 'managed' : undefined) });
+              resolution.model, managed ? 'managed' : undefined, environment) });
           } catch (error) {
             probeCache.set(key, { failure: error instanceof CliProbeError ? error.detail : null });
           }

package/src/authored-root.ts

@@ -4,7 +4,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
-import { executeAuthoredFlow, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import { executeAuthoredFlow, type AuthoredFlowExecutionResult, type AuthoredFlowSuspendedResult } from './authored-flow-executor.js';
 import { isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
 import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
@@ -20,6 +20,12 @@ import { withWorkerLease } from './worker-lease.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
+import { readSubscriptionPark } from './authored-subscription-park.js';
+import { localAgentCredentialEnvironment } from './local-agent-environment.js';
+
+export type DurableAuthoredFlowResult =
+  | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
+  | (AuthoredFlowSuspendedResult & { readonly rootRunId: string });
 
 /**
  * Taken from the projection module rather than spelled twice: `flows status`
@@ -55,11 +61,15 @@ export interface AuthoredRootSourceAuthority {
 }
 
 export interface DurableAuthoredOptions {
+  /** Preserve root authority even if a child later fails or parks. */
+  readonly onAdmitted?: (runId: string) => void;
   readonly dataDir: string;
   readonly admissionKey?: string;
   readonly localAgentStream?: string;
   /** Concurrency of the attached local workers; see `ExecuteAuthoredFlowOptions.workerCapacity`. */
   readonly workerCapacity?: number;
+  /** Provider-only environment consumed by preflight and local workers. */
+  readonly agentEnvironment?: NodeJS.ProcessEnv;
   readonly lifecycle?: RunLifecycleOptions;
 }
 
@@ -69,7 +79,7 @@ export async function executeDurableAuthoredFlow(
   journal: JournalClient,
   input: unknown,
   options: DurableAuthoredOptions,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+): Promise<DurableAuthoredFlowResult> {
   assertAuthoredRuntimeAvailable();
   const source = await readFile(loaded.sourcePath);
   const sources = await Promise.all(loaded.graph.map(async node => Object.freeze({
@@ -106,6 +116,7 @@ export async function executeDurableAuthoredFlow(
       workspace: [], streams: [{ stream, read_offset: 0 }],
     });
     const outcome = await journal.runStart(spec, undefined, admissionKey);
+    options.onAdmitted?.(outcome.run_id);
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
       return await completedRootResult(journal, outcome.run_id);
@@ -119,6 +130,9 @@ export async function executeDurableAuthoredFlow(
     // redelivers only when the former worker connection is gone.
     const resumed = await journal.runResume(outcome.run_id);
     await assertNoOpenHumanWait(journal, resumed);
+    const parked = await readSubscriptionPark(journal, outcome.run_id);
+    if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
+      suspension: parked, journalSteps: [], rootRunId: outcome.run_id };
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -132,7 +146,7 @@ export async function resumeDurableAuthoredFlow(
   rootRunId: string,
   journal: JournalClient,
   options: Omit<DurableAuthoredOptions, 'admissionKey'>,
-): Promise<(AuthoredFlowExecutionResult & { readonly rootRunId: string }) | undefined> {
+): Promise<DurableAuthoredFlowResult | undefined> {
   const metadata = await readAuthoredRootMetadata(journal, rootRunId);
   if (metadata === undefined) return undefined;
   assertAuthoredRuntimeAvailable();
@@ -159,6 +173,9 @@ export async function resumeDurableAuthoredFlow(
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
     options.lifecycle?.onRunStarted?.({ runId: rootRunId, flow: metadata.flowName, resumed: true });
+    const parked = await readSubscriptionPark(journal, rootRunId);
+    if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
+      suspension: parked, journalSteps: [], rootRunId };
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -204,7 +221,7 @@ async function driveRoot(
   peer: JournalClient,
   dispatch: StepDispatchEvent,
   options: Omit<DurableAuthoredOptions, 'admissionKey'>,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+): Promise<DurableAuthoredFlowResult> {
   try {
     const result = await withWorkerLease(peer, dispatch, async rootSignal => {
       const callerSignal = options.lifecycle?.signal;
@@ -212,6 +229,9 @@ async function driveRoot(
       if (process.versions['bun'] !== undefined) {
         return runAuthoredInNode(metadata, journal.socketPath, dispatch.run_id, {
           dataDir: options.dataDir, localAgentStream: options.localAgentStream,
+          ...(options.agentEnvironment === undefined ? {} : {
+            agentEnvironment: localAgentCredentialEnvironment(options.agentEnvironment),
+          }),
           ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
           ...options.lifecycle, signal,
         });
@@ -225,6 +245,7 @@ async function driveRoot(
           dataDir: options.dataDir,
           flowPath: metadata.flowPath,
           localAgentStream: options.localAgentStream,
+          ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
           ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
           rootRunId: dispatch.run_id,
           extensions: loaded.extensions,
@@ -248,6 +269,15 @@ async function driveRoot(
     );
     return Object.freeze({ ...result, rootRunId: dispatch.run_id });
   } catch (error) {
+    if (error instanceof AuthoredFlowExecutionError
+      && error.code === 'subscription_suspended'
+      && error.suspension !== undefined) {
+      await peer.subscriptionPark({ run_id: dispatch.run_id, step_id: dispatch.step_id,
+        attempt: dispatch.attempt, idempotency_key: dispatch.idempotency_key,
+        subscription_id: error.suspension.subscriptionId, phase: error.suspension.kind });
+      return Object.freeze({ state: 'suspended' as const, name: metadata.flowName,
+        suspension: error.suspension, journalSteps: Object.freeze([]), rootRunId: dispatch.run_id });
+    }
     if (error instanceof AuthoredHumanParked) {
       // Not a failure: the body reached a question nobody has answered. Park
       // THIS attempt on the kernel's `wait.human` under the body's own wait