@relayflows/sdk 2.0.10 → 2.0.12

package/src/agent-relay-transport.ts

@@ -1,187 +1,273 @@
-/**
- * Agent-relay HTTP transport for f.agent step dispatch (flows#385).
- *
- * The SDK's default agent path is a direct `child_process.spawn(cli, ...)`
- * in worker-cli.ts. That is unobservable — you cannot DM the spawned agent
- * mid-flight, and every ecosystem tool that wants to steer or watch it
- * ends up shelling out to the `agent-relay` CLI, which is fragile.
- *
- * This module speaks to agent-relay via structured HTTP: the same call
- * shape the `mcp__agent-relay__spawn` MCP tool posts. The SDK becomes a
- * first-class agent-relay participant, registered under a derived agent
- * name a caller can DM against.
- *
- * Scope: spawn + close. Streaming inbox and observation are follow-ups.
- */
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { claimRelayTask } from "./agent-relay-state.js";
+import { canonicalize } from "./canonical.js";
+import {
+  isRecord,
+  nonempty,
+  readTaskReceipt,
+  type RelayTaskReceipt,
+} from "./agent-relay-receipt.js";
 
-export type AgentTransport = 'direct' | 'relay';
-
-export interface AgentRelaySpawnRequest {
-  /** Registered agent name in the workspace. */
-  name: string;
-  /** CLI to launch. */
-  cli: 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'grok' | 'opencode';
-  /** Initial task instructions. */
+export type AgentTransport = "direct" | "relay";
+export interface AgentRelayTaskRequest {
+  cli: string;
   task: string;
-  /** Optional model powering the worker. */
   model?: string;
-  /** Optional working directory for the spawned worker process. */
   worker_cwd?: string;
-  /** Optional target fleet node name. */
-  target_node?: string;
-  /** Declared objective for workforce reporting. */
-  objective?: string;
-  /** Declared role for workforce reporting. */
-  role?: string;
-  /** Declared project for workforce reporting. */
-  project?: string;
-  /** Declared workstream for workforce reporting. */
-  workstream?: string;
+  result_schema?: unknown;
+  runId: string;
+  stepId: string;
+  idempotencyKey: string;
+  dataDir: string;
+  /** Engine task contract ceiling; bounded independently of the renewing lease. */
+  timeoutMs?: number;
 }
-
 export interface AgentRelayEnv {
-  /** `RELAY_BASE_URL` env; defaults to https://cast.agentrelay.com. */
   baseUrl?: string;
-  /** `RELAY_API_KEY` env (rk_live_...). Required. */
-  apiKey?: string;
-  /** `RELAY_DEFAULT_WORKSPACE` env; workspace scoping for the spawn. */
-  workspaceId?: string;
-  /** Optional bearer token for the individual agent identity, if pre-registered. */
   agentToken?: string;
 }
-
-export interface AgentSpawnHandle {
-  /** Registered agent name in the workspace — DM this to steer. */
-  readonly registeredName: string;
-  /** Invocation id returned by relay; use for status polling. */
-  readonly invocationId: string;
-  /** Best-effort deregistration/notification. */
-  close(): Promise<void>;
-}
-
 export class AgentRelayTransportError extends Error {
-  constructor(message: string, public readonly cause?: unknown) {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
     super(message);
-    this.name = 'AgentRelayTransportError';
+    this.name = "AgentRelayTransportError";
   }
 }
-
-/**
- * Read the same env the relay MCP already consumes. Explicit override wins.
- * Missing RELAY_API_KEY refuses immediately — the transport cannot proceed
- * unauthenticated and the direct-spawn fallback is a separate decision.
- */
-export function readAgentRelayEnv(env: NodeJS.ProcessEnv = process.env): Required<Pick<AgentRelayEnv, 'baseUrl' | 'apiKey'>> & AgentRelayEnv {
-  const baseUrl = env['RELAY_BASE_URL']?.trim() || 'https://cast.agentrelay.com';
-  const apiKey = env['RELAY_API_KEY']?.trim();
-  if (!apiKey) {
+export function readAgentRelayEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Required<AgentRelayEnv> {
+  const agentToken = env.RELAY_AGENT_TOKEN?.trim();
+  if (!agentToken)
     throw new AgentRelayTransportError(
-      'agent-relay transport requires RELAY_API_KEY in the environment; falling back to direct transport is the caller\'s responsibility.',
+      "Relay task transport requires a pre-provisioned RELAY_AGENT_TOKEN.",
     );
-  }
   return {
-    baseUrl,
-    apiKey,
-    workspaceId: env['RELAY_DEFAULT_WORKSPACE']?.trim() || undefined,
-    agentToken: env['RELAY_AGENT_TOKEN']?.trim() || undefined,
+    baseUrl: env.RELAY_BASE_URL?.trim() || "https://cast.agentrelay.com",
+    agentToken,
   };
 }
 
-/**
- * Spawn a worker via agent-relay HTTP. The endpoint mirrors what the
- * `mcp__agent-relay__spawn` MCP tool wraps — a POST that requests a fleet
- * node dispatch. Returns a handle keyed on the registered agent name.
- *
- * The `fetch` argument is injected so tests can mock the transport without
- * hitting the network.
- */
-export async function agentRelaySpawn(
-  request: AgentRelaySpawnRequest,
-  env: AgentRelayEnv & { fetch?: typeof fetch } = {},
-): Promise<AgentSpawnHandle> {
-  // Only fall back to process.env if the caller didn't supply the required
-  // fields directly. Tests pass { apiKey, fetch } inline; they shouldn't need
-  // to also set RELAY_API_KEY in the runner env.
-  const fromEnv: Partial<AgentRelayEnv> = env.apiKey
-    ? { baseUrl: env.baseUrl || 'https://cast.agentrelay.com' }
-    : readAgentRelayEnv();
-  const resolved = { ...fromEnv, ...env };
-  const url = new URL('/api/v1/agents/spawn', resolved.baseUrl).toString();
-  const doFetch: typeof fetch = env.fetch ?? (globalThis as typeof globalThis & { fetch: typeof fetch }).fetch;
-  if (typeof doFetch !== 'function') {
-    throw new AgentRelayTransportError('global fetch is unavailable; provide { fetch } explicitly.');
-  }
-  const headers: Record<string, string> = {
-    'content-type': 'application/json',
-    'authorization': `Bearer ${resolved.apiKey}`,
-  };
-  if (resolved.workspaceId !== undefined) headers['x-relay-workspace'] = resolved.workspaceId;
-  if (resolved.agentToken !== undefined) headers['x-relay-agent-token'] = resolved.agentToken;
-
-  let response: Response;
-  try {
-    response = await doFetch(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(request),
-    });
-  } catch (cause) {
-    throw new AgentRelayTransportError(
-      `agent-relay spawn network error at ${url}: ${(cause as Error).message ?? String(cause)}`,
-      cause,
-    );
-  }
-
-  if (response.status < 200 || response.status >= 300) {
-    let body: string;
-    try { body = (await response.text()).slice(0, 512); } catch { body = '<no body>'; }
-    throw new AgentRelayTransportError(
-      `agent-relay spawn refused with status ${response.status}: ${body}`,
-    );
-  }
-
-  let json: { invocation?: { invocationId?: string; input?: { name?: string } } };
-  try { json = await response.json() as typeof json; } catch (cause) {
+/** Exact Relaycast #436 HTTP contract. Only terminal GET receipts can return. */
+export async function runAgentRelayTask(
+  request: AgentRelayTaskRequest,
+  options: AgentRelayEnv & {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    pollMs?: number;
+  } = {},
+): Promise<RelayTaskReceipt> {
+  const env = options.agentToken
+    ? {
+        baseUrl: options.baseUrl || "https://cast.agentrelay.com",
+        agentToken: options.agentToken,
+      }
+    : { ...readAgentRelayEnv(), ...options };
+  const base = new URL(env.baseUrl!);
+  if (
+    base.username ||
+    base.password ||
+    base.search ||
+    base.hash ||
+    base.pathname !== "/" ||
+    !["https:", "http:"].includes(base.protocol)
+  )
+    throw new AgentRelayTransportError("Invalid Relay task base URL");
+  const loopback =
+    base.hostname === "[::1]" ||
+    (isIP(base.hostname) === 4 && base.hostname.startsWith("127."));
+  if (base.protocol !== "https:" && !loopback) {
     throw new AgentRelayTransportError(
-      'agent-relay spawn response was not JSON',
-      cause,
+      "Relay task credentials require HTTPS outside literal loopback addresses",
     );
   }
-  const invocationId = json.invocation?.invocationId;
-  const registeredName = json.invocation?.input?.name ?? request.name;
-  if (typeof invocationId !== 'string' || invocationId.length === 0) {
+  const baseUrl = base.origin;
+  const timeoutMs = request.timeoutMs ?? 86_400_000;
+  if (
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs < 1 ||
+    timeoutMs > 86_400_000 ||
+    ![
+      request.runId,
+      request.stepId,
+      request.idempotencyKey,
+      request.dataDir,
+      request.cli,
+    ].every(nonempty)
+  ) {
     throw new AgentRelayTransportError(
-      'agent-relay spawn response missing invocation.invocationId',
+      "Relay task requires durable dispatch identity and a valid deadline",
     );
   }
-
-  return {
-    registeredName,
-    invocationId,
-    async close(): Promise<void> {
-      // Best-effort: post to /api/v1/invocations/<id>/close if defined server-side;
-      // no throw on error because the invocation may already be terminal.
-      const closeUrl = new URL(`/api/v1/invocations/${encodeURIComponent(invocationId)}/close`, resolved.baseUrl).toString();
+  const pollMs = options.pollMs ?? 1000;
+  if (!Number.isFinite(pollMs) || pollMs < 1)
+    throw new AgentRelayTransportError("Invalid Relay task polling interval");
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const outer = options.signal ?? new AbortController().signal;
+  let deadline = Date.now() + timeoutMs + 30_000;
+  let missingDeadline = Date.now() + 30_000;
+  async function http(
+    path: string,
+    body?: unknown,
+  ): Promise<Record<string, unknown>> {
+    for (;;) {
+      outer.throwIfAborted();
+      if (Date.now() >= deadline)
+        throw new AgentRelayTransportError(
+          "Relay task status unavailable before its reconciliation deadline",
+        );
+      const bounded = AbortSignal.any([
+        outer,
+        AbortSignal.timeout(
+          Math.min(15_000, Math.max(1, deadline - Date.now())),
+        ),
+      ]);
+      let response: Response | undefined;
+      let value: unknown;
       try {
-        await doFetch(closeUrl, {
-          method: 'POST',
-          headers,
-          body: JSON.stringify({ reason: 'sdk_transport_close' }),
+        response = await doFetch(new URL(path, baseUrl), {
+          method: body === undefined ? "GET" : "POST",
+          redirect: "error",
+          signal: bounded,
+          headers: {
+            authorization: `Bearer ${env.agentToken}`,
+            "content-type": "application/json",
+            ...(body === undefined
+              ? {}
+              : { "Idempotency-Key": request.idempotencyKey }),
+          },
+          ...(body === undefined ? {} : { body: canonicalize(body) }),
         });
-      } catch {
-        // Deliberate: close is advisory in this minimum-viable slice.
+        if (
+          response.status === 404 &&
+          body === undefined &&
+          path.includes("/invocations/")
+        ) {
+          if (Date.now() >= missingDeadline)
+            throw new AgentRelayTransportError(
+              "Relay task dispatch remains unconfirmed; no repeat POST is permitted",
+            );
+        } else if (
+          !response.ok &&
+          response.status !== 429 &&
+          response.status < 500
+        ) {
+          // Never copy untrusted response bodies, URLs, or tokens into diagnostics.
+          throw new AgentRelayTransportError(
+            `Relay task request refused with HTTP ${response.status}`,
+          );
+        }
+        if (response.ok) value = await response.json();
+        if (body !== undefined && !response.ok) return {}; // ambiguous POST: GET only below
+      } catch (error) {
+        outer.throwIfAborted();
+        if (error instanceof AgentRelayTransportError) throw error;
+        if (body !== undefined) return {}; // response loss or invalid JSON never causes another POST
+        if (response?.ok && !bounded.aborted)
+          throw new AgentRelayTransportError(
+            "Relay task response was not valid JSON",
+          );
+      }
+      outer.throwIfAborted();
+      if (response?.ok && value !== undefined) {
+        if (!isRecord(value) || value.ok !== true || !isRecord(value.data))
+          throw new AgentRelayTransportError(
+            "Relay task response has an invalid data envelope",
+          );
+        return value.data;
       }
+      await delay(pollMs, undefined, { signal: outer });
+    }
+  }
+  // Resolving the agent is read-only. Pin identity before any invocation so a
+  // restarted runner cannot create a second task using another caller's key.
+  const agent = await http("/v1/agent");
+  if (!nonempty(agent.id))
+    throw new AgentRelayTransportError("Relay task caller identity is missing");
+  if (!nonempty(agent.workspace_id))
+    throw new AgentRelayTransportError(
+      "Relay task workspace identity is missing",
+    );
+  // Pinned action-invoke-v1 identity contract from Relaycast #436.
+  const invocationId =
+    "inv_idem_" +
+    createHash("sha256")
+      .update(
+        [
+          "action-invoke-v1",
+          agent.workspace_id,
+          agent.id,
+          "task.run",
+          request.idempotencyKey,
+        ].join("\0"),
+      )
+      .digest("hex");
+  const input = {
+    cli: request.cli,
+    task: request.task,
+    ...(request.model === undefined ? {} : { model: request.model }),
+    ...(request.worker_cwd === undefined
+      ? {}
+      : { worker_cwd: request.worker_cwd }),
+    ...(request.result_schema === undefined
+      ? {}
+      : { result_schema: request.result_schema }),
+    task_context: {
+      run_id: request.runId,
+      step_id: request.stepId,
+      dispatch_id: request.idempotencyKey,
+      timeout_ms: timeoutMs,
     },
   };
-}
-
-/**
- * Derive a workspace-unique agent name from a run identity + step id. The
- * result is stable across replays of the same step so DMs can be addressed
- * even during retries.
- */
-export function deriveAgentName(runId: string, stepId: string): string {
-  // Keep readable + collision-safe: prefix with 'flow-' and use lower-kebab.
-  const clean = (s: string): string => s.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
-  return `flow-${clean(runId)}-${clean(stepId)}`.slice(0, 96);
+  const { claim, created } = await claimRelayTask(request.dataDir, {
+    version: 1,
+    baseUrl,
+    callerId: agent.id,
+    workspaceId: agent.workspace_id,
+    invocationId,
+    runId: request.runId,
+    stepId: request.stepId,
+    idempotencyKey: request.idempotencyKey,
+    input,
+    startedAt: Date.now(),
+  });
+  // A restarted runner may recover a terminal receipt after the task deadline.
+  // Give that read one bounded window; never reopen or extend the remote task.
+  deadline = Math.max(
+    claim.startedAt + timeoutMs + 30_000,
+    Date.now() + 15_000,
+  );
+  missingDeadline = claim.startedAt + 30_000;
+  if (created) {
+    const ack = await http("/v1/actions/task.run/invoke", { input });
+    if (
+      Object.keys(ack).length &&
+      (ack.invocation_id !== invocationId ||
+        ack.action_name !== "task.run" ||
+        canonicalize(ack.input) !== canonicalize(input))
+    ) {
+      throw new AgentRelayTransportError(
+        "Relay task acknowledgment has mismatched invocation or input",
+      );
+    }
+  }
+  let previous: RelayTaskReceipt | undefined;
+  for (;;) {
+    const value = await http(
+      `/v1/actions/task.run/invocations/${encodeURIComponent(invocationId)}`,
+    );
+    if (value.caller_id !== agent.id)
+      throw new AgentRelayTransportError(
+        "Relay task receipt belongs to another caller",
+      );
+    const receipt = readTaskReceipt(value, invocationId, input, previous);
+    outer.throwIfAborted();
+    if (receipt.status === "completed" || receipt.status === "failed")
+      return receipt;
+    previous = receipt;
+    await delay(pollMs, undefined, { signal: outer });
+  }
 }

package/src/authored-admission.ts

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+
+/** Stable retry identity for one operation in one durable authored root. */
+export function authoredChildAdmissionKey(
+  rootRunId: string | undefined,
+  stepId: string,
+): string | undefined {
+  if (rootRunId === undefined) return undefined;
+  return `authored-child:${createHash('sha256').update(`${rootRunId}\0${stepId}`).digest('hex')}`;
+}
+
+/** Stable local worker surface for retries of one caller-owned root start. */
+export function authoredLocalAgentStream(admissionIdentity: string): string {
+  return `local-agent-${createHash('sha256')
+    .update(`authored-root-worker\0${admissionIdentity}`)
+    .digest('hex')}`;
+}

package/src/authored-budget.ts

@@ -20,8 +20,9 @@ export class AuthoredBudget {
     }
   }
 
-  async execute<T>(journal: JournalClient, spec: KernelRunSpec, consume: (outcome: RunOutcome) => Promise<T>): Promise<T> {
-    if (this.limit === undefined) return consume(await journal.runStart(spec));
+  async execute<T>(journal: JournalClient, spec: KernelRunSpec,
+    consume: (outcome: RunOutcome) => Promise<T>, admissionKey?: string): Promise<T> {
+    if (this.limit === undefined) return consume(await journal.runStart(spec, undefined, admissionKey));
     const previous = this.tail;
     let release!: () => void;
     this.tail = new Promise<void>(resolve => { release = resolve; });
@@ -38,7 +39,7 @@ export class AuthoredBudget {
         tokens_in: exactNumber(total.input), tokens_out: exactNumber(total.output),
         dollars: `${total.micro / 1_000_000n}.${String(total.micro % 1_000_000n).padStart(6, '0')}`,
         wallclock_ms: exactNumber(total.ms), ...(this.limit.window === 'day' && day !== undefined ? { day } : {}),
-      } } });
+      } } }, undefined, admissionKey);
       try {
         if (outcome.completion_reason === 'budget_exceeded') throw new AuthoredFlowExecutionError('step_failed', 'Flow budget exceeded before the next step.', 'budget_exceeded', outcome.run_id);
         return await consume(outcome);

package/src/authored-flow-error.ts

@@ -9,7 +9,6 @@ export type AuthoredFlowExecutionErrorCode =
   | 'helper_slack.credential_missing'
   | 'helper_slack.mount_required'
   | 'budget_syntax_invalid'
-  | 'budget_missing_price'
   | 'agent_cli_unresolved'
   | 'agent_parked'
   | 'llm_cli_unresolved'

package/src/authored-flow-executor.ts

@@ -1,3 +1,4 @@
+import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 import { pluginHelpers } from './plugin-loader.js';
 import { runPluginEffect } from './authored-plugin-effect.js';
 import { randomUUID } from 'node:crypto';
@@ -71,7 +72,16 @@ export interface AuthoredFlowJournalStep {
   readonly completionReason: ProtocolCompletionReason;
 }
 
+export interface AuthoredExecutionRuntime {
+  readonly kind: 'node';
+  readonly version: string;
+  readonly executableSha256: string;
+  readonly payloadSha256: string;
+}
+
 export interface AuthoredFlowExecutionResult {
+  readonly executionRuntime?: AuthoredExecutionRuntime;
+  readonly rootRunId?: string;
   readonly name: string;
   readonly completionReason: FlowCompletionReason;
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
@@ -122,6 +132,8 @@ export interface ExecuteAuthoredFlowOptions {
   readonly onWait?: RunLifecycleOptions['onWait'];
   readonly onProgress?: (event: ProgressEvent) => void;
   readonly localAgentStream?: string;
+  /** Durable kernel root that owns this body's child admission identities. */
+  readonly rootRunId?: string;
 }
 
 export async function executeAuthoredFlow<Input = undefined>(
@@ -130,6 +142,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   input?: Input,
   options: ExecuteAuthoredFlowOptions = {},
 ): Promise<AuthoredFlowExecutionResult> {
+  assertAuthoredPromiseHooks();
   const getDefinition = options.getDefinition ?? getAuthoredFlowDefinition;
   const localAgentStream = options.localAgentStream;
   const onProgress = options.onProgress;
@@ -173,9 +186,14 @@ export async function executeAuthoredFlow<Input = undefined>(
   let nextStep = 1;
   let requestedCompletion: FlowCompletionReason | undefined;
 
-  const lowerDeterministic = authoredDeterministicRunner(definition.name, journal, journalSteps, budget);
+  const lowerDeterministic = authoredDeterministicRunner(
+    definition.name, journal, journalSteps, budget, options.rootRunId,
+  );
 
-  const worker = authoredWorkerRunner(definition, journal, flowPath, journalSteps, waitOptions, localAgentStream, budget, definition.header.budget);
+  const worker = authoredWorkerRunner(
+    definition, journal, flowPath, journalSteps, waitOptions,
+    localAgentStream, budget, definition.header.budget, options.rootRunId,
+  );
 
   function llmOperation(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
   function llmOperation(prompt: string, options: LlmOptions): Step<unknown>;
@@ -205,7 +223,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     return trackStep(authoredSteps, llmOp);
   }
 
-  const slackRun = randomUUID();
+  const slackRun = options.rootRunId ?? randomUUID();
   function slackOperation<T>(call: SlackCall): Step<T> {
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
     const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
@@ -215,7 +233,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion),
       async () => {
         const receipt = await runHelperEffect(journal, definition.name, id, snapshot,
-          options.dataDir ?? dirname(journal.socketPath), journalSteps);
+          options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId);
         return (call.verb === 'react' ? undefined : receipt) as T;
       },
       lifecycle,
@@ -231,7 +249,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       return trackStep(authoredSteps, new AuthoredFlowOperation<T>(id, verb,
         () => assertOperationAllowed(verb, definition.name, requestedCompletion),
         async () => await runHelperEffect(journal, definition.name, id, snapshot,
-          options.dataDir ?? dirname(journal.socketPath), journalSteps) as T,
+          options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId) as T,
         lifecycle));
     }),
     slack: {
@@ -247,7 +265,7 @@ export async function executeAuthoredFlow<Input = undefined>(
         id, 'mcp',
         () => assertOperationAllowed('mcp', definition.name, requestedCompletion),
         () => runMcpEffect(journal, definition.name, id, server, tool, args,
-          known, checkedMcp.servers[server]!, journalSteps),
+          known, checkedMcp.servers[server]!, journalSteps, options.rootRunId),
         lifecycle,
       ));
     }),
@@ -327,7 +345,8 @@ export async function executeAuthoredFlow<Input = undefined>(
     const id = `plugin-${nextStep++}`;
     return trackStep(authoredSteps, new AuthoredFlowOperation(
       id, label, () => assertOperationAllowed(label, definition.name, requestedCompletion),
-      () => runPluginEffect(journal, definition.name, id, plugin, verb, args, journalSteps, budget),
+      () => runPluginEffect(journal, definition.name, id, plugin, verb, args,
+        journalSteps, budget, options.rootRunId),
       lifecycle,
     ));
   }));
@@ -387,6 +406,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   await lowerDeterministic(`complete-${nextStep}`, requestedCompletion === 'needs_human'
     ? `printf '%s' '{"completionReason":"needs_human"}'` : ':', true);
   return Object.freeze({
+    ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
     name: definition.name,
     completionReason: requestedCompletion,
     journalSteps: Object.freeze([...journalSteps]),