@llblab/pi-actors 0.14.2 → 0.15.0

package/docs/tool-registry.md

@@ -33,7 +33,7 @@ register_tool name=transcribe_groq \
 ```text
 register_tool name=call_subagent \
   description="Run pi as a non-interactive sub-agent" \
-  template="pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+  template="pi -p --model {model} --no-tools {prompt}" args="prompt:string,model:string"
 ```
 
 Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding.
@@ -53,7 +53,7 @@ For reusable actor workflows, register a small tool whose `template` points to a
 register_tool name=docs_review \
   description="Start an async docs review actor" \
   template="docs-review.json" \
-  args="scope:path,model:string=openai-codex/gpt-5.5"
+  args="scope:path,model:string"
 ```
 
 This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/docs-review.json` contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
@@ -66,7 +66,8 @@ When co-location is clearer than a separate file, the registry entry may include
     "description": "Start an async docs review",
     "name": "review-docs",
     "async": true,
-    "template": "pi -p --model openai-codex/gpt-5.5 --tools read,bash \"Review {scope}\""
+    "args": ["scope:path", "model:string"],
+    "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
   }
 }
 ```
@@ -91,11 +92,12 @@ Tool names come from the top-level registry keys. Tool entries define `template`
   },
   "call_subagent": {
     "description": "Run pi as a non-interactive sub-agent",
-    "template": "pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+    "args": ["prompt:string", "model:string"],
+    "template": "pi -p --model {model} --no-tools {prompt}"
   },
   "docs_review": {
     "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "args": ["scope:path", "model:string"],
     "template": "docs-review.json"
   }
 }

package/lib/actor-messages.ts

@@ -44,13 +44,15 @@ export function parseActorAddress(address: string): ActorAddress {
   const value = address.trim();
   if (value === "coordinator") return { kind: "coordinator" };
   const separator = value.indexOf(":");
-  if (separator < 0) throw new Error(`Actor address must include kind: ${address}`);
+  if (separator < 0)
+    throw new Error(`Actor address must include kind: ${address}`);
   const kind = value.slice(0, separator) as ActorAddressKind;
   const rest = value.slice(separator + 1);
   switch (kind) {
     case "branch": {
       const [run, branch, ...extra] = rest.split("/");
-      if (extra.length > 0) throw new Error(`Branch address has too many parts: ${address}`);
+      if (extra.length > 0)
+        throw new Error(`Branch address has too many parts: ${address}`);
       return {
         kind,
         value: assertToken(run || "", "branch run"),
@@ -74,14 +76,19 @@ export function formatActorAddress(address: ActorAddress): string {
   return `${address.kind}:${assertToken(address.value || "", `${address.kind} address`)}`;
 }
 
-function normalizeOptionalString(value: unknown, label: string): string | undefined {
+function normalizeOptionalString(
+  value: unknown,
+  label: string,
+): string | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "string") throw new Error(`${label} must be a string`);
   const normalized = value.trim();
   return normalized || undefined;
 }
 
-function normalizeMetadata(value: unknown): Record<string, unknown> | undefined {
+function normalizeMetadata(
+  value: unknown,
+): Record<string, unknown> | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "object" || Array.isArray(value)) {
     throw new Error("message metadata must be an object");
@@ -113,8 +120,14 @@ export function normalizeActorMessage(input: unknown): ActorMessage {
       ? { correlation_id: String(record.correlation_id) }
       : {}),
     ...(from ? { from: formatActorAddress(parseActorAddress(from)) } : {}),
-    ...(record.metadata !== undefined ? { metadata: normalizeMetadata(record.metadata) } : {}),
-    ...(record.reply_to !== undefined ? { reply_to: String(record.reply_to) } : {}),
-    ...(record.summary !== undefined ? { summary: String(record.summary) } : {}),
+    ...(record.metadata !== undefined
+      ? { metadata: normalizeMetadata(record.metadata) }
+      : {}),
+    ...(record.reply_to !== undefined
+      ? { reply_to: String(record.reply_to) }
+      : {}),
+    ...(record.summary !== undefined
+      ? { summary: String(record.summary) }
+      : {}),
   };
 }

package/lib/async-runs.ts

@@ -19,8 +19,8 @@ import {
   writeFileSync,
   writeSync,
 } from "node:fs";
-import { basename, extname, join, resolve } from "node:path";
 import { platform } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
 
 import type {
   CommandTemplateFailureScope,
@@ -28,8 +28,8 @@ import type {
 } from "./command-templates.ts";
 import { substituteCommandTemplateToken } from "./command-templates.ts";
 import { writeJsonAtomic } from "./file-state.ts";
-import * as RecipeReferences from "./recipe-references.ts";
 import * as Paths from "./paths.ts";
+import * as RecipeReferences from "./recipe-references.ts";
 
 export interface AsyncRunStartParams {
   async?: boolean;
@@ -139,8 +139,7 @@ function resolveArtifactPaths(
 function resolveRunTemplate(params: AsyncRunStartParams): {
   template: CommandTemplateValue;
 } {
-  if (!params.template)
-    throw new Error("spawn requires file or template.");
+  if (!params.template) throw new Error("spawn requires file or template.");
   const envelope: Record<string, unknown> = {};
   for (const key of [
     "args",
@@ -227,7 +226,8 @@ function isAlive(pid: number): boolean {
 }
 
 function pidMatchesRun(pid: number, cwd: string, stateDir: string): boolean {
-  if (platform() !== "linux" || !existsSync(`/proc/${pid}`)) return isAlive(pid);
+  if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
+    return isAlive(pid);
   try {
     const procCwd = readlinkSync(`/proc/${pid}/cwd`);
     const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
@@ -405,15 +405,23 @@ function normalizeRunOutboxEvent(
       : `${run}:${index}`;
   return {
     ...(record.body !== undefined ? { body: record.body } : {}),
-    ...(typeof record.correlation_id === "string" ? { correlation_id: record.correlation_id } : {}),
+    ...(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> } : {}),
+    ...(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,
     level: normalizeRunOutboxLevel(record.level),
-    ...(typeof record.reply_to === "string" ? { reply_to: record.reply_to } : {}),
+    ...(typeof record.reply_to === "string"
+      ? { reply_to: record.reply_to }
+      : {}),
     run,
     state_dir: stateDir,
     summary,
@@ -448,8 +456,9 @@ export function getRunStatus(runOrDir: string): Record<string, unknown> {
   const pid = Number(meta.pid || 0);
   const aliveOwnedRunner = Boolean(
     pid &&
-      isAlive(pid) &&
-      (!Array.isArray(meta.argv) || pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir)),
+    isAlive(pid) &&
+    (!Array.isArray(meta.argv) ||
+      pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir)),
   );
   const status: AsyncRunStatus = result
     ? Number(result.code ?? 0) === 0
@@ -555,7 +564,9 @@ export function appendRunOutboxEvent(
     ...(event.body !== undefined ? { body: event.body } : {}),
     ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
     ...(event.data !== undefined ? { data: event.data } : {}),
-    delivery: normalizeRunOutboxDelivery(event.delivery ?? (to === "coordinator" ? "followup" : "log")),
+    delivery: normalizeRunOutboxDelivery(
+      event.delivery ?? (to === "coordinator" ? "followup" : "log"),
+    ),
     event: type,
     from: event.from || `run:${run}`,
     level: normalizeRunOutboxLevel(event.level),
@@ -608,7 +619,9 @@ export function sendRunMessage(
     fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
     const bytes = writeSync(fd, payload);
     const trimmedMessage = message.trim().toLowerCase();
-    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
+      trimmedMessage,
+    );
     writeFileSync(
       join(stateDir, "events.jsonl"),
       `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts: new Date().toISOString() })}\n`,

package/lib/command-templates.ts

@@ -541,7 +541,12 @@ function shouldResolveEmbeddedCommandTemplateToken(
 function isFalsyCommandTemplateValue(value: unknown): boolean {
   if (value === undefined || value === null || value === false) return true;
   const normalized = String(value).trim().toLowerCase();
-  return normalized === "" || normalized === "0" || normalized === "false" || normalized === "no";
+  return (
+    normalized === "" ||
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no"
+  );
 }
 
 function resolveCommandTemplateCondition(

package/lib/config.ts

@@ -6,12 +6,12 @@
 
 import { existsSync, readFileSync } from "node:fs";
 
+import type { CommandTemplateValue } from "./command-templates.ts";
+import * as CommandTemplates from "./command-templates.ts";
 import { writeJsonAtomic } from "./file-state.ts";
 import { normalizeToolName } from "./identity.ts";
-import * as CommandTemplates from "./command-templates.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as Schema from "./schema.ts";
-import type { CommandTemplateValue } from "./command-templates.ts";
 
 export interface RegisteredTool {
   name: string;

package/lib/execution.ts

@@ -4,9 +4,9 @@
  * Owns command-template invocation execution and pi tool-result payload formatting
  */
 
+import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import { formatFailureOutput, formatOutput, formatToolText } from "./output.ts";
-import * as CommandTemplates from "./command-templates.ts";
 import * as Schema from "./schema.ts";
 
 export interface ToolExecOptions {
@@ -268,9 +268,10 @@ function resolveNumericControlField(
   label: string,
 ): number | undefined {
   if (value === undefined) return undefined;
-  const resolved = typeof value === "string"
-    ? CommandTemplates.substituteCommandTemplateToken(value, values, label)
-    : value;
+  const resolved =
+    typeof value === "string"
+      ? CommandTemplates.substituteCommandTemplateToken(value, values, label)
+      : value;
   if (resolved === "") return undefined;
   const numeric = Number(resolved);
   if (!Number.isFinite(numeric) || numeric < 0)
@@ -407,7 +408,10 @@ async function executeTemplateConfig(
   const controlValues = { ...(context.defaults ?? {}), ...params };
   await applyDelay(normalized.delay, controlValues, signal);
   if (
-    !CommandTemplates.shouldRunCommandTemplateNode(normalized.when, controlValues)
+    !CommandTemplates.shouldRunCommandTemplateNode(
+      normalized.when,
+      controlValues,
+    )
   ) {
     return {
       branches: [],

package/lib/observability.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, relative, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
@@ -114,7 +114,9 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(typeof status.ownerId === "string"
         ? { ownerId: status.ownerId }
         : {}),
-      ...(status.artifacts && typeof status.artifacts === "object" && !Array.isArray(status.artifacts)
+      ...(status.artifacts &&
+      typeof status.artifacts === "object" &&
+      !Array.isArray(status.artifacts)
         ? { artifacts: status.artifacts as Record<string, string> }
         : {}),
       ...(status.terminal_handled ? { terminalHandled: true } : {}),
@@ -359,7 +361,11 @@ function parseOutboxLine(
       event,
       id,
       level: normalizeOutboxLevel(raw.level),
-      ...(raw.metadata && typeof raw.metadata === "object" && !Array.isArray(raw.metadata) ? { metadata: raw.metadata as Record<string, unknown> } : {}),
+      ...(raw.metadata &&
+      typeof raw.metadata === "object" &&
+      !Array.isArray(raw.metadata)
+        ? { metadata: raw.metadata as Record<string, unknown> }
+        : {}),
       run: run.run,
       stateDir: run.stateDir,
       summary,
@@ -413,7 +419,8 @@ export function shouldSendRunOutboxFollowUp(event: RunOutboxEvent): boolean {
 
 function commonDirectory(paths: string[]): string | undefined {
   if (paths.length === 0) return undefined;
-  const split = (path: string): string[] => dirname(path).split("/").filter(Boolean);
+  const split = (path: string): string[] =>
+    dirname(path).split("/").filter(Boolean);
   const first = split(paths[0]);
   let length = first.length;
   for (const path of paths.slice(1)) {
@@ -440,7 +447,9 @@ function formatPathGroup(label: string, paths: string[]): string {
   const unique = [...new Set(paths.filter(Boolean))].slice(0, 8);
   if (unique.length === 0) return "";
   const base = commonDirectory(unique);
-  const names = unique.map((path) => `\`${relativeName(base, path)}\``).join(", ");
+  const names = unique
+    .map((path) => `\`${relativeName(base, path)}\``)
+    .join(", ");
   return `\n${label}:\n- Base: ${base ? `\`${base}\`` : "current run"}\n- Files: ${names}`;
 }
 
@@ -464,7 +473,9 @@ function formatNamedArtifacts(artifacts: unknown): string {
 }
 
 function getOutboxField(event: RunOutboxEvent, key: string): unknown {
-  return event.data && typeof event.data === "object" && !Array.isArray(event.data)
+  return event.data &&
+    typeof event.data === "object" &&
+    !Array.isArray(event.data)
     ? (event.data as Record<string, unknown>)[key]
     : undefined;
 }
@@ -478,7 +489,8 @@ function formatBodyPreview(body: unknown): string {
 }
 
 export function formatRunOutboxMessage(event: RunOutboxEvent): string {
-  if (event.event === "command.done") return `Run ${event.run}: ${event.summary}`;
+  if (event.event === "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"))}`;
 }
 
@@ -491,9 +503,7 @@ export function getRunTransitionNotificationType(
   return "error";
 }
 
-export function shouldNotifyRunTransition(
-  transition: RunTransition,
-): boolean {
+export function shouldNotifyRunTransition(transition: RunTransition): boolean {
   if (transition.terminalHandled) return false;
   return (
     transition.to === "done" ||

package/lib/prompts.ts

@@ -20,25 +20,18 @@ export const REGISTER_TOOL_GUIDELINES = [
 ];
 
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
-- Local-first cybernetic tool memory: agents persist trusted local capabilities instead of repeating shell recipes.
-- Task = user work; template = execution graph; recipe = saved JSON; run = execution instance.
-- Command templates stay sync: string leaf, array sequence, object flags, parallel: true fanout.
-- Template flags: args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output; placeholders support {value??fallback} and {flag?yes:no}.
-- Recipes live in ~/.pi/agent/recipes/*.json and wrap templates with metadata/defaults/imports/artifacts.
-- Recipe imports are local variables: imports.alias -> {"name":"alias"} nodes and {alias.defaults.key} refs.
-- Imported recipes are definitions, not nested async runs; parent async:true creates one run.
-- async:true = detached lifecycle; spawn creates run actors from recipes/templates.
-- Actor run state lives under ~/.pi/agent/tmp/pi-actors/runs.
-- Use spawn/message/inspect for actor-level start/send/observe; runtime action internals are absorbed into the actor API.
-- Run lifecycle = state files, logs, actor messages, mailbox send, cancel/kill, compact status; do not busy-poll runs, rely on message/follow-up notifications and use message for explicit run-local commands.
-- Tool template may be a command template, recipe path/name, or co-located recipe.
-- register_tool makes compact persistent buttons; args may be typed or derived from placeholders.
-- For single calls or short pipelines, use foreground templates/tools.
-- For subagents, swarms, background music, or long fanout, prefer async recipes/runs.
-- Long async fanout = parent async recipe wrapping template(parallel: true) and imports; packaged fanout recipes bubble branch completion follow-ups by default.
-- If asked to explore pi-actors, read README.md, docs/README.md, docs/template-recipes.md, docs/async-runs.md, and recipes/.
-- Ambient triangles show active async commands/subagents for the launching coordinator.
-- After async run finish, inspect status/tail/messages before final artifacts.`;
+- 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: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.
+- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
+- Recipes live in ~/.pi/agent/recipes/*.json, own template directly, and may declare metadata/defaults/imports/mailbox/artifacts.
+- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
+- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
+- Register_tool makes persistent tools from command templates, recipe names/paths, or co-located recipes; args may be typed or placeholder-derived.
+- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
+- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages.
+- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",
@@ -53,7 +46,7 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   templateArray:
     "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
   templateNull: "Delete the tool when template is null.",
-  args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,model=openai-codex/gpt-5.5",
+  args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast",
   update: "Set to true to overwrite an existing tool registration.",
   values:
     "Optional default runtime placeholder values for a co-located template recipe.",