@llblab/pi-actors 0.42.3 → 0.43.1

package/dist/lib/limits.d.ts

@@ -1,14 +1,18 @@
 /**
- * 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 declare const DEFAULT_INSPECT_LINES = 40;
 export declare const TOOL_OUTPUT_MAX_BYTES: number;
 export declare const TOOL_OUTPUT_MAX_LINES = 2000;
 export declare const COMPACT_PREVIEW_CHARS = 160;
+export declare const CONTROL_ACTION_MAX_LENGTH = 64;
+export declare const CONTROL_INPUT_MAX_BYTES = 380;
+export declare const CONTROL_WIRE_MAX_BYTES = 512;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
-export declare const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
 export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
 export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
 export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;
+export declare const TRACE_EVENT_MAX_BYTES: number;
+export declare const TRACE_EVENT_MAX_READ = 200;

package/dist/lib/limits.js

@@ -1,14 +1,18 @@
 /**
- * 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/dist/lib/observability.d.ts

@@ -1,13 +1,13 @@
 /**
  * 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 { type FSWatcher } from "node:fs";
 import * as AsyncRuns from "./async-runs.ts";
 export type RunObservedStatus = "running" | "done" | "failed" | "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;
     completed?: number;
@@ -41,13 +41,13 @@ export interface RunSummary {
     total: number;
 }
 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[];
@@ -63,7 +63,7 @@ export interface RunUiNotificationSink {
 }
 export declare function createRunUiObservationState(): RunUiObservationState;
 export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string, options?: {
-    includeOutbox?: boolean;
+    includeAttention?: boolean;
     stateRoot?: string;
 }): RunUiSnapshot;
 export declare function pruneRunUiObservationState(state: RunUiObservationState, snapshot: Pick<RunUiSnapshot, "summary" | "transitions">): void;
@@ -75,7 +75,7 @@ export declare function reconcileRunTerminalNotifications(input: {
     state: RunUiObservationState;
     stateRoot?: string;
 }): RunUiSnapshot;
-export declare function deliverRunOutboxNotifications(events: RunOutboxEvent[], sink: RunUiNotificationSink): void;
+export declare function deliverRunAttentionNotifications(events: RunAttentionEvent[], sink: RunUiNotificationSink): void;
 export interface RunRetirementCandidate {
     activeSubagents: number;
     childRuns: number;
@@ -150,13 +150,13 @@ export interface RunTerminalSemanticResult {
     synthesized: boolean;
     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;
@@ -173,11 +173,11 @@ export declare function findRunRetirementCandidates(summary: RunSummary): RunRet
 export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
 export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
 export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>, seenEventIds?: Map<string, Set<string>>): void;
-export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>): RunOutboxEvent[];
-export declare function getRunOutboxNotificationType(event: RunOutboxEvent): RunTransitionNotificationType;
-export declare function shouldNotifyRunOutboxEvent(event: RunOutboxEvent): boolean;
-export declare function shouldSendRunOutboxFollowUp(event: RunOutboxEvent): boolean;
-export declare function formatRunOutboxMessage(event: RunOutboxEvent): string;
+export declare function detectRunAttentionEvents(previousLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>): RunAttentionEvent[];
+export declare function getRunAttentionNotificationType(event: RunAttentionEvent): RunTransitionNotificationType;
+export declare function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean;
+export declare function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean;
+export declare function formatRunAttentionMessage(event: RunAttentionEvent): string;
 export declare function getRunTransitionNotificationType(transition: RunTransition): RunTransitionNotificationType;
 export declare function shouldNotifyRunTransition(transition: RunTransition): boolean;
 export declare function shouldSendRunTransitionFollowUp(transition: RunTransition): boolean;

package/dist/lib/observability.js

@@ -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 { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync, readSync, watch, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, } from "node:path";
@@ -10,26 +10,26 @@ import * as Paths from "./paths.js";
 import { readJsonlFileResilient } from "./state-readers.js";
 export function createRunUiObservationState() {
     return {
+        attentionEventIds: new Map(),
         eventLines: new Map(),
         frame: 0,
         observed: new Map(),
-        outboxEventIds: new Map(),
     };
 }
 export function readRunUiSnapshot(state, ownerId, options = {}) {
     const summary = summarizeRuns(options.stateRoot, ownerId);
     const status = renderRunStatus(summary, state.frame++);
     return {
-        outboxEvents: options.includeOutbox === false
+        attentionEvents: options.includeAttention === false
             ? []
-            : detectRunOutboxEvents(state.eventLines, summary, state.outboxEventIds),
+            : detectRunAttentionEvents(state.eventLines, summary, state.attentionEventIds),
         status,
         summary,
         transitions: detectRunTransitions(state.observed, summary),
     };
 }
 export function pruneRunUiObservationState(state, snapshot) {
-    pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.outboxEventIds);
+    pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.attentionEventIds);
 }
 export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
     for (const transition of transitions) {
@@ -68,23 +68,23 @@ export function deliverRunTransitionNotifications(transitions, sink, inFlight =
 }
 export function reconcileRunTerminalNotifications(input) {
     const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-        includeOutbox: false,
+        includeAttention: false,
         stateRoot: input.stateRoot,
     });
     deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     pruneRunUiObservationState(input.state, snapshot);
     return snapshot;
 }
-export function deliverRunOutboxNotifications(events, sink) {
+export function deliverRunAttentionNotifications(events, sink) {
     for (const event of events) {
-        if (!shouldNotifyRunOutboxEvent(event))
+        if (!shouldNotifyRunAttentionEvent(event))
             continue;
-        const text = formatRunOutboxMessage(event);
-        sink.notify(text, getRunOutboxNotificationType(event));
-        if (!shouldSendRunOutboxFollowUp(event))
+        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,
@@ -326,46 +326,7 @@ function terminalSemanticResult(status, stateDir, observedStatus) {
         : 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
-        : {};
-    const emits = Array.isArray(mailbox.emits)
-        ? mailbox.emits.filter((item) => typeof item === "string")
-        : [];
-    const outbox = readJsonlFileResilient(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 : {}),
-                ...(status.transport_context &&
-                    typeof status.transport_context === "object" &&
-                    !Array.isArray(status.transport_context)
-                    ? {
-                        transport_context: status.transport_context,
-                    } : {}),
-                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)
@@ -396,14 +357,6 @@ function terminalSemanticResult(status, stateDir, observedStatus) {
         type,
     };
 }
-function formatSemanticBody(body) {
-    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) {
     try {
         const status = AsyncRuns.getRunStatus(stateDir);
@@ -771,18 +724,20 @@ export function detectRunTransitions(previous, summary) {
     }
     return transitions;
 }
-function normalizeOutboxDelivery(value) {
+function normalizeTraceAttention(value) {
     return value === "notify" || value === "followup" ? value : "log";
 }
-function normalizeOutboxLevel(value) {
+function normalizeTraceLevel(value) {
     return value === "warning" || value === "error" ? value : "info";
 }
-function parseOutboxRecord(raw, run, index) {
+function parseAttentionRecord(raw, run, index) {
     if (!run.stateDir)
         return undefined;
-    const event = typeof raw.event === "string" && raw.event.trim()
-        ? raw.event.trim()
-        : "run.event";
+    const 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()
         : event;
@@ -795,10 +750,12 @@ function parseOutboxRecord(raw, run, index) {
     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)
@@ -810,9 +767,13 @@ function parseOutboxRecord(raw, run, index) {
         ts,
     };
 }
-function readOutboxRecords(run) {
+function readTraceAttentionRecords(run) {
     if (!run.stateDir)
         return [];
+    const tracePath = join(run.stateDir, "trace.jsonl");
+    if (existsSync(tracePath)) {
+        return readJsonlFileResilient(tracePath).records;
+    }
     return readJsonlFileResilient(join(run.stateDir, "outbox.jsonl")).records;
 }
 export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = [], seenEventIds = new Map()) {
@@ -839,11 +800,11 @@ export function pruneRunObservationState(previousStatuses, previousLineCounts, s
         }
     }
 }
-export function detectRunOutboxEvents(previousLineCounts, summary, seenEventIds = new Map()) {
+export function detectRunAttentionEvents(previousLineCounts, summary, seenEventIds = new Map()) {
     const events = [];
     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);
@@ -853,7 +814,7 @@ export function detectRunOutboxEvents(previousLineCounts, summary, seenEventIds
         const start = Math.min(previousCount, records.length);
         const seen = seenEventIds.get(key) ?? new Set();
         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);
@@ -864,14 +825,14 @@ export function detectRunOutboxEvents(previousLineCounts, summary, seenEventIds
     }
     return events;
 }
-export function getRunOutboxNotificationType(event) {
+export function getRunAttentionNotificationType(event) {
     return event.level;
 }
-export function shouldNotifyRunOutboxEvent(event) {
-    return event.delivery === "notify" || event.delivery === "followup";
+export function shouldNotifyRunAttentionEvent(event) {
+    return event.attention === "notify" || event.attention === "followup";
 }
-export function shouldSendRunOutboxFollowUp(event) {
-    return event.delivery === "followup";
+export function shouldSendRunAttentionFollowUp(event) {
+    return event.attention === "followup";
 }
 function commonDirectory(paths) {
     if (paths.length === 0)
@@ -919,7 +880,7 @@ function formatNamedArtifacts(artifacts) {
         return "";
     return formatPathGroup("Artifacts", Object.values(artifacts).filter((path) => typeof path === "string"));
 }
-function getOutboxField(event, key) {
+function getAttentionDataField(event, key) {
     return event.data &&
         typeof event.data === "object" &&
         !Array.isArray(event.data)
@@ -935,10 +896,10 @@ function formatBodyPreview(body) {
         return "";
     return `\nBody: ${compact.length > 500 ? `${compact.slice(0, 500)}…` : compact}`;
 }
-export function formatRunOutboxMessage(event) {
-    if (event.event === "command.done")
+export function formatRunAttentionMessage(event) {
+    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(transition) {
     if (transition.to === "done" || transition.to === "cancelled")

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- 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.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno 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.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -16,13 +16,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/dist/lib/recipe-control.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function normalizeRecipeControl(value: unknown): string[] | undefined;
+export declare function assertRecipeHasNoMailbox(recipe: Record<string, unknown>): void;

package/dist/lib/recipe-control.js

@@ -0,0 +1,43 @@
+/**
+ * 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.js";
+import * as Limits from "./limits.js";
+const RUNTIME_RUN_ACTIONS = new Set(["archive", "kill", "prune"]);
+export function normalizeRecipeControl(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("recipe.control must be an array of action strings");
+    }
+    const actions = [];
+    const seen = new Set();
+    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) {
+    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/dist/lib/recipes-discovery.js

@@ -356,6 +356,8 @@ function diagnosticSuggestedAction(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/dist/lib/recipes-references.d.ts

@@ -11,19 +11,6 @@ export interface TemplateRecipeImportBinding {
     values?: Record<string, unknown>;
 }
 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;
@@ -42,7 +29,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;

package/dist/lib/recipes-references.js

@@ -8,6 +8,7 @@ import { homedir } from "node:os";
 import { basename, dirname, extname, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
+import * as RecipeControl from "./recipe-control.js";
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
 function hasWhitespace(value) {
@@ -629,6 +630,7 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
     const raw = readRawRecipeConfig(path);
     if (!raw || !Object.hasOwn(raw, "template"))
         return undefined;
+    RecipeControl.assertRecipeHasNoMailbox(raw);
     const imports = {};
     for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
         const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
@@ -671,9 +673,9 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
     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" &&
@@ -743,24 +745,7 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
                 artifacts: Object.fromEntries(Object.entries(artifactSource).filter((entry) => typeof entry[1] === "string")),
             }
             : {}),
-        ...(isRecord(mailboxSource)
-            ? {
-                mailbox: {
-                    ...(Array.isArray(mailboxSource.accepts)
-                        ? {
-                            accepts: mailboxSource.accepts.filter((value) => typeof value === "string" ||
-                                (isRecord(value) && typeof value.type === "string")),
-                        }
-                        : {}),
-                    ...(Array.isArray(mailboxSource.emits)
-                        ? {
-                            emits: mailboxSource.emits.filter((value) => 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" }

package/dist/lib/review-control.d.ts

@@ -11,4 +11,4 @@ export interface AutomaticReviewControlOptions {
     toolStatePath?: string;
 }
 export declare function controlAutomaticReview(action: AutomaticReviewControlAction, scope: AutomaticReviewScope, options?: AutomaticReviewControlOptions): Record<string, unknown>;
-export declare function parseAutomaticReviewScope(body: unknown): AutomaticReviewScope;
+export declare function parseAutomaticReviewScope(input: unknown): AutomaticReviewScope;

package/dist/lib/review-control.js

@@ -98,14 +98,13 @@ export function controlAutomaticReview(action, scope, options = {}) {
     return {
         ...result,
         next_actions: nextActions,
-        sent: result.changed === true,
     };
 }
-export function parseAutomaticReviewScope(body) {
-    const record = body && typeof body === "object" && !Array.isArray(body)
-        ? body
+export function parseAutomaticReviewScope(input) {
+    const record = input && typeof input === "object" && !Array.isArray(input)
+        ? input
         : {};
     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/dist/lib/review-projection.js

@@ -68,17 +68,13 @@ function templateShape(value) {
 function contractShape(recipe) {
     if (!recipe)
         return undefined;
-    const mailbox = recipe.mailbox && typeof recipe.mailbox === "object" && !Array.isArray(recipe.mailbox)
-        ? recipe.mailbox
-        : {};
     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/dist/lib/run-ui-runtime.js

@@ -19,7 +19,7 @@ export function createRunUiRuntime(deps) {
             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 = (ctx, notify = false, terminalOnly = false) => {
@@ -33,7 +33,7 @@ export function createRunUiRuntime(deps) {
         Observability.deliverRunTransitionNotifications(snapshot.transitions, sink, terminalNotificationsInFlight);
         Observability.pruneRunUiObservationState(observation, snapshot);
         if (!terminalOnly) {
-            Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, sink);
+            Observability.deliverRunAttentionNotifications(snapshot.attentionEvents, sink);
         }
     };
     const reportDiagnostics = (ctx) => {