@relayflows/sdk 2.0.34 → 2.0.36

package/src/authored-activity.ts

@@ -0,0 +1,251 @@
+import type {
+  Activity,
+  ActivityDuration,
+  ActivityOptions,
+  EventFrame,
+  TriggerSource,
+  WebhookTriggerSource,
+  Wake,
+} from '@relayflows/surface';
+import type { SubscriptionNextResult } from './protocol.js';
+import { AuthoredFlowExecutionError, type AuthoredFlowSuspension } from './authored-flow-error.js';
+import { JournalClient } from './journal-client.js';
+
+type CloseReason = 'closed' | 'run_completed' | 'canceled';
+
+interface OpenActivity {
+  readonly activity: Activity;
+  close(reason: CloseReason): Promise<void>;
+}
+
+/** Owns body-local cursors that must close before the authored root completes. */
+export class AuthoredActivities {
+  private readonly activities: OpenActivity[] = [];
+
+  constructor(
+    private readonly journal: JournalClient,
+    private readonly runId: string | undefined,
+  ) {}
+
+  open(source: TriggerSource, options: ActivityOptions): Activity {
+    if (source?.kind !== 'webhook') {
+      throw new AuthoredFlowExecutionError('unsupported_header',
+        'f.on() requires an event source; schedule triggers start runs and cannot be awaited inside a body');
+    }
+    if (this.runId === undefined) {
+      throw new AuthoredFlowExecutionError('journal_protocol_violation', 'f.on() requires a durable authored root run');
+    }
+    const id = `activity-${this.activities.length + 1}`;
+    const activity = new JournalActivity(this.journal, this.runId, id, source, normalizeOptions(options));
+    this.activities.push(activity);
+    return activity.activity;
+  }
+
+  async closeAll(reason: Exclude<CloseReason, 'closed'>): Promise<void> {
+    for (const activity of this.activities) await activity.close(reason);
+  }
+}
+
+class JournalActivity implements OpenActivity {
+  readonly activity: Activity;
+  private readonly openPromise: Promise<void>;
+  private closed = false;
+  private nextSequence = 0;
+  private acknowledgeWaitId: string | undefined;
+
+  constructor(
+    private readonly journal: JournalClient,
+    private readonly runId: string,
+    private readonly subscriptionId: string,
+    private readonly source: WebhookTriggerSource,
+    private readonly options: NormalizedActivityOptions,
+  ) {
+    this.activity = Object.freeze({
+      next: () => this.next(),
+      close: () => this.close('closed'),
+    });
+    // Opening starts at f.on(), rather than at the first next(), so frames
+    // arriving while the body reads state or runs another step are inside the
+    // router's binding window. next()/close() await this same handshake.
+    this.openPromise = this.openNow();
+    void this.openPromise.catch(() => undefined);
+  }
+
+  async close(reason: CloseReason): Promise<void> {
+    if (this.closed) return;
+    try {
+      await this.ensureOpen();
+    } catch (error) {
+      // Failure cleanup has no active binding to close before activation.
+      // Re-throwing this handoff would disguise a real body failure as a
+      // normal suspension. Root termination fences any later activation.
+      if (reason !== 'closed' && error instanceof AuthoredFlowExecutionError
+        && error.code === 'subscription_suspended' && error.suspension?.kind === 'activation') return;
+      throw error;
+    }
+    await this.journal.subscriptionClose({
+      run_id: this.runId,
+      subscription_id: this.subscriptionId,
+      completion_reason: reason,
+    });
+    this.closed = true;
+  }
+
+  private async next(): Promise<Wake> {
+    if (this.closed) throw new AuthoredFlowExecutionError('activity_closed', 'activity is already closed');
+    await this.ensureOpen();
+    const result = await this.journal.subscriptionNext({
+      run_id: this.runId,
+      subscription_id: this.subscriptionId,
+      sequence: this.nextSequence,
+      ...(this.acknowledgeWaitId === undefined ? {} : { acknowledge_wait_id: this.acknowledgeWaitId }),
+    });
+    if (result.kind === 'suspended') {
+      throw suspended({
+        kind: 'event_wait', subscriptionId: result.subscription_id,
+        stream: result.stream, deadlineAtMs: result.deadline_at_ms,
+      }, this.runId);
+    }
+    const wake = decodeWake(result);
+    if (wake.kind === 'deadline' || wake.kind === 'overflow') {
+      this.closed = true;
+    } else {
+      this.acknowledgeWaitId = receiptId(result) ?? `${this.subscriptionId}/next/${this.nextSequence}`;
+      this.nextSequence += 1;
+    }
+    return wake;
+  }
+
+  private async ensureOpen(): Promise<void> {
+    await this.openPromise;
+  }
+
+  private async openNow(): Promise<void> {
+    const result = await this.journal.subscriptionOpen({
+      run_id: this.runId,
+      subscription_id: this.subscriptionId,
+      event_types: [this.source.name],
+      ...(this.source.filter === undefined ? {} : { pattern: this.source.filter }),
+      settle_ms: this.options.settleMs,
+      idle_ms: this.options.idleMs,
+      deadline_ms: this.options.deadlineMs,
+      include_self: this.options.includeSelf,
+    });
+    if (result.state === 'prepared') {
+      throw suspended({
+        kind: 'activation', subscriptionId: result.subscription_id,
+        eventTypes: Object.freeze([...result.event_types]),
+        ...(result.pattern === undefined ? {} : { pattern: Object.freeze({ ...result.pattern }) }),
+        stream: result.stream, settleMs: result.settle_ms, idleMs: result.idle_ms,
+        deadlineAtMs: result.deadline_at_ms, includeSelf: result.include_self,
+      }, this.runId);
+    }
+  }
+}
+
+function suspended(value: AuthoredFlowSuspension, runId: string): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError(
+    'subscription_suspended',
+    `subscription ${value.subscriptionId} is durably suspended for ${value.kind}`,
+    undefined,
+    runId,
+    undefined,
+    value,
+  );
+}
+
+function receiptId(result: SubscriptionNextResult): string | undefined {
+  const receipt = (result as { acknowledge_wait_id?: unknown }).acknowledge_wait_id;
+  return typeof receipt === 'string' && receipt.length > 0 ? receipt : undefined;
+}
+
+interface NormalizedActivityOptions {
+  readonly settleMs: number;
+  readonly idleMs: number;
+  readonly deadlineMs: number;
+  readonly includeSelf: boolean;
+}
+
+function normalizeOptions(options: ActivityOptions): NormalizedActivityOptions {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw unboundedSubscription('f.on() requires idle and deadline bounds');
+  }
+  const value = options as unknown as Record<string, unknown>;
+  const allowed = new Set(['settle', 'idle', 'deadline', 'includeSelf']);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new AuthoredFlowExecutionError('unbounded_subscription', `f.on() has unknown option ${JSON.stringify(key)}`);
+  }
+  if (!Object.hasOwn(value, 'idle') || !Object.hasOwn(value, 'deadline')) {
+    throw unboundedSubscription('f.on() requires both idle and deadline bounds');
+  }
+  if (value['includeSelf'] !== undefined && typeof value['includeSelf'] !== 'boolean') {
+    throw new AuthoredFlowExecutionError('unbounded_subscription', 'f.on() includeSelf must be a boolean');
+  }
+  return Object.freeze({
+    settleMs: parseDuration(value['settle'] as ActivityDuration | undefined, 'settle', true),
+    idleMs: parseDuration(value['idle'] as ActivityDuration, 'idle', false),
+    deadlineMs: parseDuration(value['deadline'] as ActivityDuration, 'deadline', false),
+    includeSelf: value['includeSelf'] === true,
+  });
+}
+
+function parseDuration(value: ActivityDuration | undefined, field: string, zeroAllowed: boolean): number {
+  if (value === undefined && zeroAllowed) return 0;
+  let milliseconds: number;
+  if (typeof value === 'number') milliseconds = value;
+  else if (typeof value === 'string') {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value);
+    const units: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+    const unit = match?.[2];
+    milliseconds = match === null || unit === undefined ? NaN : Math.round(Number(match[1]) * units[unit]!);
+  } else milliseconds = NaN;
+  if (!Number.isSafeInteger(milliseconds) || milliseconds < 0 || (!zeroAllowed && milliseconds === 0)) {
+    throw new AuthoredFlowExecutionError(
+      'unbounded_subscription',
+      `f.on() ${field} must be ${zeroAllowed ? 'a non-negative' : 'a positive'} whole number of milliseconds or a duration such as "72h"`,
+    );
+  }
+  return milliseconds;
+}
+
+function unboundedSubscription(message: string): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError('unbounded_subscription', message);
+}
+
+/** Decode the wire result at the journal boundary so malformed wakes fail closed. */
+export function decodeWake(value: SubscriptionNextResult): Wake {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidWake();
+  if (value.kind === 'idle') return Object.freeze({ kind: 'idle' });
+  if (value.kind === 'events') {
+    if (!Array.isArray(value.events) || !isOffset(value.offset) || !value.events.every(isEventFrame)) return invalidWake();
+    return Object.freeze({ kind: 'events', events: Object.freeze([...value.events]) as readonly EventFrame[], offset: value.offset });
+  }
+  if (value.kind === 'deadline') {
+    if (value.pending !== null && !isPending(value.pending)) return invalidWake();
+    return Object.freeze({ kind: 'deadline', pending: value.pending === null ? null : Object.freeze({ ...value.pending }) });
+  }
+  if (value.kind === 'overflow') {
+    if (!isOffset(value.retained) || !isOffset(value.bytes) || !isOffset(value.from)) return invalidWake();
+    return Object.freeze({ kind: 'overflow', retained: value.retained, bytes: value.bytes, from: value.from });
+  }
+  return invalidWake();
+}
+
+function isEventFrame(value: unknown): value is EventFrame {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && typeof (value as { type?: unknown }).type === 'string';
+}
+
+function isPending(value: unknown): value is { from: number; to: number } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && isOffset((value as { from?: unknown }).from)
+    && isOffset((value as { to?: unknown }).to);
+}
+
+function isOffset(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function invalidWake(): never {
+  throw new AuthoredFlowExecutionError('journal_protocol_violation', 'subscription.next returned an invalid wake result');
+}

package/src/authored-child-run.ts

@@ -0,0 +1,138 @@
+import { delay, LEASE_SWEEP_GRACE_MS } from './cli/run.js';
+import type { JournalClient } from './journal-client.js';
+import type { RunGetResult, RunStatus } from './protocol.js';
+
+/** One `journal.read` page; the kernel caps an unbounded read at 100 entries. */
+const PAGE = 1_000;
+const POLL_MS = 50;
+// A run between two of its own actions can report `running` with nothing in
+// flight for a moment (a wait just completed, the next attempt not yet
+// journaled). The same bound `classifyOutcome` gives that window (#179).
+const MAX_IDLE_POLLS = 40;
+
+/**
+ * Every entry of a child run's journal, paged.
+ *
+ * A single unbounded read returns the first 100 entries only, and a reader
+ * that needs the LAST completion of a step cannot stop at a page boundary.
+ * A short page is the end of the journal.
+ */
+export async function readChildJournal(journal: JournalClient, runId: string): Promise<unknown[]> {
+  const all: unknown[] = [];
+  let fromSeq = 1;
+  while (true) {
+    const { entries } = await journal.journalRead(runId, fromSeq, PAGE);
+    all.push(...entries);
+    if (entries.length < PAGE) return all;
+    const last = entries.at(-1) as { seq?: unknown } | undefined;
+    if (typeof last?.seq !== 'number' || !Number.isSafeInteger(last.seq) || last.seq < fromSeq) {
+      throw new Error(`invalid journal sequence reading child run "${runId}"`);
+    }
+    fromSeq = last.seq + 1;
+  }
+}
+
+/**
+ * Wait until an authored operation's child run is terminal, and say whether
+ * it got there.
+ *
+ * A child adopted through its admission key is not necessarily finished: on
+ * `flows resume` of a root whose daemon survived, `run.start` returns the
+ * existing child's CURRENT outcome without driving it, so the child may still
+ * be executing an attempt, or sleeping out a retry backoff, on the request
+ * that originally started it. Reading its journal then judges a history that
+ * is still being written.
+ *
+ * The wait is read-only on purpose: it never resumes the child. The kernel
+ * drives a deterministic attempt inline on the request that started it, and a
+ * second driver would presume that attempt dead and run the command again.
+ *
+ * Bounded by the child's own journaled deadlines, never a fixed one: a running
+ * attempt by its lease (renewed as the lease renews) plus the kernel's
+ * lease-sweep grace, a backoff by the `sleep.until` it journaled (once that
+ * wake has passed, by the settling window). With nothing in flight, only the
+ * short settling window above; a child parked on a worker
+ * returns at once. Either way the caller gets the status and decides.
+ */
+export async function waitForTerminalChildRun(
+  journal: JournalClient,
+  runId: string,
+  signal?: AbortSignal,
+): Promise<RunStatus> {
+  let idlePolls = 0;
+  while (true) {
+    if (signal?.aborted === true) throw new Error(`waiting for child run "${runId}" was canceled`);
+    const snapshot = await journal.runGet(runId);
+    if (snapshot.status === 'completed' || snapshot.status === 'failed') return snapshot.status;
+    const inFlight = await inFlightDeadline(journal, runId, snapshot);
+    if (inFlight === 'parked') return snapshot.status;
+    const remainingMs = inFlight === undefined ? 0 : inFlight.deadlineMs + inFlight.graceMs - Date.now();
+    if (inFlight !== undefined && remainingMs > 0) {
+      idlePolls = 0;
+      await delay(Math.min(POLL_MS, remainingMs), signal);
+      continue;
+    }
+    // Only a lease past its sweep grace is proof nothing is running the
+    // attempt. An elapsed retry wake is the kernel's normal transition to the
+    // next attempt — its driver may be folding the timer right now — so it is
+    // re-polled inside the settling window like any other in-between state.
+    if (inFlight?.what === 'lease') {
+      throw new Error(`child run "${runId}" step "${inFlight.stepId}" passed its lease`
+        + ` (${inFlight.deadlineMs}) without reaching a terminal state`);
+    }
+    if (idlePolls >= MAX_IDLE_POLLS) return snapshot.status;
+    idlePolls += 1;
+    await delay(POLL_MS, signal);
+  }
+}
+
+interface InFlight {
+  stepId: string;
+  what: 'lease' | 'retry backoff';
+  deadlineMs: number;
+  graceMs: number;
+}
+
+/**
+ * What the child is waiting on, and until when; `parked` when it is waiting
+ * on nothing this process can wait out.
+ *
+ * A worker-typed (`agent`/`llm`) step that is runnable, or whose retry
+ * backoff has elapsed, with no attempt running, needs a worker — or the
+ * `run.resume` a caller like `classifyOutcome` issues — to move. That is the
+ * park `classifyOutcome` reports, and waiting on it would only delay the same
+ * answer. A deterministic step in that state is the kernel between two of its
+ * own actions, which the caller's settling window covers.
+ */
+async function inFlightDeadline(
+  journal: JournalClient,
+  runId: string,
+  snapshot: RunGetResult,
+): Promise<InFlight | 'parked' | undefined> {
+  const steps = Object.entries(snapshot.steps);
+  const running = steps.find(([, step]) => step.state === 'running' && step.lease_deadline_ms !== undefined);
+  if (running !== undefined) {
+    return {
+      stepId: running[0], what: 'lease', deadlineMs: running[1].lease_deadline_ms!, graceMs: LEASE_SWEEP_GRACE_MS,
+    };
+  }
+  const worker = ([, step]: [string, { type: string }]) => step.type !== 'deterministic';
+  if (steps.some(entry => worker(entry) && entry[1].state === 'runnable')) return 'parked';
+  const backoff = steps.find(([, step]) => step.state === 'backoff');
+  if (backoff === undefined) return undefined;
+  const wakeAtMs = (await readChildJournal(journal, runId))
+    .map(entry => retryWake(entry, backoff[0]))
+    .filter((value): value is number => value !== undefined)
+    .at(-1);
+  if (wakeAtMs === undefined) return undefined;
+  if (wakeAtMs <= Date.now()) return worker(backoff) ? 'parked' : undefined;
+  return { stepId: backoff[0], what: 'retry backoff', deadlineMs: wakeAtMs, graceMs: 0 };
+}
+
+function retryWake(entry: unknown, stepId: string): number | undefined {
+  if (typeof entry !== 'object' || entry === null) return undefined;
+  const { entry_type: type, step_id: step, payload } = entry as Record<string, unknown>;
+  if (type !== 'sleep.until' || step !== stepId || typeof payload !== 'object' || payload === null) return undefined;
+  const wakeAtMs = (payload as Record<string, unknown>)['wake_at_ms'];
+  return typeof wakeAtMs === 'number' && Number.isFinite(wakeAtMs) ? wakeAtMs : undefined;
+}

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

@@ -11,11 +11,18 @@ export type AuthoredFlowExecutionErrorCode =
   | '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'
@@ -36,6 +43,9 @@ export type AuthoredFlowExecutionErrorCode =
   | 'unsettled_derived_work'
   | 'unsupported_promise_lifecycle'
   | 'unsupported_workspace_permission'
+  | 'unbounded_subscription'
+  | 'activity_closed'
+  | 'subscription_suspended'
   | 'unawaited_step'
   | 'unsupported_verb';
 
@@ -73,12 +83,38 @@ export class AuthoredFlowExecutionError extends Error {
      * Node-child error frame — can forward it instead of dropping it.
      */
     readonly details?: StepFailedDetails,
+    readonly suspension?: AuthoredFlowSuspension,
   ) {
     super(`${code}: ${message}`);
     this.name = 'AuthoredFlowExecutionError';
   }
 }
 
+/** 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;