@llblab/pi-actors 0.22.5 → 0.23.0

package/dist/lib/recipe-usage.js

@@ -28,7 +28,10 @@ function getRecipeFingerprint(raw) {
     const { usage: _usage, ...content } = raw;
     return createHash("sha256").update(stableStringify(content)).digest("hex");
 }
-export function recordRecipeLaunch(path, now = new Date()) {
+function launchCounterKey(kind) {
+    return `${kind}_calls`;
+}
+export function recordRecipeLaunch(path, now = new Date(), kind = "direct") {
     if (!existsSync(path))
         return false;
     try {
@@ -37,16 +40,25 @@ export function recordRecipeLaunch(path, now = new Date()) {
             return false;
         const usage = isRecord(raw.usage) ? raw.usage : {};
         const fingerprint = getRecipeFingerprint(raw);
-        const changed = typeof usage.fingerprint === "string" && usage.fingerprint !== fingerprint;
+        const changed = typeof usage.fingerprint === "string" &&
+            usage.fingerprint !== fingerprint;
         const nowIso = now.toISOString();
+        const counterKey = launchCounterKey(kind);
         writeJsonAtomic(path, {
             ...raw,
             usage: {
                 ...usage,
                 calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
+                [counterKey]: (changed ? 0 : normalizeCalls(usage[counterKey])) + 1,
                 last_called: nowIso,
+                launch_kind: kind,
                 fingerprint,
-                ...(changed ? { reset_at: nowIso } : {}),
+                ...(changed
+                    ? {
+                        reset_at: nowIso,
+                        reset_reason: "recipe content fingerprint changed",
+                    }
+                    : {}),
             },
         });
         return true;

package/dist/lib/runtime.js

@@ -54,6 +54,15 @@ export function createAutoToolsRuntime(deps) {
         runtimeTools.add(cfg.name);
         runtimeToolFingerprints.set(cfg.name, fingerprint);
     }
+    function isStartupActionableRegistryWarning(warning) {
+        if (warning.includes("invokes bash;") &&
+            warning.includes("trusted executable content"))
+            return false;
+        if (warning.includes("invokes bash;") &&
+            warning.includes("shell scripts are trusted executable content"))
+            return false;
+        return true;
+    }
     function formatRecipeToolWarnings(warnings) {
         const shadowed = warnings.filter((warning) => warning.includes(" shadows "));
         const skipped = warnings.filter((warning) => warning.includes(" could not be exposed as a tool:"));
@@ -112,8 +121,9 @@ export function createAutoToolsRuntime(deps) {
             }
             registerRuntimeTool(cfg);
         }
-        if (warnings.length > 0) {
-            notify(ctx, formatRecipeToolWarnings(warnings), "warning");
+        const startupWarnings = warnings.filter(isStartupActionableRegistryWarning);
+        if (startupWarnings.length > 0) {
+            notify(ctx, formatRecipeToolWarnings(startupWarnings), "warning");
         }
     }
     return {

package/dist/lib/tools.js

@@ -7,6 +7,7 @@ import * as ActorMessages from "./actor-messages.js";
 import * as ActorRooms from "./actor-rooms.js";
 import * as AsyncRuns from "./async-runs.js";
 import * as Execution from "./execution.js";
+import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
 import * as Prompts from "./prompts.js";
 import * as RecipeDiscovery from "./recipe-discovery.js";
@@ -154,7 +155,7 @@ function compactRunMessages(messages) {
     ].join(" "))
         .join("\n")}`;
 }
-function compactPreview(value, maxLength = 80) {
+function compactPreview(value, maxLength = Limits.COMPACT_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
     const text = typeof value === "string" ? value : JSON.stringify(value, undefined, 0);
@@ -173,7 +174,9 @@ function compactRoomPreviews(previews) {
         `to=${preview.to}`,
         `type=${preview.type}`,
         preview.summary ? `summary=${compactPreview(preview.summary)}` : "",
-        preview.body_preview ? `body=${compactPreview(preview.body_preview)}` : "",
+        preview.body_preview
+            ? `body=${compactPreview(preview.body_preview)}`
+            : "",
     ]
         .filter(Boolean)
         .join(" "))
@@ -189,7 +192,9 @@ function compactRoomMessages(messages) {
         `to=${message.to}`,
         `type=${message.type}`,
         `summary=${String(message.summary ?? "").replaceAll(/\s+/g, "_")}`,
-        compactPreview(message.body) ? `body=${compactPreview(message.body)}` : "",
+        compactPreview(message.body)
+            ? `body=${compactPreview(message.body)}`
+            : "",
     ]
         .filter(Boolean)
         .join(" "))
@@ -203,8 +208,12 @@ function compactRoomContacts(contacts) {
         `address=${contact.address}`,
         contact.role !== undefined ? `role=${String(contact.role)}` : "",
         contact.parent !== undefined ? `parent=${String(contact.parent)}` : "",
-        contact.caps !== undefined ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}` : "",
-        contact.claim !== undefined ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}` : "",
+        contact.caps !== undefined
+            ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}`
+            : "",
+        contact.claim !== undefined
+            ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}`
+            : "",
         contact.status !== undefined ? `status=${String(contact.status)}` : "",
     ]
         .filter(Boolean)
@@ -220,8 +229,12 @@ function compactRoomRoster(roster) {
         `address=${member.address}`,
         `role=${String(member.role ?? "")}`,
         member.parent !== undefined ? `parent=${String(member.parent)}` : "",
-        member.caps !== undefined ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}` : "",
-        member.claim !== undefined ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}` : "",
+        member.caps !== undefined
+            ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}`
+            : "",
+        member.claim !== undefined
+            ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}`
+            : "",
         `status=${String(member.status ?? "")}`,
         `last_seen=${member.last_seen}`,
     ].join(" "))
@@ -245,19 +258,72 @@ function compactInboxMessages(messages, emptyLabel) {
         `type=${String(message.type ?? "")}`,
         `from=${String(message.from ?? "")}`,
         `to=${String(message.to ?? "")}`,
-        ...(message.queued_at ? [`queued_at=${String(message.queued_at)}`] : []),
+        ...(message.queued_at
+            ? [`queued_at=${String(message.queued_at)}`]
+            : []),
         ...(message.sent_at ? [`sent_at=${String(message.sent_at)}`] : []),
-        ...(message.claimed_at ? [`claimed_at=${String(message.claimed_at)}`] : []),
-        ...(message.handled_at ? [`handled_at=${String(message.handled_at)}`] : []),
-        ...(message.failed_at ? [`failed_at=${String(message.failed_at)}`] : []),
+        ...(message.claimed_at
+            ? [`claimed_at=${String(message.claimed_at)}`]
+            : []),
+        ...(message.handled_at
+            ? [`handled_at=${String(message.handled_at)}`]
+            : []),
+        ...(message.failed_at
+            ? [`failed_at=${String(message.failed_at)}`]
+            : []),
     ].join(" "))
         .join("\n")}`;
 }
 function compactBranchInbox(messages) {
     return compactInboxMessages(messages, "branch inbox");
 }
+function normalizeMailboxEntry(value) {
+    if (typeof value === "string")
+        return { type: value };
+    const record = asRecord(value);
+    if (typeof record.type !== "string" || !record.type.trim())
+        return undefined;
+    return {
+        type: record.type.trim(),
+        ...(record.body_schema !== undefined
+            ? { body_schema: record.body_schema }
+            : {}),
+        ...(record.ack !== undefined ? { ack: record.ack } : {}),
+        ...(typeof record.idempotency === "string"
+            ? { idempotency: record.idempotency }
+            : {}),
+        ...(typeof record.level === "string" ? { level: record.level } : {}),
+        ...(record.requires_response === true ? { requires_response: true } : {}),
+        ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
+    };
+}
+function normalizeMailboxContracts(mailbox) {
+    const accepts = Array.isArray(mailbox.accepts)
+        ? mailbox.accepts
+            .map(normalizeMailboxEntry)
+            .filter((entry) => Boolean(entry))
+        : [];
+    const emits = Array.isArray(mailbox.emits)
+        ? mailbox.emits
+            .map(normalizeMailboxEntry)
+            .filter((entry) => Boolean(entry))
+        : [];
+    return { accepts, emits };
+}
+function mailboxTypes(entries) {
+    return entries.flatMap((entry) => typeof asRecord(entry).type === "string"
+        ? [String(asRecord(entry).type)]
+        : []);
+}
 function compactRunMailbox(run, mailbox, messages) {
-    return `\nrun=${run} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}${compactInboxMessages(messages, "run inbox")}`;
+    const normalized = normalizeMailboxContracts(mailbox);
+    return `\nrun=${run} accepts=${mailboxTypes(normalized.accepts).join(",")} emits=${mailboxTypes(normalized.emits).join(",")}${compactInboxMessages(messages, "run inbox")}`;
+}
+function compactArtifactPath(value) {
+    if (typeof value === "string")
+        return value;
+    const record = asRecord(value);
+    return String(record.path ?? "<missing>");
 }
 function compactActorFiles(status) {
     const run = String(status.run ?? "<unknown>");
@@ -267,12 +333,14 @@ function compactActorFiles(status) {
         status.stderrLog,
         status.eventsFile,
         status.outboxFile,
-        status.state_dir ? `${String(status.state_dir)}/communication.json` : undefined,
+        status.state_dir
+            ? `${String(status.state_dir)}/communication.json`
+            : undefined,
         status.state_dir ? `${String(status.state_dir)}/result.json` : undefined,
     ].filter((file) => typeof file === "string");
     const artifactText = Object.keys(artifacts).length
         ? ` artifacts=${Object.entries(artifacts)
-            .map(([key, value]) => `${key}:${String(value)}`)
+            .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
             .join(",")}`
         : "";
     return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
@@ -302,11 +370,49 @@ function compactToolActor(name, tool) {
     const properties = asRecord(parameters.properties);
     return `\ntool=${name} description=${String(tool.description ?? "").replaceAll(/\s+/g, "_")} args=${Object.keys(properties).join(",")} required=${required}`;
 }
+function compactRecipeImports(summary) {
+    const active = Array.isArray(summary.active)
+        ? summary.active
+        : [];
+    const lines = active.flatMap((entry) => {
+        const imports = asRecord(entry.imports);
+        return Object.entries(imports).map(([alias, value]) => {
+            const binding = typeof value === "string" ? { from: value } : asRecord(value);
+            return `recipe=${String(entry.id ?? "<unknown>")} alias=${alias} from=${String(binding.from ?? value)}`;
+        });
+    });
+    return lines.length ? `\n${lines.join("\n")}` : "\n(no recipe imports)";
+}
+function compactRecipeDoctor(summary) {
+    const details = Array.isArray(summary.diagnostic_details)
+        ? summary.diagnostic_details
+        : [];
+    const recommendations = Array.isArray(summary.recommendations)
+        ? summary.recommendations
+        : [];
+    const counts = { error: 0, info: 0, warning: 0 };
+    for (const detail of details) {
+        const severity = String(detail.severity ?? "info");
+        if (severity === "error" || severity === "warning" || severity === "info")
+            counts[severity] += 1;
+    }
+    const lines = [
+        `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} recommendations=${recommendations.length}`,
+    ];
+    for (const detail of details.slice(0, 8)) {
+        lines.push(`${String(detail.severity ?? "info")} id=${String(detail.id ?? "root")} action=${compactPreview(detail.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS) ?? "inspect"}`);
+    }
+    return `\n${lines.join("\n")}`;
+}
 function compactRecipeRegistry(summary) {
     const active = Array.isArray(summary.active) ? summary.active.length : 0;
-    const shadowed = Array.isArray(summary.shadowed) ? summary.shadowed.length : 0;
+    const shadowed = Array.isArray(summary.shadowed)
+        ? summary.shadowed.length
+        : 0;
     const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
-    const disabled = Array.isArray(summary.disabled) ? summary.disabled.length : 0;
+    const disabled = Array.isArray(summary.disabled)
+        ? summary.disabled.length
+        : 0;
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
@@ -420,6 +526,11 @@ function assertMessageSenderBelongsToRun(message, run, routeLabel) {
         throw new Error(`message to ${routeLabel} requires from=run:${run} or branch:${run}/<branch>; got ${message.from}.`);
     }
 }
+async function routeBranchEnvelope(stateDir, runId, recipient, message, _options) {
+    const branchMessage = { ...message, to: recipient };
+    ActorRooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
+    return AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+}
 function getRoomMulticastRecipients(message, run) {
     const raw = message.metadata?.recipients;
     if (raw === undefined)
@@ -471,13 +582,17 @@ export function createSpawnToolDefinition() {
                 run_id: runId,
                 state_dir: typeof input.state_dir === "string" ? input.state_dir : undefined,
                 ...(input.template !== undefined
-                    ? { template: input.template }
+                    ? {
+                        template: input.template,
+                    }
                     : {}),
                 values: asRecord(input.values),
                 ...(input.artifacts &&
                     typeof input.artifacts === "object" &&
                     !Array.isArray(input.artifacts)
-                    ? { artifacts: input.artifacts }
+                    ? {
+                        artifacts: input.artifacts,
+                    }
                     : {}),
             }, ctx.cwd);
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -532,11 +647,15 @@ export function createInspectToolDefinition(deps = {}) {
             const target = String(input.target ?? "");
             const view = String(input.view ?? "");
             if (target === "recipes" || target === "recipe-registry") {
-                if (view !== "status" && view !== "summary") {
-                    throw new Error("inspect recipes supports view=status or view=summary.");
+                if (view !== "status" && view !== "summary" && view !== "doctor" && view !== "imports") {
+                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, or view=imports.");
                 }
                 const discovered = RecipeDiscovery.discoverRecipeSources([
-                    { root: deps.recipeRoot ?? Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+                    {
+                        root: deps.recipeRoot ?? Paths.getRecipeRoot(),
+                        defaultTool: true,
+                        mutableUsage: true,
+                    },
                     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
                 ]);
                 const summary = RecipeDiscovery.summarizeDiscovery(discovered);
@@ -544,7 +663,11 @@ export function createInspectToolDefinition(deps = {}) {
                     content: [
                         {
                             type: "text",
-                            text: maybeJsonText(summary, input.verbose === true, compactRecipeRegistry(summary)),
+                            text: maybeJsonText(summary, input.verbose === true, view === "doctor"
+                                ? compactRecipeDoctor(summary)
+                                : view === "imports"
+                                    ? compactRecipeImports(summary)
+                                    : compactRecipeRegistry(summary)),
                         },
                     ],
                     details: summary,
@@ -627,7 +750,7 @@ export function createInspectToolDefinition(deps = {}) {
                     };
                 }
                 if (view === "previews") {
-                    const previews = ActorRooms.readRoomMessagePreviews(stateDir, address.room, Number(input.lines || 40));
+                    const previews = ActorRooms.readRoomMessagePreviews(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [
                             {
@@ -639,7 +762,7 @@ export function createInspectToolDefinition(deps = {}) {
                     };
                 }
                 if (view === "messages") {
-                    const messages = ActorRooms.readRoomMessages(stateDir, address.room, Number(input.lines || 40));
+                    const messages = ActorRooms.readRoomMessages(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [
                             {
@@ -676,14 +799,16 @@ export function createInspectToolDefinition(deps = {}) {
                 }
                 throw new Error("inspect room:<run> supports view=status, view=messages, view=previews, view=roster, or view=contacts.");
             }
-            const runId = address.kind === "run" || address.kind === "branch" ? address.value : undefined;
+            const runId = address.kind === "run" || address.kind === "branch"
+                ? address.value
+                : undefined;
             if (!runId)
                 throw new Error("inspect target must be run:<id>, branch:<run>/<branch>, coordinator, session:<id>, or tool:<name>.");
             if (address.kind === "branch") {
                 if (view !== "mailbox")
                     throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
                 const status = assertRunAccessibleToContext(runId, ctx);
-                const branchInbox = ActorRooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                const branchInbox = ActorRooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                 const messages = branchInbox.messages;
                 return {
                     content: [
@@ -710,7 +835,7 @@ export function createInspectToolDefinition(deps = {}) {
                 }
                 case "tail": {
                     assertRunAccessibleToContext(runId, ctx);
-                    const text = AsyncRuns.tailRun(runId, Number(input.lines || 40));
+                    const text = AsyncRuns.tailRun(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [{ type: "text", text: `\n${text}` }],
                         details: {},
@@ -718,7 +843,7 @@ export function createInspectToolDefinition(deps = {}) {
                 }
                 case "messages": {
                     assertRunAccessibleToContext(runId, ctx);
-                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || 40));
+                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [
                             {
@@ -732,21 +857,30 @@ export function createInspectToolDefinition(deps = {}) {
                 case "artifacts":
                 case "files": {
                     const status = assertRunAccessibleToContext(runId, ctx);
+                    const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
+                    const details = artifactManifest
+                        ? { ...status, artifact_manifest: artifactManifest }
+                        : status;
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: maybeJsonText(status, input.verbose === true, compactActorFiles(status)),
+                                text: maybeJsonText(details, input.verbose === true, compactActorFiles(status)),
                             },
                         ],
-                        details: status,
+                        details,
                     };
                 }
                 case "mailbox": {
                     const status = assertRunAccessibleToContext(runId, ctx);
                     const mailbox = asRecord(status.mailbox);
-                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || 40));
-                    const details = { mailbox, messages };
+                    const normalizedMailbox = normalizeMailboxContracts(mailbox);
+                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    const details = {
+                        mailbox,
+                        normalized_mailbox: normalizedMailbox,
+                        messages,
+                    };
                     return {
                         content: [
                             {
@@ -802,7 +936,14 @@ export function createActorMessageToolDefinition(deps = {}) {
             const address = ActorMessages.parseActorAddress(message.to);
             let result;
             if (address.kind === "run" && address.value) {
-                assertRunAccessibleToContext(address.value, ctx);
+                const status = assertRunAccessibleToContext(address.value, ctx);
+                const normalizedMailbox = normalizeMailboxContracts(asRecord(status.mailbox));
+                const acceptedTypes = new Set(mailboxTypes(normalizedMailbox.accepts));
+                const advisoryWarnings = acceptedTypes.size > 0 && !acceptedTypes.has(message.type)
+                    ? [
+                        `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
+                    ]
+                    : [];
                 if (message.type === "control.stop" ||
                     message.type === "control.cancel") {
                     result = AsyncRuns.cancelRun(address.value);
@@ -810,9 +951,21 @@ export function createActorMessageToolDefinition(deps = {}) {
                 else if (message.type === "control.kill") {
                     result = AsyncRuns.killRun(address.value);
                 }
+                else if (message.type === "control.archive") {
+                    result = AsyncRuns.archiveRun(address.value);
+                }
+                else if (message.type === "control.prune") {
+                    const body = asRecord(message.body);
+                    result = AsyncRuns.pruneRun(address.value, {
+                        preserveArtifacts: body.preserve_artifacts === true ||
+                            body.preserveArtifacts === true,
+                    });
+                }
                 else {
                     result = await AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
                 }
+                if (advisoryWarnings.length > 0)
+                    result = { ...result, warnings: advisoryWarnings };
             }
             else if (address.kind === "branch" && address.value) {
                 const runId = address.value;
@@ -837,9 +990,10 @@ export function createActorMessageToolDefinition(deps = {}) {
                         }
                     }
                     ActorRooms.writeCommunicationSnapshot(stateDir, runId);
-                    ActorRooms.appendBranchInboxMessage(stateDir, runId, message.to, message);
                 }
-                result = await AsyncRuns.sendRunMessage(address.value, JSON.stringify(message));
+                result = await routeBranchEnvelope(stateDir, runId, message.to, message, {
+                    source: "direct",
+                });
             }
             else if (address.kind === "room" && address.value && address.room) {
                 const runId = address.value;
@@ -850,7 +1004,9 @@ export function createActorMessageToolDefinition(deps = {}) {
                     throw new Error(`${message.to} has no run state directory.`);
                 const recipients = getRoomMulticastRecipients(message, runId);
                 const roomResult = ActorRooms.appendRoomMessage(stateDir, address.room, message);
-                await Promise.all(recipients.map((recipient) => AsyncRuns.sendRunMessage(runId, JSON.stringify({ ...message, to: recipient }))));
+                await Promise.all(recipients.map((recipient) => routeBranchEnvelope(stateDir, runId, recipient, message, {
+                    source: "room-multicast",
+                })));
                 result = {
                     ...roomResult,
                     ...(recipients.length > 0
@@ -898,7 +1054,10 @@ export function createActorMessageToolDefinition(deps = {}) {
                 result = AsyncRuns.appendRunOutboxEvent(sender.value, {
                     body: message.body,
                     correlation_id: message.correlation_id,
-                    delivery: address.kind === "session" ? "followup" : undefined,
+                    delivery: message.metadata?.requires_response === true ||
+                        address.kind === "session"
+                        ? "followup"
+                        : undefined,
                     event: message.type,
                     from: message.from,
                     metadata: message.metadata,
@@ -965,7 +1124,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             try {
                 if (cfg.sourcePath)
-                    RecipeUsage.recordRecipeLaunch(cfg.sourcePath);
+                    RecipeUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
                 if (isAsyncRecipe) {
                     const input = params;
                     const { run_id, ...values } = input;

package/docs/async-runs.md

@@ -166,8 +166,9 @@ Low-level async actions map into the actor surface instead of forming a second p
 - Send/control → `message`
 - Status/tail/messages/list → `inspect`
 - Stop/kill → `message` with `control.stop` or `control.kill`, with synchronous results
+- Archive/prune terminal state → `message` with `control.archive` or `control.prune`, with active runs rejected fail-closed
 
-Compact text is returned by default so async management does not flood agent context; use verbose inspection when the full state object is needed. List output intentionally shares one state root across music, subagents, timers, and other async work; source fields such as `tool` and `recipe` distinguish run purpose when the launcher recorded them. Registered tools are the preferred user-facing surface for reusable recipes.
+Compact text is returned by default so async management does not flood agent context; use verbose inspection when the full state object is needed. List output intentionally shares one state root across music, subagents, timers, and other async work; source fields such as `tool` and `recipe` distinguish run purpose when the launcher recorded them. The run root may contain a rebuildable `index.json` with run id, state directory, owner, status, update time, and recipe/tool hints; corrupt indexes fall back to recursive scan. Registered tools are the preferred user-facing surface for reusable recipes. `control.prune` accepts `body.preserve_artifacts=true` to copy existing named artifacts beside the run root before deleting terminal state.
 
 ## Run-Local Messages
 

package/docs/template-recipes.md

@@ -162,7 +162,7 @@ Use recipe-level `mailbox` to document the semantic messages a recipe actor acce
 }
 ```
 
-`mailbox` is contract metadata, not transport configuration. It should name semantic message types, not transport commands, file paths, or CLI fragments.
+`mailbox` is contract metadata, not transport configuration. It should name semantic message types, not transport commands, file paths, or CLI fragments. Entries may be strings or typed objects such as `{ "type": "task.assign", "requires_response": true, "summary": "Assign work" }`; inspection normalizes both forms. Acceptance contracts are advisory by default: messages outside `mailbox.accepts` produce warnings rather than hard routing failures.
 
 ## Actor Recipe Context
 

package/docs/tool-registry.md

@@ -15,7 +15,6 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
 - Same-id JSON shadows Markdown in the same priority layer.
 
-
 Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. `inspect target=recipes view=summary verbose=true` includes usage metadata and operator-gated cleanup recommendations for invalid, shadowed, disabled, component-only, unused, or overriding recipes. Recommended actions stay explicit: keep as a tool/component, enable, merge, fix, delete, or archive. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
 
 `register_tool` is the preferred agent-facing mutation API. It creates, updates, and deletes recipe files in `~/.pi/agent/recipes`; agents do not need to edit the files directly for normal registration. Direct file edits are still valid for operators and advanced agents. Runtime behavior is reactive: file creation, deletion, or edits in the user recipe root trigger validation and tool-set refresh, with invalid recipes surfaced as diagnostics rather than silently ignored.

package/index.ts

@@ -60,6 +60,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   let actorInspectorUnreadOnly = false;
   let actorInspectorRoomLimitPerRun = 12;
   let selectedInspectorSequence: number | undefined;
+  const actorInspectorReadKeys = new Set<string>();
   let recipeWatcherFailureNotified = false;
   const getRunOwnerId = (ctx: ExtensionContext): string =>
     ctx.sessionManager.getSessionId();
@@ -108,6 +109,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
                     branch: actorInspectorBranch,
                     mention: actorInspectorMention,
                     ownerId,
+                    readKeys: actorInspectorReadKeys,
                     roomLimitPerRun: actorInspectorRoomLimitPerRun,
                     unreadOnly: actorInspectorUnreadOnly,
                   },
@@ -414,6 +416,22 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
         ctx.ui.notify("Usage: /actors-inspect <number>", "warning");
         return;
       }
+      const previews = ActorInspectorTui.readActorInspectorPreviews(
+        RUN_STATE_ROOT,
+        actorInspectorRows,
+        {
+          channels: actorInspectorChannels,
+          currentRunOnly: true,
+          branch: actorInspectorBranch,
+          mention: actorInspectorMention,
+          ownerId: getRunOwnerId(ctx),
+          readKeys: actorInspectorReadKeys,
+          roomLimitPerRun: actorInspectorRoomLimitPerRun,
+          unreadOnly: actorInspectorUnreadOnly,
+        },
+      );
+      const preview = previews.find((item) => item.sequence === sequence);
+      if (preview) actorInspectorReadKeys.add(ActorInspectorTui.inspectorPreviewReadKey(preview));
       selectedInspectorSequence = sequence;
       communicationWidgetVisible = true;
       updateRunUi(ctx);