@relayflows/sdk 2.0.34 → 2.0.36

package/dist/authored-dispatch.js

@@ -0,0 +1,81 @@
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { flowRequirements } from './flow-requirements.js';
+export const MAX_DISPATCH_DEPTH = 3;
+/** Resolve one attenuated direct child from the statically loaded `use` graph. */
+export function resolveDispatchChild(options) {
+    if (typeof options.flowName !== 'string' || options.flowName.trim() === '') {
+        throw new AuthoredFlowExecutionError('dispatch_invalid', 'f.dispatch requires a non-empty declared child flow name');
+    }
+    if (options.depth >= MAX_DISPATCH_DEPTH) {
+        throw new AuthoredFlowExecutionError('dispatch_depth_exceeded', `f.dispatch depth exceeds ${MAX_DISPATCH_DEPTH}; flatten the flow tree or move work into the current child`);
+    }
+    const current = options.graph?.find(node => node.handle === options.handle);
+    const direct = current?.use.map(path => options.graph.find(node => node.path === path)) ?? [];
+    const matches = direct.filter((node) => node !== undefined && node.getDefinition(node.handle).name === options.flowName);
+    if (matches.length !== 1) {
+        const declared = direct.filter((node) => node !== undefined)
+            .map(node => node.getDefinition(node.handle).name).sort();
+        throw new AuthoredFlowExecutionError(matches.length > 1 ? 'dispatch_invalid' : 'dispatch_unknown', `flow "${options.definition.name}" cannot dispatch ${JSON.stringify(options.flowName)}; direct use children: ${declared.length === 0 ? '(none)' : declared.join(', ')}`);
+    }
+    const child = matches[0];
+    const childDefinition = child.getDefinition(child.handle);
+    assertChildCapabilities(options.definition, childDefinition);
+    if (childDefinition.header.budget !== undefined) {
+        throw new AuthoredFlowExecutionError('dispatch_invalid', `child flow "${childDefinition.name}" declares its own budget; put the run-tree ceiling on "${options.definition.name}" until nested budget intersection ships`);
+    }
+    return child;
+}
+export function parseDispatchReceipt(value, step) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new AuthoredFlowExecutionError('journal_protocol_violation', `dispatch step "${step}" recorded invalid JSON`);
+    }
+    const receipt = parsed;
+    if (typeof receipt !== 'object' || receipt === null || typeof receipt.name !== 'string'
+        || receipt.completionReason !== 'success'
+        || (receipt.completionDetail !== undefined && typeof receipt.completionDetail !== 'string')) {
+        throw new AuthoredFlowExecutionError('journal_protocol_violation', `dispatch step "${step}" recorded an invalid child receipt`);
+    }
+    return {
+        name: receipt.name,
+        completionReason: 'success',
+        ...(receipt.completionDetail === undefined ? {} : { completionDetail: receipt.completionDetail }),
+    };
+}
+/** Last visible child operations; the dispatch receipt joins all of them. */
+export function childLeaves(steps) {
+    const visible = steps.filter(step => !/(?:^|--)complete-[1-9][0-9]*$/.test(step.id));
+    const parents = new Set(visible.flatMap(step => step.after ?? []));
+    return visible.map(step => step.id).filter(id => !parents.has(id));
+}
+/** A child may use only provider/MCP capabilities its parent already declared. */
+function assertChildCapabilities(parent, child) {
+    const parentTools = parent.header?.tools ?? {};
+    const childTools = child.header?.tools ?? {};
+    for (const [tool, declared] of Object.entries(childTools)) {
+        if (tool === 'mcp') {
+            const allowed = new Set(Array.isArray(parentTools.mcp) ? parentTools.mcp : []);
+            const requested = Array.isArray(declared) ? declared : [];
+            if (requested.some(server => !allowed.has(server))) {
+                throw new AuthoredFlowExecutionError('dispatch_invalid', `child flow "${child.name}" widens tools.mcp beyond parent "${parent.name}"`);
+            }
+        }
+    }
+    const parentHelpers = helperAuthority(parent);
+    for (const requirement of flowRequirements(child).integrations) {
+        if ((requirement.from === 'tools' || requirement.from === 'helper')
+            && !parentHelpers.has(requirement.provider)) {
+            throw new AuthoredFlowExecutionError('dispatch_invalid', `child flow "${child.name}" requires ${requirement.detail}, which parent "${parent.name}" did not grant`);
+        }
+    }
+}
+/** Helper providers this flow can delegate, from explicit or statically visible use. */
+export function helperAuthority(definition) {
+    return new Set(flowRequirements(definition).integrations
+        .filter(requirement => requirement.from === 'tools' || requirement.from === 'helper')
+        .map(requirement => requirement.provider));
+}
+//# sourceMappingURL=authored-dispatch.js.map

package/dist/authored-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-dispatch.js","sourceRoot":"","sources":["../src/authored-dispatch.ts"],"names":[],"mappings":"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"}

package/dist/authored-flow-error.d.ts

@@ -1,13 +1,17 @@
 import type { HumanRecipient } from './human-to.js';
 import type { ParkCause, StepFailedDetails } from './failure-kinds.js';
 import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason } from './protocol.js';
-export type AuthoredFlowExecutionErrorCode = 'helper_provider.mount_required' | 'helper_provider.unsupported' | 'helper_slack.credential_missing' | 'helper_slack.mount_required' | 'budget_syntax_invalid' | 'agent_cli_unresolved' | 'agent_parked' | 'llm_cli_unresolved' | 'llm_parked' | 'duplicate_completion' | 'journal_protocol_violation' | 'missing_completion' | 'memory_unreachable' | 'operation_after_completion' | 'operation_callback_failed' | 'step_failed' | 'lease_exceeded' | 'unsupported_completion' | 'unsupported_gate' | 'gate_failed'
+export type AuthoredFlowExecutionErrorCode = 'helper_provider.mount_required' | 'helper_provider.unsupported' | 'helper_slack.credential_missing' | 'helper_slack.mount_required' | 'budget_syntax_invalid'
+/** The step's CLI is too old for its model — an environment refusal, not a spec error. */
+ | 'cli_outdated'
+/** The step's credential hit a provider usage/rate limit during preflight. */
+ | 'provider_usage_limited' | 'agent_cli_unresolved' | 'agent_parked' | 'llm_cli_unresolved' | 'llm_parked' | 'duplicate_completion' | 'dispatch_depth_exceeded' | 'dispatch_invalid' | 'dispatch_unknown' | 'journal_protocol_violation' | 'missing_completion' | 'memory_unreachable' | 'operation_after_completion' | 'operation_callback_failed' | 'step_failed' | 'lease_exceeded' | 'unsupported_completion' | 'unsupported_gate' | 'gate_failed'
 /** The body reached an unanswered `f.human`; the root parked on it. */
  | 'human_parked'
 /** A recorded answer to `f.human` was not `{ answer: boolean }`. */
  | 'human_answer_invalid'
 /** `f.human`'s `to` is not one of the documented recipient forms (human-to.ts). */
- | 'human_to_invalid' | 'unsupported_header' | 'unsettled_derived_work' | 'unsupported_promise_lifecycle' | 'unsupported_workspace_permission' | 'unawaited_step' | 'unsupported_verb';
+ | 'human_to_invalid' | 'unsupported_header' | 'unsettled_derived_work' | 'unsupported_promise_lifecycle' | 'unsupported_workspace_permission' | 'unbounded_subscription' | 'activity_closed' | 'subscription_suspended' | 'unawaited_step' | 'unsupported_verb';
 export declare class AuthoredFlowExecutionError extends Error {
     readonly code: AuthoredFlowExecutionErrorCode;
     readonly completionReason?: (ProtocolCompletionReason | ProtocolRunCompletionReason) | undefined;
@@ -26,6 +30,7 @@ export declare class AuthoredFlowExecutionError extends Error {
      * Node-child error frame — can forward it instead of dropping it.
      */
     readonly details?: StepFailedDetails | undefined;
+    readonly suspension?: AuthoredFlowSuspension | undefined;
     /** Set by the durable root driver after the child error crosses any IPC boundary. */
     rootRunId?: string;
     /**
@@ -55,8 +60,32 @@ export declare class AuthoredFlowExecutionError extends Error {
      * wrapper on the way out — the `lease_exceeded` remap, the authenticated
      * Node-child error frame — can forward it instead of dropping it.
      */
-    details?: StepFailedDetails | undefined);
+    details?: StepFailedDetails | undefined, suspension?: AuthoredFlowSuspension | undefined);
 }
+/** Serialized into the CLI report so Cloud can atomically finish activation or wait for a wake. */
+export type AuthoredFlowSuspension = 
+/**
+ * Exact durable `subscription.prepared` facts Cloud must persist before it
+ * fences provider ingress and invokes `subscription.activate`. Binding
+ * generation and ingress cursor are Cloud-assigned receipts, deliberately
+ * absent from the authored request.
+ */
+{
+    readonly kind: 'activation';
+    readonly subscriptionId: string;
+    readonly eventTypes: readonly string[];
+    readonly pattern?: Readonly<Record<string, unknown>>;
+    readonly stream: string;
+    readonly settleMs: number;
+    readonly idleMs: number;
+    readonly deadlineAtMs: number;
+    readonly includeSelf: boolean;
+} | {
+    readonly kind: 'event_wait';
+    readonly subscriptionId: string;
+    readonly stream: string;
+    readonly deadlineAtMs: number;
+};
 /** The question an authored body parked on, as the kernel journals it. */
 export interface AuthoredHumanWait {
     readonly waitId: string;

package/dist/authored-flow-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-error.d.ts","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EACV,gBAAgB,IAAI,wBAAwB,EAC5C,mBAAmB,IAAI,2BAA2B,EACnD,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,8BAA8B,GACtC,gCAAgC,GAChC,6BAA6B,GAC7B,iCAAiC,GACjC,6BAA6B,GAC7B,uBAAuB,GACvB,sBAAsB,GACtB,cAAc,GACd,oBAAoB,GACpB,YAAY,GACZ,sBAAsB,GACtB,4BAA4B,GAC5B,oBAAoB,GACpB,oBAAoB,GACpB,4BAA4B,GAC5B,2BAA2B,GAC3B,aAAa,GACb,gBAAgB,GAChB,wBAAwB,GACxB,kBAAkB,GAClB,aAAa;AACf,uEAAuE;GACrE,cAAc;AAChB,oEAAoE;GAClE,sBAAsB;AACxB,mFAAmF;GACjF,kBAAkB,GAClB,oBAAoB,GACpB,wBAAwB,GACxB,+BAA+B,GAC/B,kCAAkC,GAClC,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,qBAAa,0BAA2B,SAAQ,KAAK;IAgBjD,QAAQ,CAAC,IAAI,EAAE,8BAA8B;IAE7C,QAAQ,CAAC,gBAAgB,CAAC,GAAE,wBAAwB,GAAG,2BAA2B;IAClF;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB;IAhCtC,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;gBAEX,IAAI,EAAE,8BAA8B,EAC7C,OAAO,EAAE,MAAM,EACN,gBAAgB,CAAC,GAAE,wBAAwB,GAAG,2BAA2B,aAAA;IAClF;;;;OAIG;IACM,KAAK,CAAC,EAAE,MAAM,YAAA;IACvB;;;;;;;OAOG;IACM,OAAO,CAAC,EAAE,iBAAiB,YAAA;CAKvC;AAED,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,0BAA0B;IACrD,QAAQ,CAAC,IAAI,EAAE,iBAAiB;gBAAvB,IAAI,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM;CAShE"}
+{"version":3,"file":"authored-flow-error.d.ts","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"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"}

package/dist/authored-flow-error.js

@@ -3,6 +3,7 @@ export class AuthoredFlowExecutionError extends Error {
     completionReason;
     runId;
     details;
+    suspension;
     /** Set by the durable root driver after the child error crosses any IPC boundary. */
     rootRunId;
     /**
@@ -32,12 +33,13 @@ export class AuthoredFlowExecutionError extends Error {
      * wrapper on the way out — the `lease_exceeded` remap, the authenticated
      * Node-child error frame — can forward it instead of dropping it.
      */
-    details) {
+    details, suspension) {
         super(`${code}: ${message}`);
         this.code = code;
         this.completionReason = completionReason;
         this.runId = runId;
         this.details = details;
+        this.suspension = suspension;
         this.name = 'AuthoredFlowExecutionError';
     }
 }

package/dist/authored-flow-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-error.js","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAyCA,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAgBxC;IAEA;IAMA;IASA;IAhCX,qFAAqF;IACrF,SAAS,CAAU;IACnB;;;;;;;;;;OAUG;IACH,SAAS,CAAa;IACtB,YACW,IAAoC,EAC7C,OAAe,EACN,gBAAyE;IAClF;;;;OAIG;IACM,KAAc;IACvB;;;;;;;OAOG;IACM,OAA2B;QAEpC,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QAnBpB,SAAI,GAAJ,IAAI,CAAgC;QAEpC,qBAAgB,GAAhB,gBAAgB,CAAyD;QAMzE,UAAK,GAAL,KAAK,CAAS;QASd,YAAO,GAAP,OAAO,CAAoB;QAGpC,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAWD;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,0BAA0B;IAC5C;IAArB,YAAqB,IAAuB,EAAE,SAAiB;QAC7D,KAAK,CACH,cAAc,EACd,uBAAuB,IAAI,CAAC,EAAE,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,EAC5F,SAAS,EACT,SAAS,CACV,CAAC;QANiB,SAAI,GAAJ,IAAI,CAAmB;QAO1C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}
+{"version":3,"file":"authored-flow-error.js","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAmDA,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAgBxC;IAEA;IAMA;IASA;IACA;IAjCX,qFAAqF;IACrF,SAAS,CAAU;IACnB;;;;;;;;;;OAUG;IACH,SAAS,CAAa;IACtB,YACW,IAAoC,EAC7C,OAAe,EACN,gBAAyE;IAClF;;;;OAIG;IACM,KAAc;IACvB;;;;;;;OAOG;IACM,OAA2B,EAC3B,UAAmC;QAE5C,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QApBpB,SAAI,GAAJ,IAAI,CAAgC;QAEpC,qBAAgB,GAAhB,gBAAgB,CAAyD;QAMzE,UAAK,GAAL,KAAK,CAAS;QASd,YAAO,GAAP,OAAO,CAAoB;QAC3B,eAAU,GAAV,UAAU,CAAyB;QAG5C,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAoCD;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,0BAA0B;IAC5C;IAArB,YAAqB,IAAuB,EAAE,SAAiB;QAC7D,KAAK,CACH,cAAc,EACd,uBAAuB,IAAI,CAAC,EAAE,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,EAC5F,SAAS,EACT,SAAS,CACV,CAAC;QANiB,SAAI,GAAJ,IAAI,CAAmB;QAO1C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/dist/authored-flow-executor.d.ts

@@ -1,13 +1,16 @@
+import { AuthoredBudget } from './authored-budget.js';
 import { type LoweredCompletionReason } from './authored-completion.js';
 import { type FlowHandle } from '@relayflows/surface/runtime';
 import { type ProgressEvent } from './progress.js';
 import type { GetFlowDefinition } from './authored-flow-loader.js';
+import type { LoadedAuthoredFlowNode } from './authored-flow-loader.js';
 import type { RunLifecycleOptions } from './cli/run.js';
-import { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
+import { AuthoredFlowExecutionError, type AuthoredFlowSuspension, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
 import { type AuthoredStepEdges } from './authored-step-index.js';
 import { JournalClient } from './journal-client.js';
 import { type HostedExtensionDispatch, type LoadedFlowExtension } from './flow-extension-loader.js';
 import type { CompletionReason as ProtocolCompletionReason } from './protocol.js';
+import type { AuthoredWorkerSlots } from './worker-slots.js';
 export { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode };
 export interface AuthoredFlowJournalStep extends AuthoredStepEdges {
     readonly id: string;
@@ -21,6 +24,7 @@ export interface AuthoredExecutionRuntime {
     readonly payloadSha256: string;
 }
 export interface AuthoredFlowExecutionResult {
+    readonly state?: undefined;
     readonly executionRuntime?: AuthoredExecutionRuntime;
     readonly rootRunId?: string;
     readonly name: string;
@@ -33,6 +37,13 @@ export interface AuthoredFlowExecutionResult {
     readonly completionDetail?: string;
     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[];
+}
 /**
  * Exercise the internal authored-flow lowering seam through protocol v0.
  *
@@ -87,6 +98,20 @@ export interface ExecuteAuthoredFlowOptions {
      * from authored input: direct `/workflows/run` callers control that JSON.
      */
     readonly extensionDispatch?: HostedExtensionDispatch;
+    /** Pinned static `use:` graph available to `f.dispatch`. */
+    readonly flowGraph?: readonly LoadedAuthoredFlowNode[];
+    /** Internal namespace for descendant step/admission identities. */
+    readonly stepPrefix?: string;
+    /** Current child depth. Root is zero; dispatch is capped at three. */
+    readonly dispatchDepth?: number;
+    /** Parent predecessors inherited by the first operation in a child body. */
+    readonly entryAfter?: readonly string[];
+    /** Root-owned budget accumulator shared by every descendant. */
+    readonly sharedBudget?: AuthoredBudget;
+    /** Root-owned worker capacity shared by every descendant. */
+    readonly workerSlots?: AuthoredWorkerSlots;
+    /** Parent helper authority inherited by this dispatched child. */
+    readonly allowedHelperProviders?: ReadonlySet<string>;
 }
 export declare function executeAuthoredFlow<Input = undefined>(handle: FlowHandle, journal: JournalClient, input?: Input, options?: ExecuteAuthoredFlowOptions): Promise<AuthoredFlowExecutionResult>;
 //# sourceMappingURL=authored-flow-executor.d.ts.map

package/dist/authored-flow-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-executor.d.ts","sourceRoot":"","sources":["../src/authored-flow-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authored-flow-executor.d.ts","sourceRoot":"","sources":["../src/authored-flow-executor.ts"],"names":[],"mappings":"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"}

package/dist/authored-flow-executor.js

@@ -24,10 +24,12 @@ import { readHumanAnswer } from './authored-human.js';
 import { parseHumanTo } from './human-to.js';
 import { AuthoredFlowOperation, stopAuthoredOperations, verifyAuthoredOperations, } from './authored-flow-operation.js';
 import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
+import { AuthoredActivities } from './authored-activity.js';
 import { displayLabel } from './authored-step-index.js';
 import { PluginError } from './plugin-manifest.js';
 import { createHookEvaluator } from './authored-hooks.js';
 import { extensionHandlerForHostedDispatch, probeFlowExtension, } from './flow-extension-loader.js';
+import { childLeaves, helperAuthority, parseDispatchReceipt, resolveDispatchChild } from './authored-dispatch.js';
 export { AuthoredFlowExecutionError };
 export async function executeAuthoredFlow(handle, journal, input, options = {}) {
     assertAuthoredPromiseHooks();
@@ -46,7 +48,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     };
     const definition = getDefinition(handle);
     const hostedHandler = extensionHandlerForHostedDispatch(options.extensionDispatch, options.extensions ?? []);
-    const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory' && key !== 'version' && key !== 'hooks');
+    const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory' && key !== 'version' && key !== 'hooks' && key !== 'use');
     if (definition.header.tools && Object.keys(definition.header.tools).some(key => !['mcp', ...helperProviders.map(p => p.namespace)].includes(key)))
         headerFields.push('tools');
     if (definition.header.tools?.relayfile !== undefined)
@@ -75,7 +77,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
         // the manifest boundary, not merely proxy selected Ctx properties.
         throw new PluginError('plugin_unsupported', `${hostedHandler.extension.name}: hosted extension handlers require enforced manifest permission isolation (gate 8 / #442).`);
     }
-    const budget = new AuthoredBudget(definition.header.budget);
+    const budget = options.sharedBudget ?? new AuthoredBudget(definition.header.budget);
     if (definition.header.memory?.agent === true) {
         throw new AuthoredFlowExecutionError('unsupported_header', 'memory.agent requires the follow-up identity-scoped agent memory adapter');
     }
@@ -87,16 +89,35 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     const journalSteps = [];
     const authoredSteps = [];
     const lifecycle = new AuthoredFlowLifecycle();
-    const stepEdges = (step) => lifecycle.stepEdges(step);
+    const activities = new AuthoredActivities(journal, options.rootRunId);
+    const edgeOverrides = new Map();
+    const stepEdges = (step) => {
+        const overridden = edgeOverrides.get(step);
+        if (overridden !== undefined)
+            return overridden;
+        const local = lifecycle.stepEdges(step);
+        if (local === undefined || (local.after !== undefined && local.after.length > 0) || options.entryAfter === undefined
+            || options.entryAfter.length === 0)
+            return local;
+        return { ...local, after: [...options.entryAfter] };
+    };
     let nextStep = 1;
     let requestedCompletion;
     let requestedDetail;
+    const qualify = (id) => `${options.stepPrefix ?? ''}${id}`;
+    const nextId = (kind) => qualify(`${kind}-${nextStep++}`);
+    const assertHelperAllowed = (provider) => {
+        if (options.allowedHelperProviders !== undefined && !options.allowedHelperProviders.has(provider)) {
+            throw new AuthoredFlowExecutionError('dispatch_invalid', `child flow "${definition.name}" attempted helper provider "${provider}" outside its parent's granted integrations`);
+        }
+    };
     const lowerDeterministic = authoredDeterministicRunner(definition.name, journal, journalSteps, budget, {
         ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
         ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
         stepEdges,
     });
-    const worker = authoredWorkerRunner(definition, journal, flowPath, journalSteps, waitOptions, localAgentStream, budget, definition.header.budget, options.rootRunId, options.workerCapacity, stepEdges);
+    const worker = authoredWorkerRunner(definition, journal, flowPath, journalSteps, waitOptions, localAgentStream, budget, definition.header.budget, options.rootRunId, options.workerCapacity, stepEdges, options.workerSlots);
     /**
      * Predicate gates (docs/SURFACE.md §6). The closure runs here, once, on the
      * value the journal handed back; the VERDICT is then journaled as a lowered
@@ -194,7 +215,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     lifecycle.applyPredicateGate = applyPredicateGate;
     function llmOperation(prompt, ...values) {
         assertOperationAllowed('llm', definition.name, requestedCompletion);
-        const id = `llm-${nextStep++}`;
+        const id = nextId('llm');
         // Hoist the operation reference so the start closure can read the
         // caller's `.gate(config)` at spec-build time. AuthoredFlowOperation
         // begins after construction returns, so `llmOp` is defined by then.
@@ -222,7 +243,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
         if (policy !== undefined && policy !== 'fail' && policy !== 'record') {
             throw new AuthoredFlowExecutionError('unsupported_verb', `f.run options.onNonZero must be 'fail' or 'record' (got ${JSON.stringify(policy)}).`);
         }
-        const id = `run-${nextStep++}`;
+        const id = nextId('run');
         if (policy === 'record') {
             let recordOp;
             recordOp = new AuthoredFlowOperation(id, 'run', () => assertOperationAllowed('run', definition.name, requestedCompletion), () => observeStep(id, 'deterministic', () => lowerDeterministic.recording(id, command, leaseMs, recordOp.namedGate), options.onProgress), lifecycle, 
@@ -241,8 +262,9 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     const slackRun = options.rootRunId ?? randomUUID();
     function slackOperation(call) {
         assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
+        assertHelperAllowed(call.provider);
         const snapshot = snapshotJsonValue(call, 'f.slack call');
-        const id = `slack-${slackRun}-${nextStep++}`;
+        const id = qualify(`slack-${slackRun}-${nextStep++}`);
         return trackStep(authoredSteps, new AuthoredFlowOperation(id, `slack.${call.verb}`, () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion), async () => {
             const receipt = await runHelperEffect(journal, definition.name, id, snapshot, options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId);
             return (call.verb === 'react' ? undefined : receipt);
@@ -262,8 +284,9 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
         ...createHelpers((call) => {
             const verb = `${call.provider}.${call.verb}`;
             assertOperationAllowed(verb, definition.name, requestedCompletion);
+            assertHelperAllowed(call.provider);
             const snapshot = snapshotJsonValue(call, `f.${verb} call`);
-            const id = `${call.provider}-${slackRun}-${nextStep++}`;
+            const id = qualify(`${call.provider}-${slackRun}-${nextStep++}`);
             return trackStep(authoredSteps, new AuthoredFlowOperation(id, verb, () => assertOperationAllowed(verb, definition.name, requestedCompletion), async () => await runHelperEffect(journal, definition.name, id, snapshot, options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId), lifecycle));
         }),
         slack: {
@@ -274,7 +297,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
         },
         mcp: buildMcpProxy(checkedMcp.inventory, (server, tool, args, known) => {
             assertOperationAllowed('mcp', definition.name, requestedCompletion);
-            const id = `mcp-${nextStep++}`;
+            const id = nextId('mcp');
             return trackStep(authoredSteps, new AuthoredFlowOperation(id, 'mcp', () => assertOperationAllowed('mcp', definition.name, requestedCompletion), () => runMcpEffect(journal, definition.name, id, server, tool, args, known, checkedMcp.servers[server], journalSteps, options.rootRunId), lifecycle));
         }),
         memory: authoredMemory(scriptMemoryScope(flowPath, definition.name), () => assertOperationAllowed('memory', definition.name, requestedCompletion), definition.header.memory?.script !== false),
@@ -284,11 +307,19 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
             assertOperationAllowed('agent', definition.name, requestedCompletion);
             // Authored headers do not yet declare reusable named agents, so the name
             // identifies nothing to the kernel; it is the step's label in the DAG.
-            const id = `agent-${nextStep++}`;
+            const id = nextId('agent');
             let agentOp;
             agentOp = new AuthoredFlowOperation(id, 'agent', () => assertOperationAllowed('agent', definition.name, requestedCompletion), () => observeStep(id, 'agent', () => worker.agent(id, options, agentOp.namedGate), onProgress), lifecycle, displayLabel(typeof name === 'string' ? name : 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
@@ -306,6 +337,9 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
          */
         human(question, humanOptions) {
             assertOperationAllowed('human', definition.name, requestedCompletion);
+            if ((options.dispatchDepth ?? 0) > 0) {
+                throw new AuthoredFlowExecutionError('dispatch_invalid', `child flow "${definition.name}" cannot call f.human in this release; the parent owns approval authority`);
+            }
             if (typeof question !== 'string' || question.trim() === '') {
                 throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires a non-empty question');
             }
@@ -319,7 +353,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
             if (!parsedTo.ok) {
                 throw new AuthoredFlowExecutionError('human_to_invalid', `f.human to ${parsedTo.reason}`);
             }
-            const id = `human-${nextStep++}`;
+            const id = nextId('human');
             const to = humanOptions.to;
             // Hoisted like `llmOp`/`runOp`: the start closure reads the caller's
             // `.gate(config)` at spec-build time, so a named gate on the answer is
@@ -343,13 +377,66 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
             }, options.onProgress), lifecycle, {});
             return trackStep(authoredSteps, humanOp);
         },
-        dispatch() {
+        dispatch(flowName, dispatchInput) {
             assertOperationAllowed('dispatch', definition.name, requestedCompletion);
-            throw unsupportedVerb('dispatch');
+            const depth = options.dispatchDepth ?? 0;
+            const child = resolveDispatchChild({
+                handle, definition, graph: options.flowGraph,
+                flowName, depth,
+            });
+            const childDefinition = child.getDefinition(child.handle);
+            const inputSnapshot = snapshotJsonValue(dispatchInput, `f.dispatch(${JSON.stringify(flowName)}) input`);
+            const id = nextId('dispatch');
+            let dispatchOp;
+            dispatchOp = new AuthoredFlowOperation(id, 'dispatch', () => assertOperationAllowed('dispatch', definition.name, requestedCompletion), async () => {
+                const inheritedAfter = stepEdges(id)?.after ?? [];
+                const currentHelperAuthority = helperAuthority(definition);
+                const allowedHelperProviders = options.allowedHelperProviders === undefined
+                    ? currentHelperAuthority
+                    : new Set([...currentHelperAuthority].filter(provider => options.allowedHelperProviders.has(provider)));
+                const childResult = await executeAuthoredFlow(child.handle, journal, inputSnapshot, {
+                    getDefinition: child.getDefinition,
+                    dataDir: options.dataDir,
+                    flowPath: child.path,
+                    ...(localAgentStream === undefined ? {} : { localAgentStream }),
+                    ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
+                    ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
+                    flowGraph: options.flowGraph,
+                    stepPrefix: `${id}--`,
+                    dispatchDepth: depth + 1,
+                    entryAfter: inheritedAfter,
+                    sharedBudget: budget,
+                    ...(worker.slots === undefined ? {} : { workerSlots: worker.slots }),
+                    allowedHelperProviders,
+                    ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
+                    onProgress,
+                    ...(options.onWait === undefined ? {} : { onWait: options.onWait }),
+                    ...(options.signal === undefined ? {} : { signal: options.signal }),
+                });
+                if (childResult.completionReason !== 'success') {
+                    throw new AuthoredFlowExecutionError('step_failed', `child flow "${childResult.name}" completed with ${childResult.completionReason}`
+                        + (childResult.completionDetail === undefined ? '' : `: ${childResult.completionDetail}`), childResult.completionReason === 'step_failed' ? 'step_failed' : undefined);
+                }
+                const leaves = childLeaves(childResult.journalSteps);
+                edgeOverrides.set(id, {
+                    ...displayLabel(childResult.name),
+                    ...(leaves.length > 0 ? { after: leaves } : inheritedAfter.length === 0
+                        ? {} : { after: inheritedAfter }),
+                });
+                const receipt = {
+                    name: childResult.name,
+                    completionReason: 'success',
+                    ...(childResult.completionDetail === undefined ? {} : { completionDetail: childResult.completionDetail }),
+                };
+                const literal = `'${JSON.stringify(receipt).replaceAll("'", "'\\''")}'`;
+                const recorded = await lowerDeterministic(id, `printf '%s' ${literal}`, false, undefined, dispatchOp.namedGate);
+                return parseDispatchReceipt(recorded, id);
+            }, lifecycle, displayLabel(flowName));
+            return trackStep(authoredSteps, dispatchOp);
         },
         hook(name, input) {
             assertOperationAllowed('hook', definition.name, requestedCompletion);
-            const id = `hook-${nextStep++}`;
+            const id = nextId('hook');
             const snapshot = snapshotJsonValue(input, 'f.hook input');
             return trackStep(authoredSteps, new AuthoredFlowOperation(id, 'hook', () => assertOperationAllowed('hook', definition.name, requestedCompletion), async () => {
                 const verdict = await evaluateHook(id, name, snapshot, context);
@@ -395,7 +482,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     Object.assign(context, pluginHelpers(checkedMcp.plugins ?? [], (plugin, verb, args) => {
         const label = `${verb.namespace}.${verb.method}`;
         assertOperationAllowed(label, definition.name, requestedCompletion);
-        const id = `plugin-${nextStep++}`;
+        const id = nextId('plugin');
         return trackStep(authoredSteps, new AuthoredFlowOperation(id, label, () => assertOperationAllowed(label, definition.name, requestedCompletion), () => runPluginEffect(journal, definition.name, id, plugin, verb, args, journalSteps, budget, options.rootRunId), lifecycle));
     }));
     let bodyFailed = false;
@@ -412,6 +499,12 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
         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();
@@ -437,6 +530,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
         try {
             worker.stop(missingCompletion);
             await stopAuthoredOperations(authoredSteps, missingCompletion);
+            await activities.closeAll('canceled');
         }
         finally {
             lifecycle.close();
@@ -446,6 +540,18 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     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();
     }
@@ -463,7 +569,7 @@ export async function executeAuthoredFlow(handle, journal, input, options = {})
     // explanation the root had already journaled to `run_admission_conflict`.
     // With no detail there is no environment in the command and nothing to
     // commit, so that path is untouched.
-    const terminalId = `complete-${nextStep}`;
+    const terminalId = qualify(`complete-${nextStep}`);
     const verdict = await commitAuthoredVerdict(journal, options.rootRunId, terminalId, {
         reason: requestedCompletion,
         ...(requestedDetail === undefined ? {} : { detail: requestedDetail }),