@llblab/pi-actors 0.12.7 → 0.12.9

package/AGENTS.md

@@ -43,7 +43,7 @@
 - `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, and keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason
 - `Template migration boundary`: Tool definitions use `template`, not `script` | Trigger: Loading or editing persisted config | Action: Reject `script` entries explicitly and do not silently rewrite user config outside the repo
 - `Reserved tool names`: Built-in or core tool names must not be shadowed | Trigger: Adding or renaming registration logic | Action: Keep conflict checks before persistence and runtime registration
-- `Async run observability`: Ambient triangles count active async work units: each running async run contributes at least one triangle, and its reported active parallel command/subagent branches contribute the visible branch count when greater than one. Event-driven terminal/outbox watchers should initiate follow-up for unhandled terminal completion/failure states, packaged multi-agent `command.done` branch completions, and coordinator-bound script-authored messages; actor `message` is the explicit coordinator-to-run command channel paired with these upward events. Do not restore busy-polling loops, sleep-then-status smoke examples, or duplicate follow-ups for `cancel`, `kill`, or control-stop actions already handled by synchronous tool results. | Trigger: Changing async run UI, notifications, actor-message routing, or smoke-test interpretation | Action: Preserve branch-aware triangles from `progress.activeSubagents`, runtime-inferred branch bubbling for packaged fanout completion, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
+- `Async run observability`: Ambient triangles count active async work units: each running async run contributes at least one triangle, and its reported active parallel command/subagent branches contribute the visible branch count when greater than one. Event-driven terminal/outbox watchers should initiate follow-up for unhandled terminal completion/failure states, failed or in-flight `command.done` branch completions, and coordinator-bound script-authored messages with bounded body previews; actor `message` is the explicit coordinator-to-run command channel paired with these upward events. Do not restore busy-polling loops, sleep-then-status smoke examples, duplicate follow-ups for final successful leaf commands, or duplicate follow-ups for `cancel`, `kill`, or control-stop actions already handled by synchronous tool results. | Trigger: Changing async run UI, notifications, actor-message routing, or smoke-test interpretation | Action: Preserve branch-aware triangles from `progress.activeSubagents`, runtime-inferred branch bubbling for packaged fanout completion, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.
 - `Output discipline`: Tool stdout is returned with bounded context impact | Trigger: Changing execution or formatting | Action: Keep tail truncation, full-output temp files, and failure formatting intact
 - `Extension temp directory`: Temporary runtime files belong under `~/.pi/agent/tmp/pi-actors`; session start prepares the directory and prunes stale entries | Trigger: Adding temp files, run state, logs, or artifacts | Action: Do not use system tmp for extension-owned state unless the operator explicitly overrides a path

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.12.9: Actor Runtime Hotfix
+
+- `[Async Runs]` Protected the `runs` state root from session-start temp pruning, tightened live-run status around owned runner processes, and kept non-Linux FIFO control usable without `/proc`-only checks. Impact: long-lived actors are less likely to disappear or be misclassified during startup and stale PID reuse is reduced on Linux.
+- `[Actor Messages]` Preserved coordinator-bound actor message `body` and `metadata` through outbox parsing and follow-up formatting, with bounded body previews. Impact: checkpoint and decision messages reach the coordinator with the useful payload instead of only the summary line.
+- `[Observability]` Reduced generic `command.done` follow-up noise by keeping successful final leaf completions diagnostic while still bubbling failures and in-flight parallel branch completions. Impact: long sequential pipelines no longer flood the launching coordinator with low-value leaf-completion messages.
+- `[Output]` Moved truncated full-output files under `~/.pi/agent/tmp/pi-actors/outputs`. Impact: oversized tool output now follows the extension temp-directory contract instead of using system temp.
+
+## 0.12.8: Usage Hint Documentation
+
+- `[Docs]` Documented runtime actor-tool argument usage hints in README and tool-registry docs, and covered missing template-value hints separately from typed value errors. Impact: users and agents can discover the self-correction behavior without reading tests.
+
 ## 0.12.7: Tool Argument Usage Hints
 
 - `[Tools]` Added compact usage hints to runtime actor-tool argument errors when typed normalization or placeholder resolution fails. Impact: if an agent supplies a wrong enum/type value or misses a required template value after schema validation, the error now shows the expected call shape with required and optional fields.

package/README.md

@@ -361,6 +361,7 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - Tool args are derived from placeholders when `args` is omitted.
 - Typed arg declarations are progressive: `file:path`, `request_timeout:int=60000`, `speed:number=1.5`, `dry_run:bool=true`, `prompts:array`, and `mode:enum(check,fix)=check` can live in `args` or inline placeholders such as `{request_timeout:int=60000}`. They generate narrower tool schemas and runtime validation while existing untyped `args` and placeholders keep working.
 - `{arg=default}` inline defaults resolve after runtime values and stored `defaults`; `{arg??fallback}` handles empty/null fallback values; `{flag?--flag:}` ternaries map small truthy/falsy values to strings such as optional CLI flags.
+- Runtime actor-tool argument errors include a compact usage hint when typed normalization or template value resolution fails, including example call shape plus required and optional fields.
 - `template: [...]` sequences execute left to right; each successful step passes stdout to the next step on stdin.
 - Object nodes may set `parallel: true`; children receive the same stdin and joined stdout flows to the next sequence step.
 - Parallel nodes use soft-quorum semantics: failed branches are reported as degraded coverage unless failure propagation escalates to the root.
@@ -379,11 +380,11 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - `spawn`, `message`, and `inspect` are the public async coordination vocabulary. Low-level async actions map to this actor API: start belongs to `spawn`; send/control belongs to `message`; status/tail/events/list belong to `inspect`; stop/kill are runtime control messages with synchronous results.
 - Actor management returns compact text by default; pass `verbose: true` to `inspect` when full JSON state is needed.
 - Detached runs inject `{run_id}` and `{state_dir}` into template values for run-local artifacts or recipe-specific control endpoints.
-- Runtime actor messages are stored in `<state_dir>/outbox.jsonl`; coordinator attention is inferred by the runtime, not exposed as recipe or message-envelope input.
-- Native Windows should use WSL or a recipe-specific transport for FIFO-controlled recipes.
+- Runtime actor messages are stored in `<state_dir>/outbox.jsonl`; coordinator attention is inferred by the runtime, not exposed as recipe or message-envelope input. Follow-ups preserve bounded body previews and metadata for decision messages.
+- Native Windows should use WSL or a recipe-specific transport for FIFO-controlled recipes; Linux uses stricter `/proc` runner ownership checks for stale PID protection.
 - Registered tools may set `template` to a recipe JSON path/name; calling them follows that recipe's `async` mode.
 - File-backed recipes may declare `imports` and embed imported recipes with `{ "name": "alias" }` nodes, or read `{alias.defaults.key}`, `{alias.defaults.key=fallback}`, and `{alias.values.key?yes:no}` references before command-template execution.
-- Interactive sessions show ambient async activity as stable `▷` triangles aggregated across runs started by the current agent session. Each running async run contributes at least one triangle; parallel active branches can contribute more. One `▶` wave moves over the active set; terminal `done`/`failed`/unhandled `killed`/`exited` messages are delivered as compact follow-up context only to the launching coordinator agent, while intentional `cancel`, `kill`, and `stop` actions stay silent because the action already reports synchronously. Packaged multi-agent fanout recipes emit `command.done` messages by default so parallel subtask completions reach the coordinator.
+- Interactive sessions show ambient async activity as stable `▷` triangles aggregated across runs started by the current agent session. Each running async run contributes at least one triangle; parallel active branches can contribute more. One `▶` wave moves over the active set; terminal `done`/`failed`/unhandled `killed`/`exited` messages are delivered as compact follow-up context only to the launching coordinator agent, while intentional `cancel`, `kill`, and `stop` actions stay silent because the action already reports synchronously. Failed commands and in-flight parallel branch completions can bubble through `command.done`; successful final leaf completions remain diagnostic to avoid sequential pipeline noise.
 - Use `{file}` as the canonical local file path arg.
 - Stored `script` entries are rejected with migration guidance.
 

package/docs/actor-messages.md

@@ -98,7 +98,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-`mailbox.accepts` is a contract for coordinator-to-actor messages. `mailbox.emits` is a contract for actor-to-coordinator or actor-to-actor messages. Packaged interactive and message-producing recipes declare mailbox metadata so coordinators can discover semantic message types without reading FIFO details. Message-producing recipes produce actor-message-envelope-shaped records with `to`, `from`, `type`, `summary`, `body`, optional `correlation_id`/`reply_to`, and optional `metadata` fields. Deterministic pipelines should prefer `utility-actor-message` for this wrapping so message shape is validated and guaranteed instead of delegated to a prompt; its recipe args intentionally mirror the envelope field names.
+`mailbox.accepts` is a contract for coordinator-to-actor messages. `mailbox.emits` is a contract for actor-to-coordinator or actor-to-actor messages. Packaged interactive and message-producing recipes declare mailbox metadata so coordinators can discover semantic message types without reading FIFO details. Message-producing recipes produce actor-message-envelope-shaped records with `to`, `from`, `type`, `summary`, `body`, optional `correlation_id`/`reply_to`, and optional `metadata` fields. Coordinator follow-ups preserve bounded body previews and metadata so checkpoints do not lose their actionable payload. Deterministic pipelines should prefer `utility-actor-message` for this wrapping so message shape is validated and guaranteed instead of delegated to a prompt; its recipe args intentionally mirror the envelope field names.
 
 ## Spawn
 

package/docs/async-runs.md

@@ -81,7 +81,7 @@ Use ordinary files under the extension temp directory so status tools stay simpl
 - `run.json`: pid, optional source metadata (`tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir.
 - `progress.json`: phase, active command count, completed count, failures, and updated time.
 - `events.jsonl`: append-only lifecycle events.
-- `outbox.jsonl`: optional script-authored JSONL events for coordinator inspection, notifications, or follow-up context.
+- `outbox.jsonl`: optional script-authored JSONL actor-message events for coordinator inspection, notifications, or follow-up context. Coordinator follow-ups preserve bounded `body` previews plus message metadata for decision points.
 - `stdout.log` and `stderr.log`: detached process output.
 - `result.json`: final code, killed flag, output selector, and optional full-output path.
 
@@ -172,7 +172,7 @@ Native Windows does not support this Unix FIFO contract. Use WSL/Linux/macOS for
 
 ## Coordinator Notifications
 
-The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Packaged multi-agent fanout recipes bubble these completion messages by default because async branch completion is base coordinator context rather than optional diagnostics. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `runtime.cancel`, `runtime.kill`, and control messages such as `stop` stay out of follow-up context because the initiating message already returns synchronously. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
+The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `runtime.cancel`, `runtime.kill`, and control messages such as `stop` stay out of follow-up context because the initiating message already returns synchronously. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
 
 Ambient status indicators may refresh while work is active, but coordinator attention is event-driven from state-file changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through `events.jsonl`, `result.json`, and `outbox.jsonl`. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
 
@@ -227,6 +227,7 @@ Rules:
 - Prune stale entries on session start.
 - Default stale age is 24 hours unless the extension has a stronger reason.
 - Cleanup must be fail-open: cleanup races should not prevent extension startup.
+- The `runs` state root is preserved by startup cleanup; run lifecycle cleanup must be explicit and run-aware.
 - State that must survive restarts belongs in the agent root, not in `tmp`.
 
 ## Ambient Observability

package/docs/tool-registry.md

@@ -149,6 +149,20 @@ Supported compact types are `string` (implicit), `path`, `int`, `number`, `bool`
 
 Defaults are applied before substitution, with resolution order runtime values → stored `defaults` → inline default → error. Missing required values are rejected before or during execution. Typed runtime values are normalized before substitution: `int` and `number` values become numeric strings, booleans become `true`/`false`, and enums must match one of the declared values.
 
+When typed normalization or template value resolution fails at runtime, the tool error includes a compact usage hint:
+
+```text
+Invalid arguments for tool "check_tool": Argument mode must be one of: check, fix.
+
+Expected call shape for check_tool:
+check_tool({
+  "file": "<file>",
+  "mode": "check"
+})
+Required: file
+Optional: mode
+```
+
 Template recipe tools derive public arguments from the referenced or co-located command template when the recipe is available locally. Explicit `args` is still available when the public tool surface should be narrower or defaulted differently, or when a file-backed recipe is not available during registration. Runtime values are passed as `values`; async recipe tools also accept optional `run_id` to override the generated run id.
 
 ## File Argument Naming

package/lib/async-runs.ts

@@ -20,6 +20,7 @@ import {
   writeSync,
 } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
+import { platform } from "node:os";
 
 import type {
   CommandTemplateFailureScope,
@@ -76,6 +77,7 @@ export interface RunOutboxEvent {
   from?: string;
   id: string;
   level: RunOutboxLevel;
+  metadata?: Record<string, unknown>;
   reply_to?: string;
   run: string;
   state_dir: string;
@@ -225,6 +227,7 @@ function isAlive(pid: number): boolean {
 }
 
 function pidMatchesRun(pid: number, cwd: string, stateDir: string): boolean {
+  if (platform() !== "linux" || !existsSync(`/proc/${pid}`)) return isAlive(pid);
   try {
     const procCwd = readlinkSync(`/proc/${pid}/cwd`);
     const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
@@ -405,6 +408,7 @@ function normalizeRunOutboxEvent(
     ...(typeof record.correlation_id === "string" ? { correlation_id: record.correlation_id } : {}),
     ...(record.data !== undefined ? { data: record.data } : {}),
     delivery: normalizeRunOutboxDelivery(record.delivery),
+    ...(record.metadata && typeof record.metadata === "object" && !Array.isArray(record.metadata) ? { metadata: record.metadata as Record<string, unknown> } : {}),
     event,
     ...(typeof record.from === "string" ? { from: record.from } : {}),
     id,
@@ -442,11 +446,16 @@ export function getRunStatus(runOrDir: string): Record<string, unknown> {
   if (!meta) throw new Error(`Run not found: ${runOrDir}`);
   const result = readJson(join(stateDir, "result.json"));
   const pid = Number(meta.pid || 0);
+  const aliveOwnedRunner = Boolean(
+    pid &&
+      isAlive(pid) &&
+      (!Array.isArray(meta.argv) || pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir)),
+  );
   const status: AsyncRunStatus = result
     ? Number(result.code ?? 0) === 0
       ? "done"
       : "failed"
-    : isAlive(pid)
+    : aliveOwnedRunner
       ? "running"
       : (getInterruptedRunStatus(stateDir) ?? "exited");
   const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
@@ -530,6 +539,7 @@ export function appendRunOutboxEvent(
     event?: string;
     from?: string;
     level?: string;
+    metadata?: Record<string, unknown>;
     reply_to?: string;
     summary?: string;
     to?: string;
@@ -549,6 +559,7 @@ export function appendRunOutboxEvent(
     event: type,
     from: event.from || `run:${run}`,
     level: normalizeRunOutboxLevel(event.level),
+    ...(event.metadata ? { metadata: event.metadata } : {}),
     ...(event.reply_to ? { reply_to: event.reply_to } : {}),
     summary: event.summary || type,
     to,

package/lib/observability.ts

@@ -55,11 +55,13 @@ export interface RunTransition {
 }
 
 export interface RunOutboxEvent {
+  body?: unknown;
   data?: unknown;
   delivery: RunOutboxDelivery;
   event: string;
   id: string;
   level: RunOutboxLevel;
+  metadata?: Record<string, unknown>;
   run: string;
   stateDir: string;
   summary: string;
@@ -351,11 +353,13 @@ function parseOutboxLine(
         ? raw.id.trim()
         : `${run.run}:${index}`;
     return {
+      ...(raw.body !== undefined ? { body: raw.body } : {}),
       ...(raw.data !== undefined ? { data: raw.data } : {}),
       delivery: normalizeOutboxDelivery(raw.delivery),
       event,
       id,
       level: normalizeOutboxLevel(raw.level),
+      ...(raw.metadata && typeof raw.metadata === "object" && !Array.isArray(raw.metadata) ? { metadata: raw.metadata as Record<string, unknown> } : {}),
       run: run.run,
       stateDir: run.stateDir,
       summary,
@@ -465,9 +469,17 @@ function getOutboxField(event: RunOutboxEvent, key: string): unknown {
     : undefined;
 }
 
+function formatBodyPreview(body: unknown): string {
+  if (body === undefined) return "";
+  const rendered = typeof body === "string" ? body : JSON.stringify(body);
+  const compact = rendered.replaceAll(/\s+/g, " ").trim();
+  if (!compact) return "";
+  return `\nBody: ${compact.length > 500 ? `${compact.slice(0, 500)}…` : compact}`;
+}
+
 export function formatRunOutboxMessage(event: RunOutboxEvent): string {
   if (event.event === "command.done") return `Run ${event.run}: ${event.summary}`;
-  return `Run ${event.run}: ${event.summary}${formatNamedArtifacts(getOutboxField(event, "artifacts"))}${formatRunFileList(getOutboxField(event, "run_files"))}`;
+  return `Run ${event.run}: ${event.summary}${formatBodyPreview(event.body)}${formatNamedArtifacts(getOutboxField(event, "artifacts"))}${formatRunFileList(getOutboxField(event, "run_files"))}`;
 }
 
 export function getRunTransitionNotificationType(

package/lib/output.ts

@@ -4,11 +4,11 @@
  * Owns stdout/stderr failure formatting, tail truncation, and full-output temp-file persistence
  */
 
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { sanitizeFilePart } from "./identity.ts";
+import * as Paths from "./paths.ts";
 
 export interface FormattedOutput {
   text: string;
@@ -25,7 +25,9 @@ export function writeFullOutput(
   content: string,
 ): string | undefined {
   try {
-    const dir = mkdtempSync(join(tmpdir(), "pi-actors-"));
+    const outputRoot = join(Paths.getExtensionTmpDir(), "outputs");
+    mkdirSync(outputRoot, { recursive: true });
+    const dir = mkdtempSync(join(outputRoot, "tool-output-"));
     const filePath = join(
       dir,
       `${sanitizeFilePart(toolName)}-${sanitizeFilePart(stream)}.txt`,

package/lib/temp.ts

@@ -13,6 +13,7 @@ export async function cleanupStaleTempEntries(
   tempDir: string,
   maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS,
   now = Date.now(),
+  preservedEntries = new Set(["runs"]),
 ): Promise<number> {
   let entries: Array<{ name: string }>;
   let removed = 0;
@@ -22,6 +23,7 @@ export async function cleanupStaleTempEntries(
     return 0;
   }
   for (const entry of entries) {
+    if (preservedEntries.has(entry.name)) continue;
     const path = join(tempDir, entry.name);
     try {
       const info = await stat(path);

package/lib/tools.ts

@@ -575,6 +575,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           correlation_id: message.correlation_id,
           event: message.type,
           from: message.from,
+          metadata: message.metadata,
           reply_to: message.reply_to,
           summary: message.summary,
           to: message.to,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.12.7",
+  "version": "0.12.9",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "type": "module",

package/scripts/async-runner.mjs

@@ -43,8 +43,8 @@ function event(name, data = {}) {
     `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
   );
 }
-function getMessageDelivery(name) {
-  return name === "command.done" ? "followup" : "log";
+function getCommandDoneDelivery(result) {
+  return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
 }
 function outbox(name, summary, data = {}, delivery = "log", level = "info") {
   appendFileSync(
@@ -102,7 +102,7 @@ async function observedExec(command, args, options) {
       command,
       killed: result.killed,
     },
-    getMessageDelivery("command.done"),
+    getCommandDoneDelivery(result),
     result.code === 0 ? "info" : "error",
   );
   progressRunning();