@relayflows/sdk 2.0.34 → 2.0.35

package/dist/worker-slots.js

@@ -26,20 +26,38 @@ export class WorkerSlots {
             throw new RangeError(`worker capacity must be an integer from 1 to ${MAX_LOCAL_AGENT_CAPACITY} (got ${capacity})`);
     }
     async run(work) {
+        return this.runInScope(work);
+    }
+    /** One independently closable admission scope over this shared capacity. */
+    scope() {
+        const scope = {};
+        return Object.freeze({
+            run: (work) => this.runInScope(work, scope),
+            close: (reason) => this.closeScope(scope, reason),
+        });
+    }
+    async runInScope(work, scope) {
         if (this.closed !== undefined)
             throw this.closed.reason;
+        if (scope?.closed !== undefined)
+            throw scope.closed.reason;
         if (this.held < this.capacity)
             this.held++;
         // A released slot is handed straight to the next waiter, so `held` never
         // dips below capacity while anyone is queued and no later caller can jump it.
         else {
-            await new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
+            await new Promise((resolve, reject) => this.waiting.push({ resolve, reject, scope }));
             // Woken with the slot, but the body may have failed in between (see release).
             const closed = this.closedReason();
             if (closed !== undefined) {
                 this.release();
                 throw closed.reason;
             }
+            const scopeClosed = scopeClosedReason(scope);
+            if (scopeClosed !== undefined) {
+                this.release();
+                throw scopeClosed.reason;
+            }
         }
         try {
             return await work();
@@ -66,16 +84,28 @@ export class WorkerSlots {
             return;
         }
         setImmediate(() => {
-            if (this.closed === undefined) {
+            if (this.closed === undefined && next.scope?.closed === undefined) {
                 next.resolve();
                 return;
             }
             // Closed meanwhile. `close` could not see this waiter (already taken off
             // the queue), so refuse it here, and pass the slot on instead of leaking it.
-            next.reject(this.closed.reason);
+            next.reject(this.closed?.reason ?? next.scope.closed.reason);
             this.release();
         });
     }
+    closeScope(scope, reason) {
+        if (scope.closed !== undefined)
+            return;
+        scope.closed = { reason };
+        for (let index = this.waiting.length - 1; index >= 0; index--) {
+            const waiter = this.waiting[index];
+            if (waiter.scope !== scope)
+                continue;
+            this.waiting.splice(index, 1);
+            waiter.reject(reason);
+        }
+    }
     /**
      * Refuse every queued and future admission with `reason`; work already
      * holding a slot is not interrupted. The authored body calls this when it
@@ -91,4 +121,11 @@ export class WorkerSlots {
             waiter.reject(reason);
     }
 }
+/** Read through a call so a check after an `await` is not narrowed away. */
+function scopeClosedReason(scope) {
+    return scope?.closed;
+}
+export function authoredWorkerSlots(capacity) {
+    return Object.freeze({ agent: new WorkerSlots(capacity), llm: new WorkerSlots(capacity) });
+}
 //# sourceMappingURL=worker-slots.js.map

package/dist/worker-slots.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker-slots.js","sourceRoot":"","sources":["../src/worker-slots.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,IAAI,CAAC,IAAK,KAAgB,IAAI,wBAAwB,CAAC;AAC5G,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAW;IAKD;IAJb,IAAI,GAAG,CAAC,CAAC;IACA,OAAO,GAAsE,EAAE,CAAC;IACzF,MAAM,CAA2C;IAEzD,YAAqB,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;QACnC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,gDAAgD,wBAAwB,SAAS,QAAQ,GAAG,CAAC,CAAC;IACrJ,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,IAAsB;QACjC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QACxD,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,yEAAyE;QACzE,8EAA8E;aACzE,CAAC;YACJ,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;YACrF,8EAA8E;YAC9E,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,MAAM,MAAM,CAAC,MAAM,CAAC;YACtB,CAAC;QACH,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED,4EAA4E;IACpE,YAAY;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACK,OAAO;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QACD,YAAY,CAAC,GAAG,EAAE;YAChB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,OAAO;YACT,CAAC;YACD,yEAAyE;YACzE,6EAA6E;YAC7E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAe;QACnB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,IAAI,CAAC,MAAM,GAAG,EAAE,MAAM,EAAE,CAAC;QACzB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;CACF"}
+{"version":3,"file":"worker-slots.js","sourceRoot":"","sources":["../src/worker-slots.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.34",
+  "version": "2.0.35",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.6.2",
     "@relayfile/relay-helpers": "0.4.12",
-    "@relayflows/surface": "2.0.34",
+    "@relayflows/surface": "2.0.35",
     "@types/js-yaml": "^4.0.9",
     "acorn": "^8.18.0",
     "ai-hist": "0.4.1",

package/src/authored-dispatch.ts

@@ -0,0 +1,113 @@
+import type { DispatchResult } from '@relayflows/surface';
+import type { FlowHandle } from './authored-flow.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { LoadedAuthoredFlowNode } from './authored-flow-loader.js';
+import { flowRequirements, type RequirementsFlowDefinition } 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: {
+  readonly handle: FlowHandle;
+  readonly definition: RequirementsFlowDefinition & { readonly name: string };
+  readonly graph?: readonly LoadedAuthoredFlowNode[];
+  readonly flowName: string;
+  readonly depth: number;
+}): LoadedAuthoredFlowNode {
+  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 is LoadedAuthoredFlowNode =>
+    node !== undefined && node.getDefinition(node.handle).name === options.flowName);
+  if (matches.length !== 1) {
+    const declared = direct.filter((node): node is LoadedAuthoredFlowNode => 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: string, step: string): DispatchResult {
+  let parsed: unknown;
+  try { parsed = JSON.parse(value); } catch {
+    throw new AuthoredFlowExecutionError('journal_protocol_violation', `dispatch step "${step}" recorded invalid JSON`);
+  }
+  const receipt = parsed as Partial<DispatchResult> | null;
+  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: readonly { readonly id: string; readonly after?: readonly string[] }[]): string[] {
+  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: RequirementsFlowDefinition & { readonly name: string },
+  child: RequirementsFlowDefinition & { readonly name: string },
+): void {
+  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 as readonly unknown[] : []);
+      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: RequirementsFlowDefinition,
+): ReadonlySet<string> {
+  return new Set(flowRequirements(definition).integrations
+    .filter(requirement => requirement.from === 'tools' || requirement.from === 'helper')
+    .map(requirement => requirement.provider));
+}

package/src/authored-flow-error.ts

@@ -16,6 +16,9 @@ export type AuthoredFlowExecutionErrorCode =
   | 'llm_cli_unresolved'
   | 'llm_parked'
   | 'duplicate_completion'
+  | 'dispatch_depth_exceeded'
+  | 'dispatch_invalid'
+  | 'dispatch_unknown'
   | 'journal_protocol_violation'
   | 'missing_completion'
   | 'memory_unreachable'

package/src/authored-flow-executor.ts

@@ -22,6 +22,7 @@ import {
 import { commitAuthoredVerdict } from './authored-completion-record.js';
 import {
   type AgentResult,
+  type DispatchResult,
   type LlmOptions,
   type CloudHelper,
   type CompletionReason as SurfaceCompletionReason,
@@ -38,6 +39,7 @@ import { observeStep, type ProgressEvent } from './progress.js';
 import { parseStepTimeout } from './compile.js';
 import { getAuthoredFlowDefinition } from './authored-flow.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,
@@ -66,6 +68,8 @@ import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
 } from './protocol.js';
+import type { AuthoredWorkerSlots } from './worker-slots.js';
+import { childLeaves, helperAuthority, parseDispatchReceipt, resolveDispatchChild } from './authored-dispatch.js';
 
 type Assert<T extends true> = T;
 type Equal<A, B> = [A] extends [B]
@@ -185,6 +189,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 async function executeAuthoredFlow<Input = undefined>(
@@ -209,7 +227,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   };
   const definition = getDefinition<Input>(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) headerFields.push('tools.relayfile');
   const helperPreflight = checkSlackHelpers(definition);
@@ -242,7 +260,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     );
   }
 
-  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');
   }
@@ -255,10 +273,28 @@ export async function executeAuthoredFlow<Input = undefined>(
   const journalSteps: AuthoredFlowJournalStep[] = [];
   const authoredSteps: AuthoredFlowOperation<unknown>[] = [];
   const lifecycle = new AuthoredFlowLifecycle();
-  const stepEdges = (step: string): AuthoredStepEdges | undefined => lifecycle.stepEdges(step);
+  const edgeOverrides = new Map<string, AuthoredStepEdges>();
+  const stepEdges = (step: string): AuthoredStepEdges | undefined => {
+    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: LoweredCompletionReason | undefined;
   let requestedDetail: string | undefined;
+  const qualify = (id: string): string => `${options.stepPrefix ?? ''}${id}`;
+  const nextId = (kind: string): string => qualify(`${kind}-${nextStep++}`);
+  const assertHelperAllowed = (provider: string): void => {
+    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, {
@@ -271,6 +307,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,
   );
 
   /**
@@ -373,7 +410,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   function llmOperation(prompt: string, options: LlmOptions): Step<unknown>;
   function llmOperation(prompt: string | TemplateStringsArray, ...values: unknown[]): Step<unknown> {
     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.
@@ -420,7 +457,7 @@ export async function executeAuthoredFlow<Input = undefined>(
         `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!: AuthoredFlowOperation<RunResult>;
       recordOp = new AuthoredFlowOperation<RunResult>(
@@ -451,8 +488,9 @@ export async function executeAuthoredFlow<Input = undefined>(
   const slackRun = options.rootRunId ?? randomUUID();
   function slackOperation<T>(call: SlackCall): Step<T> {
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
+    assertHelperAllowed(call.provider);
     const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
-    const id = `slack-${slackRun}-${nextStep++}`;
+    const id = qualify(`slack-${slackRun}-${nextStep++}`);
     return trackStep(authoredSteps, new AuthoredFlowOperation<T>(
       id, `slack.${call.verb}`,
       () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion),
@@ -480,8 +518,9 @@ export async function executeAuthoredFlow<Input = undefined>(
     ...createHelpers(<T>(call: HelperCall): Step<T> => {
       const verb = `${call.provider}.${call.verb}`;
       assertOperationAllowed(verb, definition.name, requestedCompletion);
+      assertHelperAllowed(call.provider);
       const snapshot = snapshotJsonValue(call, `f.${verb} call`) as unknown as HelperCall;
-      const id = `${call.provider}-${slackRun}-${nextStep++}`;
+      const id = qualify(`${call.provider}-${slackRun}-${nextStep++}`);
       return trackStep(authoredSteps, new AuthoredFlowOperation<T>(id, verb,
         () => assertOperationAllowed(verb, definition.name, requestedCompletion),
         async () => await runHelperEffect(journal, definition.name, id, snapshot,
@@ -496,7 +535,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     },
     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),
@@ -516,7 +555,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       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!: AuthoredFlowOperation<AgentResult>;
       agentOp = new AuthoredFlowOperation<AgentResult>(
         id,
@@ -545,6 +584,12 @@ export async function executeAuthoredFlow<Input = undefined>(
      */
     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');
       }
@@ -558,7 +603,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       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
@@ -590,13 +635,79 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, humanOp);
     },
-    dispatch<T>() {
+    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!: AuthoredFlowOperation<DispatchResult>;
+      dispatchOp = new AuthoredFlowOperation<DispatchResult>(
+        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: DispatchResult = {
+            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<boolean>(
         id, 'hook',
@@ -661,7 +772,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   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,
@@ -735,7 +846,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   // 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 }),

package/src/authored-flow-loader.ts

@@ -100,6 +100,18 @@ export async function loadAuthoredFlow(path: string, options: LoadAuthoredFlowOp
         }
         dependencies.push(child.path);
       }
+      const childNames = new Set<string>();
+      for (const path of dependencies) {
+        const child = loaded.get(path)!;
+        const name = child.getDefinition(child.handle).name;
+        if (childNames.has(name)) {
+          throw new AuthoredFlowLoadError(
+            `Flow "${absolutePath}" declares two direct use children named "${name}".`,
+            'use_invalid',
+          );
+        }
+        childNames.add(name);
+      }
       const node = Object.freeze({ path: absolutePath, handle, getDefinition, surfaceAuthority, use: Object.freeze(dependencies) });
       loaded.set(absolutePath, node);
       return node;

package/src/authored-node-entry.ts

@@ -75,6 +75,7 @@ try {
       getDefinition: loaded.getDefinition, dataDir: request.dataDir,
       flowPath: request.metadata.flowPath, rootRunId: request.rootRunId,
       extensions: loaded.extensions,
+      flowGraph: loaded.graph,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       ...(request.workerCapacity === undefined ? {} : { workerCapacity: request.workerCapacity }),
       onProgress: event => send({ type: 'progress', event }),

package/src/authored-root.ts

@@ -228,6 +228,7 @@ async function driveRoot(
           ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
           rootRunId: dispatch.run_id,
           extensions: loaded.extensions,
+          flowGraph: loaded.graph,
           ...options.lifecycle,
           signal: callerSignal === undefined
             ? rootSignal

package/src/authored-worker-step.ts

@@ -16,7 +16,7 @@ import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
 import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
-import { WorkerSlots } from './worker-slots.js';
+import { authoredWorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -26,11 +26,16 @@ export function authoredWorkerRunner(
   journalSteps: AuthoredFlowJournalStep[], waitOptions: RunLifecycleOptions,
   localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
   rootRunId?: string, workerCapacity?: number, stepEdges?: AuthoredStepContext['stepEdges'],
+  sharedSlots?: AuthoredWorkerSlots,
 ) {
   // Sized to the attached local workers, so concurrent calls wait here for a
   // slot instead of being admitted and parked for want of a free worker.
-  const slots = workerCapacity === undefined ? undefined
-    : { agent: new WorkerSlots(workerCapacity), llm: new WorkerSlots(workerCapacity) };
+  const ownsSlots = sharedSlots === undefined;
+  const slots = sharedSlots ?? (workerCapacity === undefined ? undefined : authoredWorkerSlots(workerCapacity));
+  const slotScopes = slots === undefined ? undefined : {
+    agent: slots.agent.scope(),
+    llm: slots.llm.scope(),
+  };
   const check = authoredPreflight(flowPath);
   const context: AuthoredStepContext = {
     ...(rootRunId === undefined ? {} : { rootRunId }),
@@ -136,14 +141,20 @@ export function authoredWorkerRunner(
     const admit = async () => budget === undefined
       ? consume(await journal.runStart(spec, undefined, admissionKey))
       : budget.execute(journal, spec, consume, admissionKey);
-    return slots === undefined ? admit() : slots[step.type === 'llm' ? 'llm' : 'agent'].run(admit);
+    return slotScopes === undefined ? admit() : slotScopes[step.type === 'llm' ? 'llm' : 'agent'].run(admit);
   }
 
   return {
+    slots,
     /** Refuse every agent/LLM call still waiting for a worker slot (body teardown). */
     stop(reason: unknown): void {
-      slots?.agent.close(reason);
-      slots?.llm.close(reason);
+      if (ownsSlots) {
+        slots?.agent.close(reason);
+        slots?.llm.close(reason);
+      } else {
+        slotScopes?.agent.close(reason);
+        slotScopes?.llm.close(reason);
+      }
     },
     async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
       if (options.workspace !== undefined && localAgentStream !== undefined) {

package/src/cli/run.ts

@@ -122,6 +122,8 @@ export interface RunLifecycleOptions {
   onJournalEntry?: (entry: JournalEvent) => void;
   /** An authored root was admitted: its id is known before its body runs. */
   onRunStarted?: (run: { runId: string; flow: string; resumed?: boolean }) => void;
+  /** A declarative root returned its admission receipt, even if no watched entry arrived. */
+  onRunReceipt?: (run: { runId: string; flow: string }) => void;
   localAgent?: boolean;
   /** `--agent-capacity`: the local workers' concurrency; the default is `DEFAULT_LOCAL_AGENT_CAPACITY`. */
   agentCapacity?: number;
@@ -191,6 +193,14 @@ async function executeCheckedFlow(
     }
     if (options.onJournalEntry !== undefined) client.on('entry', options.onJournalEntry);
     const outcome = await startWatched(client, spec, options);
+    // `run.start { watch: true }` is an event stream, not the source of the
+    // root identity. A short deterministic run can finish before its first
+    // watched entry is delivered (and an older daemon may refuse `watch`), so
+    // receipt consumers such as the Cloud mirror need the admitted id too.
+    // This stays separate from `onRunStarted`: opening the observer without a
+    // streamed journal would manufacture an empty projection and suppress its
+    // truthful "not projected" diagnostic.
+    options.onRunReceipt?.({ runId: outcome.run_id, flow: spec.name ?? 'flow' });
     const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
     if (options.reuseFromRunId !== undefined) {
       execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);

package/src/cli.ts

@@ -380,6 +380,9 @@ export async function runCli(
         observer?.onRunStarted(run);
         mirror?.onRunStarted(run);
       },
+      ...(mirror === undefined ? {} : {
+        onRunReceipt: (run: { runId: string }) => { mirror.onRunStarted(run); },
+      }),
     }),
     onWait: (progress: RunProgress) => {
       emitWait(progress, logged);