@llblab/pi-actors 0.42.0 → 0.42.1

package/lib/inspector-overlay.ts

@@ -69,7 +69,8 @@ export class ActorInspectorOverlay {
   private detailScroll = 0;
   private detailTurn?: Inspector.ActorInspectorTurnItem;
   private feedback?: ActorInspectorOverlayActionResult;
-  private killConfirmation?: { run: string; runInstanceId: string };
+  private killConfirmation?: { run: string; runInstanceId: string; status: string };
+  private killDialogChoice: "cancel" | "kill" = "cancel";
   private readonly readKeys = new Set<string>();
   private focus: "runs" | "tabs" | "recipe" | "list" | "detail" | "select" = "tabs";
   private filterControlIndex = 0;
@@ -105,11 +106,21 @@ export class ActorInspectorOverlay {
       return;
     }
     if (this.killConfirmation) {
-      if (matchesKey(data, "escape") || data.toLowerCase() === "n") {
-        this.feedback = { ok: false, message: "Kill cancelled." };
-        this.killConfirmation = undefined;
-      } else if (matchesKey(data, "return") || data.toLowerCase() === "y") {
+      const key = data.toLowerCase();
+      if (matchesKey(data, "escape") || key === "n") {
+        this.cancelKill();
+      } else if (
+        matchesKey(data, "left") ||
+        matchesKey(data, "right") ||
+        matchesKey(data, "tab")
+      ) {
+        this.killDialogChoice =
+          this.killDialogChoice === "cancel" ? "kill" : "cancel";
+      } else if (key === "y") {
         this.confirmKill();
+      } else if (matchesKey(data, "return")) {
+        if (this.killDialogChoice === "kill") this.confirmKill();
+        else this.cancelKill();
       }
       this.tui.requestRender();
       return;
@@ -215,6 +226,8 @@ export class ActorInspectorOverlay {
     this.ensureSelectedRun(this.runs());
     const safeWidth = Math.max(24, width);
     const innerWidth = Math.max(1, safeWidth - 2);
+    if (this.killConfirmation)
+      return this.renderKillDialog(safeWidth, innerWidth);
     const lines: string[] = [];
     lines.push(this.border("╭", " Actor Inspector ", "╮", innerWidth));
     lines.push(this.row(this.renderRunControl(), innerWidth));
@@ -261,9 +274,7 @@ export class ActorInspectorOverlay {
       );
     } else lines.push(this.border("├", "", "┤", innerWidth));
     this.contentStripeIndices = [];
-    const baseContent = this.killConfirmation
-      ? this.renderKillConfirmation()
-      : this.detailOpen
+    const baseContent = this.detailOpen
         ? this.renderDetail(innerWidth)
         : this.selectedRun
           ? this.renderTimeline(innerWidth)
@@ -392,12 +403,21 @@ export class ActorInspectorOverlay {
     this.killConfirmation = {
       run: run.run,
       runInstanceId: run.runInstanceId,
+      status: run.status,
     };
+    this.killDialogChoice = "cancel";
+  }
+
+  private cancelKill(): void {
+    this.feedback = { ok: false, message: "Kill cancelled." };
+    this.killConfirmation = undefined;
+    this.killDialogChoice = "cancel";
   }
 
   private confirmKill(): void {
     const confirmation = this.killConfirmation;
     this.killConfirmation = undefined;
+    this.killDialogChoice = "cancel";
     if (!confirmation || !this.killRun) {
       this.feedback = { ok: false, message: "Kill unavailable in this Inspector." };
       return;
@@ -416,14 +436,40 @@ export class ActorInspectorOverlay {
     }
   }
 
-  private renderKillConfirmation(): string[] {
-    return [
-      this.theme.fg(
-        "error",
-        ` Kill running actor run:${this.killConfirmation?.run}?`,
-      ),
-      this.theme.fg("muted", " This sends canonical control.kill and cannot be undone."),
+  private renderKillDialog(_width: number, innerWidth: number): string[] {
+    const confirmation = this.killConfirmation!;
+    const totalRows = this.contentViewportRows() + 7;
+    const cancel = this.killDialogChoice === "cancel"
+      ? this.theme.bg("selectedBg", this.theme.fg("accent", "  Cancel  "))
+      : this.theme.fg("muted", "  Cancel  ");
+    const kill = this.killDialogChoice === "kill"
+      ? this.theme.bg("selectedBg", this.theme.fg("error", "  Kill actor  "))
+      : this.theme.fg("error", "  Kill actor  ");
+    const body = [
+      "",
+      this.theme.fg("error", "Kill this running actor?"),
+      "",
+      `${this.theme.fg("muted", "Run:")} ${this.theme.fg("accent", `run:${confirmation.run}`)}`,
+      `${this.theme.fg("muted", "Current status:")} ${this.theme.fg("warning", confirmation.status)}`,
+      "",
+      this.theme.fg("text", "This sends canonical control.kill."),
+      this.theme.fg("error", "The action is destructive and cannot be undone."),
+      "",
+      `${cancel}    ${kill}`,
+      "",
     ];
+    const lines = [this.border("╭", " Confirm Actor Kill ", "╮", innerWidth)];
+    const availableRows = Math.max(1, totalRows - 2);
+    const topPadding = Math.max(0, Math.floor((availableRows - body.length) / 2));
+    const dialogRows = [
+      ...Array.from({ length: topPadding }, () => ""),
+      ...body,
+    ].slice(0, availableRows);
+    while (dialogRows.length < availableRows) dialogRows.push("");
+    for (const line of dialogRows)
+      lines.push(this.row(this.center(line, innerWidth), innerWidth));
+    lines.push(this.border("╰", " ←→/tab choose · enter activate · esc cancel ", "╯", innerWidth));
+    return lines;
   }
 
   private listItemCount(): number {
@@ -1293,6 +1339,12 @@ export class ActorInspectorOverlay {
     return plain.slice(index);
   }
 
+  private center(content: string, width: number): string {
+    const contentWidth = visibleWidth(content);
+    const leading = Math.max(0, Math.floor((width - contentWidth) / 2));
+    return `${" ".repeat(leading)}${content}`;
+  }
+
   private fit(content: string, width: number): string {
     // A Component render entry must remain exactly one terminal row. Persisted
     // prompts, messages, and tool results may contain line breaks or tabs;

package/lib/inspector.ts

@@ -248,7 +248,7 @@ export function readActorInspectorTurns(stateDir: string): ActorInspectorTurnIte
             withFileTypes: true,
           })
           .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
-          .map((file) => path.join("sessions", entry.name, file.name))
+          .map((file) => path.posix.join("sessions", entry.name, file.name))
           .filter((file) => !recordedFiles.has(file));
         return files.length > 0
           ? [{ id: entry.name, session_files: files, stage: "subagent" }]

package/lib/observability.ts

@@ -5,9 +5,13 @@
  */
 
 import {
+  closeSync,
   existsSync,
+  fstatSync,
+  openSync,
   readdirSync,
   readFileSync,
+  readSync,
   watch,
   type FSWatcher,
 } from "node:fs";
@@ -41,6 +45,7 @@ export interface RunObservation {
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
+  launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
   notificationPolicy?: "normal" | "silent";
@@ -48,6 +53,7 @@ export interface RunObservation {
   terminalHandled?: boolean;
   retireWhen?: string;
   run: string;
+  semanticResult?: RunTerminalSemanticResult;
   tool?: string;
   stateDir?: string;
   status: RunObservedStatus;
@@ -162,6 +168,19 @@ export function deliverRunTransitionNotifications(
           transition.to,
         );
       }
+    } catch (error) {
+      if (transition.stateDir) {
+        AsyncRuns.recordRunTerminalDeliveryFailure(
+          transition.stateDir,
+          transition.to,
+          error,
+        );
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      sink.notify(
+        `Actor terminal delivery failed for run:${transition.run}: ${message.replaceAll(/\s+/g, " ").slice(0, 240)}`,
+        "error",
+      );
     } finally {
       inFlight.delete(key);
     }
@@ -420,12 +439,23 @@ export interface RunTransition {
   run: string;
   stateDir?: string;
   artifacts?: Record<string, string>;
+  launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
   recipeFile?: string;
   terminalHandled?: boolean;
   to: RunObservedStatus;
   tool?: string;
+  semanticResult?: RunTerminalSemanticResult;
+}
+
+export interface RunTerminalSemanticResult {
+  body?: string;
+  correlationId?: string;
+  metadata: Record<string, unknown>;
+  summary: string;
+  synthesized: boolean;
+  type: string;
 }
 
 export interface RunOutboxEvent {
@@ -504,15 +534,145 @@ function scanRunStateDirs(
   return result;
 }
 
+const TERMINAL_RESULT_BYTES = 8 * 1024;
+const TERMINAL_RESULT_CHARS = 4_000;
+
+function readBoundedStart(path: string): string {
+  if (!existsSync(path)) return "";
+  const fd = openSync(path, "r");
+  try {
+    const size = Math.min(fstatSync(fd).size, TERMINAL_RESULT_BYTES);
+    const buffer = Buffer.alloc(size);
+    const bytes = readSync(fd, buffer, 0, size, 0);
+    const text = buffer.subarray(0, bytes).toString("utf8").trim();
+    return text.length > TERMINAL_RESULT_CHARS
+      ? `${text.slice(0, TERMINAL_RESULT_CHARS - 1)}…`
+      : text;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function semanticBodyFromStdout(stateDir: string): string | undefined {
+  const text = readBoundedStart(join(stateDir, "stdout.log"));
+  if (!text) return undefined;
+  const withoutMarker = text.replace(/^ACTOR_REVIEW_RESULT\s*(?:\r?\n)?/, "").trim();
+  return withoutMarker || undefined;
+}
+
+function terminalSemanticResult(
+  status: Record<string, unknown>,
+  stateDir: string,
+  observedStatus: RunObservedStatus,
+): RunTerminalSemanticResult {
+  const correlation = status.launch_correlation &&
+    typeof status.launch_correlation === "object" &&
+    !Array.isArray(status.launch_correlation)
+    ? status.launch_correlation as Record<string, unknown>
+    : {};
+  const correlationId =
+    typeof correlation.correlation_id === "string"
+      ? correlation.correlation_id
+      : typeof correlation.tool_call_id === "string"
+        ? correlation.tool_call_id
+        : undefined;
+  const mailbox = status.mailbox &&
+    typeof status.mailbox === "object" &&
+    !Array.isArray(status.mailbox)
+    ? status.mailbox as Record<string, unknown>
+    : {};
+  const emits = Array.isArray(mailbox.emits)
+    ? mailbox.emits.filter((item): item is string => typeof item === "string")
+    : [];
+  const outbox = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "outbox.jsonl"),
+  ).records;
+  const explicit = outbox.findLast((record) => {
+    const type = String(record.type ?? record.event ?? "");
+    return emits.includes(type) && !["command.done", "run.done", "run.failed"].includes(type);
+  });
+  if (explicit) {
+    const type = String(explicit.type ?? explicit.event);
+    return {
+      ...(explicit.body === undefined
+        ? {} : { body: formatSemanticBody(explicit.body) }),
+      ...(typeof explicit.correlation_id === "string"
+        ? { correlationId: explicit.correlation_id } : correlationId ? { correlationId } : {}),
+      metadata: {
+        ...(explicit.metadata &&
+        typeof explicit.metadata === "object" &&
+        !Array.isArray(explicit.metadata)
+          ? explicit.metadata as Record<string, unknown> : {}),
+        ...(status.transport_context &&
+        typeof status.transport_context === "object" &&
+        !Array.isArray(status.transport_context)
+          ? {
+              transport_context: status.transport_context as Record<string, unknown>,
+            } : {}),
+        run: String(status.run ?? ""),
+        status: observedStatus,
+      },
+      summary: String(explicit.summary ?? type),
+      synthesized: false,
+      type,
+    };
+  }
+  const reviewCompleted = observedStatus === "done" && emits.includes("review.completed");
+  const result = status.result &&
+    typeof status.result === "object" &&
+    !Array.isArray(status.result)
+    ? status.result as Record<string, unknown>
+    : {};
+  const type = reviewCompleted
+    ? "review.completed"
+    : observedStatus === "done" ? "run.done" : "run.failed";
+  const stdoutBody = observedStatus === "done"
+    ? semanticBodyFromStdout(stateDir) : undefined;
+  return {
+    ...(stdoutBody
+      ? { body: stdoutBody }
+      : typeof result.error === "string" ? { body: result.error } : {}),
+    ...(correlationId ? { correlationId } : {}),
+    metadata: {
+      ...(status.transport_context &&
+      typeof status.transport_context === "object" &&
+      !Array.isArray(status.transport_context)
+        ? {
+            transport_context: status.transport_context as Record<string, unknown>,
+          } : {}),
+      run: String(status.run ?? ""), status: observedStatus,
+    },
+    summary: reviewCompleted ? "Review completed." :
+      observedStatus === "done" ? "Run completed." : `Run ${observedStatus}.`,
+    synthesized: true,
+    type,
+  };
+}
+
+function formatSemanticBody(body: unknown): string {
+  const rendered = typeof body === "string" ? body : JSON.stringify(body);
+  const text = typeof rendered === "string" ? rendered : String(body);
+  const compact = text.trim();
+  return compact.length > TERMINAL_RESULT_CHARS
+    ? `${compact.slice(0, TERMINAL_RESULT_CHARS - 1)}…`
+    : compact;
+}
+
 function observeRun(stateDir: string): RunObservation | undefined {
   try {
     const status = AsyncRuns.getRunStatus(stateDir);
     const progress = getProgress(status);
     const run = typeof status.run === "string" ? status.run : undefined;
     if (!run) return undefined;
+    const observedStatus = status.status as RunObservedStatus;
     return {
       activeSubagents: toNumber(progress.activeSubagents),
       completed: toNumber(progress.completed),
+      ...(status.launch_correlation &&
+      typeof status.launch_correlation === "object" &&
+      !Array.isArray(status.launch_correlation)
+        ? { launchCorrelation: status.launch_correlation as Record<string, string> }
+        : {}),
       failures: Array.isArray(progress.failures)
         ? progress.failures.length
         : undefined,
@@ -542,9 +702,12 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(typeof status.retire_when === "string"
         ? { retireWhen: status.retire_when }
         : {}),
+      ...(TERMINAL.has(observedStatus)
+        ? { semanticResult: terminalSemanticResult(status, stateDir, observedStatus) }
+        : {}),
       run,
       stateDir,
-      status: status.status as RunObservedStatus,
+      status: observedStatus,
       ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
       updatedAt: getUpdatedAt(status),
     };
@@ -933,9 +1096,11 @@ export function detectRunTransitions(
         run: run.run,
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
+        ...(run.launchCorrelation ? { launchCorrelation: run.launchCorrelation } : {}),
         ...(run.launchSource ? { launchSource: run.launchSource } : {}),
         ...(run.modelPolicy ? { modelPolicy: run.modelPolicy } : {}),
         ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
+        ...(run.semanticResult ? { semanticResult: run.semanticResult } : {}),
         ...(run.terminalHandled ? { terminalHandled: true } : {}),
         to: run.status,
         ...(run.tool ? { tool: run.tool } : {}),
@@ -1195,7 +1360,8 @@ function isUserRecipeFile(file: string | undefined): boolean {
   if (!file) return false;
   const recipeRoot = resolve(Paths.getRecipeRoot());
   const path = resolve(file);
-  return path === recipeRoot || path.startsWith(`${recipeRoot}/`);
+  const relation = relative(recipeRoot, path);
+  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
 }
 
 export function shouldSuggestRecipePersistence(
@@ -1245,16 +1411,26 @@ function formatTransitionNextActions(transition: RunTransition): string {
   return `\nNext actions: ${actions.join(" | ")}`;
 }
 
+function formatTransitionSemanticResult(transition: RunTransition): string {
+  const result = transition.semanticResult;
+  if (!result) return "";
+  const correlation = result.correlationId
+    ? `\nCorrelation: ${result.correlationId}` : "";
+  const body = result.body ? `\nResult:\n${result.body}` : "";
+  return `\nSemantic result: ${result.type} — ${result.summary}${correlation}${body}`;
+}
+
 export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
   const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
   const policy = formatTransitionPolicy(transition);
   const nextActions = formatTransitionNextActions(transition);
+  const semanticResult = formatTransitionSemanticResult(transition);
   if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
+    return `Run ${transition.run} completed successfully.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
   if (transition.to === "failed")
-    return `Run ${transition.run} failed.${policy}${artifacts}${runFiles}${nextActions}`;
+    return `Run ${transition.run} failed.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}`;
   if (transition.to === "cancelled")
     return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
   if (transition.to === "killed")

package/lib/runs-control.ts

@@ -42,6 +42,7 @@ export function getRunProcessSignalPlan(
 export interface RunProcessSignalDeps {
   killProcess?: typeof process.kill;
   runtimePlatform?: NodeJS.Platform;
+  spawnProcess?: typeof spawnSync;
   verifyIdentity?: (
     pid: number,
     expected: RunProcessIdentity,
@@ -70,8 +71,26 @@ export function signalOwnedRunProcess(
   }
   const plan = getRunProcessSignalPlan(pid, signal, runtimePlatform);
   if (plan.command && plan.args) {
-    const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
+    const spawnProcess = deps.spawnProcess ?? spawnSync;
+    let result = spawnProcess(plan.command, plan.args, { encoding: "utf8" });
+    if (
+      runtimePlatform === "win32" &&
+      result.status !== 0 &&
+      !plan.args.includes("/F")
+    ) {
+      result = spawnProcess(plan.command, [...plan.args, "/F"], {
+        encoding: "utf8",
+      });
+    }
     if (result.status !== 0) {
+      if (expectedIdentity) {
+        const finalProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(
+          pid,
+          expectedIdentity,
+          runtimePlatform,
+        );
+        if (finalProof.status === "dead_pid") return plan;
+      }
       throw new Error(
         result.stderr?.trim() ||
           result.stdout?.trim() ||

package/lib/runs-ownership.ts

@@ -12,7 +12,8 @@ import {
   realpathSync,
 } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
 
 import { writeJsonAtomic } from "./file-state.ts";
 
@@ -35,13 +36,31 @@ function comparablePath(path: string): string {
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 
+function isSystemTempRootAlias(resolved: string, canonical: string): boolean {
+  const tempRoot = resolve(tmpdir());
+  const relativeStateDir = relative(tempRoot, resolved);
+  if (
+    relativeStateDir === ".." ||
+    relativeStateDir.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) ||
+    isAbsolute(relativeStateDir)
+  ) {
+    return false;
+  }
+  const canonicalTempRoot = realpathSync.native(tempRoot);
+  const expectedCanonical = resolve(canonicalTempRoot, relativeStateDir);
+  return comparablePath(canonical) === comparablePath(expectedCanonical);
+}
+
 function assertCanonicalDirectory(stateDir: string): string {
   const resolved = resolve(stateDir);
   if (lstatSync(resolved).isSymbolicLink()) {
     throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
   }
-  const canonical = realpathSync(resolved);
-  if (comparablePath(canonical) !== comparablePath(resolved)) {
+  const canonical = realpathSync.native(resolved);
+  if (
+    comparablePath(canonical) !== comparablePath(resolved) &&
+    !isSystemTempRootAlias(resolved, canonical)
+  ) {
     throw new Error(`Run state directory has an ambiguous symlink alias: ${resolved}`);
   }
   return resolved;

package/lib/runs-process.ts

@@ -6,7 +6,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { platform } from "node:os";
-import { resolve } from "node:path";
+import { posix, win32 } from "node:path";
 
 export interface RunProcessIdentity {
   command: string;
@@ -125,8 +125,9 @@ export function captureRunProcessIdentity(
   if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
     return undefined;
   }
-  const resolvedCwd = resolve(cwd);
-  const canonicalCwd = existsSync(resolvedCwd)
+  const pathApi = runtimePlatform === "win32" ? win32 : posix;
+  const resolvedCwd = pathApi.resolve(cwd);
+  const canonicalCwd = runtimePlatform === platform() && existsSync(resolvedCwd)
     ? realpathSync.native(resolvedCwd)
     : resolvedCwd;
   const expectedCwd =

package/lib/runs-start.ts

@@ -93,6 +93,7 @@ export function prepareStateDirForStart(
     "result.json",
     "stderr.log",
     "stdout.log",
+    "terminal-delivery-failure.json",
     "terminal-handled.json",
   ]) {
     rmSync(join(stateDir, file), { force: true });

package/lib/runs-status.ts

@@ -61,6 +61,9 @@ export function buildRunStatus(
       ? "running"
       : (getInterruptedRunStatus(stateDir) ?? "exited");
   const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
+  const terminalDeliveryFailure = readJson(
+    join(stateDir, "terminal-delivery-failure.json"),
+  );
   return {
     ...meta,
     eventsFile: join(stateDir, "events.jsonl"),
@@ -70,6 +73,8 @@ export function buildRunStatus(
     process_identity_status: processIdentity.status,
     progress: readJson(join(stateDir, "progress.json")) || null,
     result: result || null,
+    ...(terminalDeliveryFailure
+      ? { terminal_delivery_failure: terminalDeliveryFailure } : {}),
     ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),
     state_dir: String(meta.state_dir ?? stateDir),
     stderrLog: join(stateDir, "stderr.log"),

package/lib/tools-inspect.ts

@@ -7,6 +7,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Limits from "./limits.ts";
@@ -269,7 +270,7 @@ function getPiActorsRuntimeStatus(): Record<string, unknown> {
   } catch {
     git_commit = undefined;
   }
-  const entrypoint = new URL(import.meta.url).pathname;
+  const entrypoint = fileURLToPath(import.meta.url);
   return {
     automatic_recipe_review: Paths.isAutomaticRecipeReviewEnabled(),
     entrypoint,

package/lib/tools-local.ts

@@ -143,6 +143,14 @@ export function createRuntimeToolDefinition(
     paramSchema.run_id = Schema.stringSchema(
       "Optional run id override for this async template recipe invocation.",
     );
+  if (isAsyncRecipe) {
+    paramSchema.correlation_id = Schema.stringSchema(
+      "Optional workflow correlation id preserved in terminal follow-up delivery.",
+    );
+    paramSchema.transport_context = Schema.looseObjectSchema(
+      "Optional originating transport route preserved for detached terminal follow-up.",
+    );
+  }
   return {
     name: cfg.name,
     label: cfg.name,
@@ -155,7 +163,7 @@ export function createRuntimeToolDefinition(
         )
       : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
     async execute(
-      _toolCallId: string,
+      toolCallId: string,
       params: unknown,
       signal: AbortSignal | undefined,
       _onUpdate: unknown,
@@ -172,7 +180,7 @@ export function createRuntimeToolDefinition(
         }
         if (isAsyncRecipe) {
           const input = params as Record<string, unknown>;
-          const { run_id, ...values } = input;
+          const { correlation_id, run_id, transport_context, ...values } = input;
           const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
           const runId =
             typeof run_id === "string" && run_id.trim()
@@ -182,6 +190,17 @@ export function createRuntimeToolDefinition(
             {
               ...base,
               launch_source: "tool",
+              launch_correlation: {
+                ...(typeof correlation_id === "string"
+                  ? { correlation_id } : {}),
+                tool_call_id: toolCallId,
+              },
+              ...(transport_context &&
+              typeof transport_context === "object" &&
+              !Array.isArray(transport_context)
+                ? {
+                    transport_context: transport_context as Record<string, unknown>,
+                  } : {}),
               ownerId: getRunOwnerId(ctx),
               run_id: runId,
               tool: cfg.name,

package/lib/tools-spawn.ts

@@ -144,6 +144,9 @@ export function createSpawnToolDefinition<
         as: Schema.stringSchema(
           "Optional actor address for the spawned run, e.g. run:<id>.",
         ),
+        correlation_id: Schema.stringSchema(
+          "Optional workflow correlation id preserved in terminal follow-up delivery.",
+        ),
         file: Schema.stringSchema(
           "Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes.",
         ),
@@ -162,6 +165,9 @@ export function createSpawnToolDefinition<
         values: Schema.looseObjectSchema(
           "Runtime placeholder values passed to the actor.",
         ),
+        transport_context: Schema.looseObjectSchema(
+          "Optional originating transport route preserved for detached terminal follow-up, e.g. Telegram chat_id and thread_id.",
+        ),
         verbose: Schema.booleanSchema(
           "Return full JSON instead of compact text.",
         ),
@@ -169,7 +175,7 @@ export function createSpawnToolDefinition<
       [],
     ),
     async execute(
-      _toolCallId: string,
+      toolCallId: string,
       params: unknown,
       _signal: AbortSignal | undefined,
       _onUpdate: unknown,
@@ -196,7 +202,14 @@ export function createSpawnToolDefinition<
           {
             file: recipe,
             launch_source: "spawn",
+            launch_correlation: {
+              ...(typeof input.correlation_id === "string"
+                ? { correlation_id: input.correlation_id } : {}),
+              tool_call_id: toolCallId,
+            },
             ownerId: getRunOwnerId(ctx),
+            ...(input.transport_context
+              ? { transport_context: asRecord(input.transport_context) } : {}),
             run_id: runId,
             ...(input.template !== undefined
               ? {