@llblab/pi-actors 0.42.3 → 0.43.1

package/lib/limits.ts

@@ -1,15 +1,19 @@
 /**
- * Shared output and preview size limits.
- * Zones: output governance, actor-message previews, inspect defaults
+ * Shared output, preview, and Control envelope limits.
+ * Zones: output governance, Trace previews, Inspect defaults, Control portability
  */
 
 export const DEFAULT_INSPECT_LINES = 40;
 export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024;
 export const TOOL_OUTPUT_MAX_LINES = 2_000;
 export const COMPACT_PREVIEW_CHARS = 160;
+export const CONTROL_ACTION_MAX_LENGTH = 64;
+export const CONTROL_INPUT_MAX_BYTES = 380;
+export const CONTROL_WIRE_MAX_BYTES = 512;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
-export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
 export const SESSION_EVIDENCE_MAX_TURNS = 100;
 export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
 export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;
+export const TRACE_EVENT_MAX_BYTES = 64 * 1024;
+export const TRACE_EVENT_MAX_READ = 200;

package/lib/observability.ts

@@ -1,7 +1,7 @@
 /**
  * Async run observability helpers
  * Zones: async runtime, ambient UI, diagnostics
- * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
+ * Owns ambient summaries, terminal events, and Trace-attention delivery for detached Runs
  */
 
 import {
@@ -34,8 +34,8 @@ export type RunObservedStatus =
   | "exited"
   | "cancelled"
   | "killed";
-export type RunOutboxDelivery = "log" | "notify" | "followup";
-export type RunOutboxLevel = "info" | "warning" | "error";
+export type RunTraceAttention = "log" | "notify" | "followup";
+export type RunTraceLevel = "info" | "warning" | "error";
 
 export interface RunObservation {
   activeSubagents?: number;
@@ -72,14 +72,14 @@ export interface RunSummary {
 }
 
 export interface RunUiObservationState {
+  attentionEventIds: Map<string, Set<string>>;
   eventLines: Map<string, number>;
   frame: number;
   observed: Map<string, RunObservedStatus>;
-  outboxEventIds: Map<string, Set<string>>;
 }
 
 export interface RunUiSnapshot {
-  outboxEvents: RunOutboxEvent[];
+  attentionEvents: RunAttentionEvent[];
   status: string | undefined;
   summary: RunSummary;
   transitions: RunTransition[];
@@ -97,28 +97,28 @@ export interface RunUiNotificationSink {
 
 export function createRunUiObservationState(): RunUiObservationState {
   return {
+    attentionEventIds: new Map<string, Set<string>>(),
     eventLines: new Map<string, number>(),
     frame: 0,
     observed: new Map<string, RunObservedStatus>(),
-    outboxEventIds: new Map<string, Set<string>>(),
   };
 }
 
 export function readRunUiSnapshot(
   state: RunUiObservationState,
   ownerId: string,
-  options: { includeOutbox?: boolean; stateRoot?: string } = {},
+  options: { includeAttention?: boolean; stateRoot?: string } = {},
 ): RunUiSnapshot {
   const summary = summarizeRuns(options.stateRoot, ownerId);
   const status = renderRunStatus(summary, state.frame++);
   return {
-    outboxEvents:
-      options.includeOutbox === false
+    attentionEvents:
+      options.includeAttention === false
         ? []
-        : detectRunOutboxEvents(
+        : detectRunAttentionEvents(
             state.eventLines,
             summary,
-            state.outboxEventIds,
+            state.attentionEventIds,
           ),
     status,
     summary,
@@ -137,7 +137,7 @@ export function pruneRunUiObservationState(
     snapshot.transitions.map(
       (transition) => transition.stateDir ?? transition.run,
     ),
-    state.outboxEventIds,
+    state.attentionEventIds,
   );
 }
 
@@ -194,7 +194,7 @@ export function reconcileRunTerminalNotifications(input: {
   stateRoot?: string;
 }): RunUiSnapshot {
   const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-    includeOutbox: false,
+    includeAttention: false,
     stateRoot: input.stateRoot,
   });
   deliverRunTransitionNotifications(
@@ -206,17 +206,17 @@ export function reconcileRunTerminalNotifications(input: {
   return snapshot;
 }
 
-export function deliverRunOutboxNotifications(
-  events: RunOutboxEvent[],
+export function deliverRunAttentionNotifications(
+  events: RunAttentionEvent[],
   sink: RunUiNotificationSink,
 ): void {
   for (const event of events) {
-    if (!shouldNotifyRunOutboxEvent(event)) continue;
-    const text = formatRunOutboxMessage(event);
-    sink.notify(text, getRunOutboxNotificationType(event));
-    if (!shouldSendRunOutboxFollowUp(event)) continue;
+    if (!shouldNotifyRunAttentionEvent(event)) continue;
+    const text = formatRunAttentionMessage(event);
+    sink.notify(text, getRunAttentionNotificationType(event));
+    if (!shouldSendRunAttentionFollowUp(event)) continue;
     sink.sendFollowUp({
-      customType: "pi-actors-run-message",
+      customType: "pi-actors-run-trace",
       content: text,
       display: false,
       details: event,
@@ -457,13 +457,13 @@ export interface RunTerminalSemanticResult {
   type: string;
 }
 
-export interface RunOutboxEvent {
+export interface RunAttentionEvent {
   body?: unknown;
   data?: unknown;
-  delivery: RunOutboxDelivery;
-  event: string;
+  attention: RunTraceAttention;
   id: string;
-  level: RunOutboxLevel;
+  kind: string;
+  level: RunTraceLevel;
   metadata?: Record<string, unknown>;
   run: string;
   stateDir: string;
@@ -575,48 +575,7 @@ function terminalSemanticResult(
       : 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 reviewCompleted = false;
   const result = status.result &&
     typeof status.result === "object" &&
     !Array.isArray(status.result)
@@ -648,15 +607,6 @@ function terminalSemanticResult(
   };
 }
 
-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);
@@ -1110,24 +1060,26 @@ export function detectRunTransitions(
   return transitions;
 }
 
-function normalizeOutboxDelivery(value: unknown): RunOutboxDelivery {
+function normalizeTraceAttention(value: unknown): RunTraceAttention {
   return value === "notify" || value === "followup" ? value : "log";
 }
 
-function normalizeOutboxLevel(value: unknown): RunOutboxLevel {
+function normalizeTraceLevel(value: unknown): RunTraceLevel {
   return value === "warning" || value === "error" ? value : "info";
 }
 
-function parseOutboxRecord(
+function parseAttentionRecord(
   raw: Record<string, unknown>,
   run: RunObservation,
   index: number,
-): RunOutboxEvent | undefined {
+): RunAttentionEvent | undefined {
   if (!run.stateDir) return undefined;
   const event =
-    typeof raw.event === "string" && raw.event.trim()
-      ? raw.event.trim()
-      : "run.event";
+    typeof raw.kind === "string" && raw.kind.trim()
+      ? raw.kind.trim()
+      : typeof raw.event === "string" && raw.event.trim()
+        ? raw.event.trim()
+        : "run.event";
   const summary =
     typeof raw.summary === "string" && raw.summary.trim()
       ? raw.summary.trim()
@@ -1143,10 +1095,13 @@ function parseOutboxRecord(
   return {
     ...(raw.body !== undefined ? { body: raw.body } : {}),
     ...(raw.data !== undefined ? { data: raw.data } : {}),
-    delivery: normalizeOutboxDelivery(raw.delivery),
-    event,
+    attention:
+      raw.attention === "notify" || raw.attention === "followup"
+        ? raw.attention
+        : normalizeTraceAttention(raw.delivery),
     id,
-    level: normalizeOutboxLevel(raw.level),
+    kind: event,
+    level: normalizeTraceLevel(raw.level),
     ...(raw.metadata &&
     typeof raw.metadata === "object" &&
     !Array.isArray(raw.metadata)
@@ -1159,8 +1114,12 @@ function parseOutboxRecord(
   };
 }
 
-function readOutboxRecords(run: RunObservation): Record<string, unknown>[] {
+function readTraceAttentionRecords(run: RunObservation): Record<string, unknown>[] {
   if (!run.stateDir) return [];
+  const tracePath = join(run.stateDir, "trace.jsonl");
+  if (existsSync(tracePath)) {
+    return readJsonlFileResilient<Record<string, unknown>>(tracePath).records;
+  }
   return readJsonlFileResilient<Record<string, unknown>>(
     join(run.stateDir, "outbox.jsonl"),
   ).records;
@@ -1199,15 +1158,15 @@ export function pruneRunObservationState(
   }
 }
 
-export function detectRunOutboxEvents(
+export function detectRunAttentionEvents(
   previousLineCounts: Map<string, number>,
   summary: RunSummary,
   seenEventIds: Map<string, Set<string>> = new Map(),
-): RunOutboxEvent[] {
-  const events: RunOutboxEvent[] = [];
+): RunAttentionEvent[] {
+  const events: RunAttentionEvent[] = [];
   for (const run of summary.runs) {
     const key = run.stateDir ?? run.run;
-    const records = readOutboxRecords(run);
+    const records = readTraceAttentionRecords(run);
     const previousCount = previousLineCounts.get(key) ?? 0;
     if (run.notificationPolicy === "silent") {
       previousLineCounts.set(key, records.length);
@@ -1217,7 +1176,7 @@ export function detectRunOutboxEvents(
     const start = Math.min(previousCount, records.length);
     const seen = seenEventIds.get(key) ?? new Set<string>();
     for (let index = start; index < records.length; index += 1) {
-      const event = parseOutboxRecord(records[index], run, index);
+      const event = parseAttentionRecord(records[index], run, index);
       if (!event || seen.has(event.id)) continue;
       events.push(event);
       seen.add(event.id);
@@ -1228,18 +1187,18 @@ export function detectRunOutboxEvents(
   return events;
 }
 
-export function getRunOutboxNotificationType(
-  event: RunOutboxEvent,
+export function getRunAttentionNotificationType(
+  event: RunAttentionEvent,
 ): RunTransitionNotificationType {
   return event.level;
 }
 
-export function shouldNotifyRunOutboxEvent(event: RunOutboxEvent): boolean {
-  return event.delivery === "notify" || event.delivery === "followup";
+export function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean {
+  return event.attention === "notify" || event.attention === "followup";
 }
 
-export function shouldSendRunOutboxFollowUp(event: RunOutboxEvent): boolean {
-  return event.delivery === "followup";
+export function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean {
+  return event.attention === "followup";
 }
 
 function commonDirectory(paths: string[]): string | undefined {
@@ -1297,7 +1256,7 @@ function formatNamedArtifacts(artifacts: unknown): string {
   );
 }
 
-function getOutboxField(event: RunOutboxEvent, key: string): unknown {
+function getAttentionDataField(event: RunAttentionEvent, key: string): unknown {
   return event.data &&
     typeof event.data === "object" &&
     !Array.isArray(event.data)
@@ -1313,10 +1272,10 @@ function formatBodyPreview(body: unknown): string {
   return `\nBody: ${compact.length > 500 ? `${compact.slice(0, 500)}…` : compact}`;
 }
 
-export function formatRunOutboxMessage(event: RunOutboxEvent): string {
-  if (event.event === "command.done")
+export function formatRunAttentionMessage(event: RunAttentionEvent): string {
+  if (event.kind === "command.done")
     return `Run ${event.run}: ${event.summary}`;
-  return `Run ${event.run}: ${event.summary}${formatBodyPreview(event.body)}${formatNamedArtifacts(getOutboxField(event, "artifacts"))}${formatRunFileList(getOutboxField(event, "run_files"))}`;
+  return `Run ${event.run}: ${event.summary}${formatBodyPreview(event.body)}${formatNamedArtifacts(getAttentionDataField(event, "artifacts"))}${formatRunFileList(getAttentionDataField(event, "run_files"))}`;
 }
 
 export function getRunTransitionNotificationType(

package/lib/prompts.ts

@@ -22,13 +22,13 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
+- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
-- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
+- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
-- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
+- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.

package/lib/recipe-control.ts

@@ -0,0 +1,52 @@
+/**
+ * Recipe Control contract.
+ * Zones: actor-local action declarations, normalization, reserved-action fencing
+ * Owns pure Recipe control validation; Recipe loading and Run capture stay in recipe/run domains.
+ */
+
+import * as Control from "./control.ts";
+import * as Limits from "./limits.ts";
+
+const RUNTIME_RUN_ACTIONS = new Set(["archive", "kill", "prune"]);
+
+export function normalizeRecipeControl(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) {
+    throw new Error("recipe.control must be an array of action strings");
+  }
+  const actions: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of value) {
+    if (typeof raw !== "string" || !raw.trim()) {
+      throw new Error("recipe.control actions must be non-empty strings");
+    }
+    const action = raw.trim();
+    if (!Control.isControlAction(action)) {
+      throw new Error(`invalid recipe.control action: ${action}`);
+    }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+      throw new Error(
+        `recipe.control action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters: ${action}`,
+      );
+    }
+    if (RUNTIME_RUN_ACTIONS.has(action)) {
+      throw new Error(
+        `recipe.control action is runtime-reserved and must not be declared: ${action}`,
+      );
+    }
+    if (seen.has(action)) {
+      throw new Error(`duplicate recipe.control action: ${action}`);
+    }
+    seen.add(action);
+    actions.push(action);
+  }
+  return actions;
+}
+
+export function assertRecipeHasNoMailbox(recipe: Record<string, unknown>): void {
+  if (Object.hasOwn(recipe, "mailbox")) {
+    throw new Error(
+      "recipe.mailbox was removed; replace it with control: [\"action\"] for actor-local inputs and emit Trace events for outputs",
+    );
+  }
+}

package/lib/recipes-discovery.ts

@@ -503,6 +503,8 @@ function diagnosticSuggestedAction(message: string): string {
   if (/cyclic/i.test(message)) return "break the import cycle";
   if (/exceeds.*size/i.test(message))
     return "split large prompt or data into separate files";
+  if (/recipe\.mailbox was removed/i.test(message))
+    return "replace mailbox.accepts with control actions and route outputs to Trace events";
   if (/repeat must/i.test(message))
     return "use a positive repeat count or an array-typed repeat source";
   if (/shadows/i.test(message))

package/lib/recipes-references.ts

@@ -14,6 +14,7 @@ import type {
 } from "./command-templates.ts";
 import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
+import * as RecipeControl from "./recipe-control.ts";
 
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
@@ -26,23 +27,6 @@ export interface TemplateRecipeImportBinding {
 
 export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 
-export type TemplateRecipeMailboxEntry =
-  | string
-  | {
-      type: string;
-      body_schema?: unknown;
-      ack?: boolean | string;
-      idempotency?: string;
-      requires_response?: boolean;
-      level?: string;
-      summary?: string;
-    };
-
-export interface TemplateRecipeMailbox {
-  accepts?: TemplateRecipeMailboxEntry[];
-  emits?: TemplateRecipeMailboxEntry[];
-}
-
 export interface TemplateRecipeDefinition {
   name?: string;
   description?: string;
@@ -61,7 +45,7 @@ export interface TemplateRecipeDefinition {
   accept_output?: "review_evidence";
   output?: string;
   artifacts?: Record<string, string>;
-  mailbox?: TemplateRecipeMailbox;
+  control?: string[];
   retire_when?: "children_terminal";
   retry?: number | string;
   failure?: CommandTemplates.CommandTemplateFailureScope;
@@ -912,6 +896,7 @@ export function readResolvedRecipeConfig(
   }
   const raw = readRawRecipeConfig(path);
   if (!raw || !Object.hasOwn(raw, "template")) return undefined;
+  RecipeControl.assertRecipeHasNoMailbox(raw);
   const imports: Record<string, ImportedRecipe> = {};
   for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
     const importPath = resolveRecipeImportPath(
@@ -975,9 +960,11 @@ export function readResolvedRecipeConfig(
   const artifactSource = isRecord(substituted.artifacts)
     ? substituted.artifacts
     : delegated?.artifacts;
-  const mailboxSource = isRecord(substituted.mailbox)
-    ? substituted.mailbox
-    : delegated?.mailbox;
+  const control = RecipeControl.normalizeRecipeControl(
+    Object.hasOwn(substituted, "control")
+      ? substituted.control
+      : delegated?.control,
+  );
   return {
     name: recipeName,
     ...(typeof substituted.description === "string" &&
@@ -1052,30 +1039,7 @@ export function readResolvedRecipeConfig(
           ),
         }
       : {}),
-    ...(isRecord(mailboxSource)
-      ? {
-          mailbox: {
-            ...(Array.isArray(mailboxSource.accepts)
-              ? {
-                  accepts: mailboxSource.accepts.filter(
-                    (value): value is TemplateRecipeMailboxEntry =>
-                      typeof value === "string" ||
-                      (isRecord(value) && typeof value.type === "string"),
-                  ),
-                }
-              : {}),
-            ...(Array.isArray(mailboxSource.emits)
-              ? {
-                  emits: mailboxSource.emits.filter(
-                    (value): value is TemplateRecipeMailboxEntry =>
-                      typeof value === "string" ||
-                      (isRecord(value) && typeof value.type === "string"),
-                  ),
-                }
-              : {}),
-          },
-        }
-      : {}),
+    ...(control !== undefined ? { control } : {}),
     ...(substituted.retire_when === "children_terminal" ||
     delegated?.retire_when === "children_terminal"
       ? { retire_when: "children_terminal" as const }

package/lib/review-control.ts

@@ -124,14 +124,13 @@ export function controlAutomaticReview(
   return {
     ...result,
     next_actions: nextActions,
-    sent: result.changed === true,
   };
 }
 
-export function parseAutomaticReviewScope(body: unknown): AutomaticReviewScope {
-  const record = body && typeof body === "object" && !Array.isArray(body)
-    ? body as Record<string, unknown>
+export function parseAutomaticReviewScope(input: unknown): AutomaticReviewScope {
+  const record = input && typeof input === "object" && !Array.isArray(input)
+    ? input as Record<string, unknown>
     : {};
   if (record.scope === "draft" || record.scope === "tool") return record.scope;
-  throw new Error("review control requires body.scope=draft or body.scope=tool.");
+  throw new Error("review Control requires input.scope=draft or input.scope=tool.");
 }

package/lib/review-projection.ts

@@ -87,17 +87,13 @@ function templateShape(value: unknown): Record<string, unknown> {
 
 function contractShape(recipe: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
   if (!recipe) return undefined;
-  const mailbox = recipe.mailbox && typeof recipe.mailbox === "object" && !Array.isArray(recipe.mailbox)
-    ? recipe.mailbox as Record<string, unknown>
-    : {};
   return {
     argument_count: countArray(recipe.args),
     artifact_count: countRecord(recipe.artifacts),
     async: recipe.async === true,
     default_count: countRecord(recipe.defaults),
     import_count: countRecord(recipe.imports),
-    mailbox_accepts_count: countArray(mailbox.accepts),
-    mailbox_emits_count: countArray(mailbox.emits),
+    control_action_count: countArray(recipe.control),
     template_shape: templateShape(recipe.template),
   };
 }

package/lib/run-ui-runtime.ts

@@ -38,7 +38,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       attempted: retirementAttempts,
       cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
       notify: (message, level) => ctx.ui.notify(message, level),
-      sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+      sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
     });
   };
   const update = (
@@ -62,7 +62,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     );
     Observability.pruneRunUiObservationState(observation, snapshot);
     if (!terminalOnly) {
-      Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, sink);
+      Observability.deliverRunAttentionNotifications(snapshot.attentionEvents, sink);
     }
   };
   const reportDiagnostics = (ctx: Pi.ExtensionContext): void => {