@llblab/pi-actors 0.12.10 → 0.12.13

package/BACKLOG.md

@@ -6,7 +6,7 @@ Continue progressive component/pipeline expansion in small validated slices; rea
 
 - Plan organic universal communication primitives.
   - Priority: High.
-  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` and `run:<id>` → `session:<id>` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, `inspect target=tool:<name>` exposes registered tool actor contracts, `inspect target=coordinator` exposes current-session run inventory, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`, and run termination now accepts actor-native `control.stop`/`control.cancel`/`control.kill` aliases while preserving legacy `runtime.*` compatibility. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
+  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` and `run:<id>` → `session:<id>` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, `inspect target=tool:<name>` exposes registered tool actor contracts, `inspect target=coordinator` exposes current-session run inventory, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`, run termination now accepts actor-native `control.stop`/`control.cancel`/`control.kill` aliases while preserving legacy `runtime.*` compatibility, async command events preserve full argv details while keeping coordinator summaries bounded, and async-run operations recommendations now emit structured `message`/`inspect` objects instead of shell-like suggestion strings. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
   - Scope: Design and implement a small semantic layer around addressed messages and actors while preserving low-level primitives as adapters where useful. Candidate top-level concepts are `spawn` for creating an actor/run from a recipe or template, `message` for sending typed messages to any address, and `inspect` for intentional observation/debugging. Candidate addresses include `run:<id>`, `branch:<run>/<branch>`, `coordinator`, `session:<id>`, `tool:<name>`, and future chat/session endpoints. Candidate message fields include `to`, `from`, `type`, `summary`, `body`, `reply_to`, `correlation_id`, and `metadata`.
   - Contract direction: Unify “send down” and “messages up” as one message model. `to: run:<id>` routes to a run mailbox, `to: coordinator` routes to the coordinator attention path, and branch/tool/session addresses can be layered over the same semantic envelope. Recipes should declare mailbox capability (`accepts`, `emits`) without exposing FIFO/outbox mechanics or delivery policy as their public interface.
   - Design gates: Breaking changes are allowed in this phase, so compress concepts instead of preserving accidental surfaces. Consolidate duplicated lifecycle/message/event APIs into a concentrated protocol with the fewest durable nouns and verbs that still explain the system. Duplex communication should be symmetric where the domain is symmetric: the same message envelope should represent run→coordinator, coordinator→run, run→run, branch→parent, and parent→branch traffic, with routing/transport hidden below it. Keep command templates as the portable synchronous execution graph; keep recipe files as semantic definitions; avoid leaking transports into public args; make polling an explicit diagnostic operation, not an example path; replace runtime action names with the actor API rather than preserving parallel concepts.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.12.13: Structured Run Operations Recommendations
+
+- `[Recipe Utilities]` Changed `utility-run-ops-snapshot` recommendations from shell-like suggestion strings to structured `message` and `inspect` call objects. Impact: async-run operations reports now preserve the actor API shape directly and avoid reintroducing command-string parsing into coordinator handoffs.
+
+## 0.12.12: Async Command Summary Hygiene
+
+- `[Observability]` Kept async `command.done` summaries bounded while preserving full argv-shaped command details in event payloads. Impact: long prompted fanouts keep diagnostic fidelity without flooding coordinator follow-ups with huge command lines.
+
+## 0.12.11: Recipe Import Diagnostics Hotfix
+
+- `[Template Recipes]` Added regression coverage proving imported recipe nodes execute correctly under a repeated parallel parent (`imports` + `repeat` + object `template`). Impact: the suspected composition blocker is now guarded as supported behavior instead of relying on manual smoke interpretation.
+- `[Observability]` Expanded command details in foreground execution results and async `command.start`/`command.done` events from executable-only labels to full argv-shaped launch strings. Impact: failed fanout branches no longer appear as misleading `pi && pi && ...` summaries when the real command was `pi -p --model ...` with a long prompt.
+- `[Spawn]` Allowed the public `spawn` schema to accept inline object command-template configs, not only strings and arrays. Impact: agents can launch object-form templates with `parallel`, `repeat`, `failure`, and nested `template` directly through `spawn` as documented.
+
 ## 0.12.10: Actor Ownership and Recipe Operations
 
 - `[Actor Messages]` Added actor-native `control.stop`, `control.cancel`, and `control.kill` handling for run termination while retaining `runtime.cancel` and `runtime.kill` as compatibility aliases. Impact: public examples can use the same control-message vocabulary declared by recipe mailboxes instead of preserving runtime action names.

package/lib/execution.ts

@@ -98,6 +98,20 @@ function createTemplateConfig(
   return { args: cfg.args, defaults: cfg.defaults, template: cfg.template };
 }
 
+function quoteCommandDetailPart(value: string): string {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function formatInvocationDetail(
+  invocation: CommandTemplates.CommandTemplateInvocation,
+): string {
+  return [invocation.command, ...invocation.args]
+    .map(quoteCommandDetailPart)
+    .join(" ");
+}
+
 function formatCommandDetail(commands: string[]): string {
   return commands.length === 1 ? commands[0] : commands.join(" && ");
 }
@@ -494,7 +508,7 @@ async function executeTemplateConfig(
     });
     return {
       branches: [],
-      commands: [invocation.command],
+      commands: [formatInvocationDetail(invocation)],
       failures: [],
       result,
     };

package/lib/tools.ts

@@ -344,6 +344,9 @@ export function createSpawnToolDefinition<
         template: unionSchema([
           stringSchema("Inline command template string"),
           arraySchema("Inline command-template sequence or parallel tree"),
+          looseObjectSchema(
+            "Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template.",
+          ),
         ]),
         values: looseObjectSchema("Runtime placeholder values passed to the actor."),
         verbose: booleanSchema("Return full JSON instead of compact text."),

package/package.json

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

package/scripts/async-runner.mjs

@@ -43,6 +43,19 @@ function event(name, data = {}) {
     `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
   );
 }
+function quoteCommandDetailPart(value) {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+function formatCommandDetail(command, args) {
+  return [command, ...args].map(quoteCommandDetailPart).join(" ");
+}
+function summarizeCommandDetail(commandDetail) {
+  return commandDetail.length > 160
+    ? `${commandDetail.slice(0, 157)}...`
+    : commandDetail;
+}
 function getCommandDoneDelivery(result) {
   return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
 }
@@ -76,30 +89,35 @@ function progressRunning() {
   });
 }
 async function observedExec(command, args, options) {
+  const commandDetail = formatCommandDetail(command, args);
   activeSubagents += 1;
-  event("command.start", { activeSubagents, command });
+  event("command.start", { activeSubagents, command: commandDetail });
   progressRunning();
   const result = await execCommandTemplate(command, args, options);
   activeSubagents = Math.max(0, activeSubagents - 1);
   completedSubagents += 1;
   if (result.code !== 0) {
-    subagentFailures.push({ code: result.code, command, killed: result.killed });
+    subagentFailures.push({
+      code: result.code,
+      command: commandDetail,
+      killed: result.killed,
+    });
   }
   event("command.done", {
     activeSubagents,
     code: result.code,
-    command,
+    command: commandDetail,
     killed: result.killed,
   });
   outbox(
     "command.done",
-    `Command ${command} completed with code ${result.code}`,
+    `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`,
     {
       activeSubagents,
       ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
       run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
       code: result.code,
-      command,
+      command: commandDetail,
       killed: result.killed,
     },
     getCommandDoneDelivery(result),

package/scripts/recipe-utils.mjs

@@ -135,10 +135,18 @@ function runOpsSnapshot(rootValue, eventFileValue, linesValue = "80", staleMinut
     const updatedMs = Date.parse(run.updated || "");
     const stale = Number.isFinite(updatedMs) && Number.isFinite(staleMs) && now - updatedMs > staleMs;
     if (run.status === "running" && stale) {
-      return [{ run: run.run, reason: "running-stale", suggested_message: `message to=run:${run.run} type=control.stop body=stop` }];
+      return [{
+        run: run.run,
+        reason: "running-stale",
+        suggested_message: { to: `run:${run.run}`, type: "control.stop", body: "stop" },
+      }];
     }
     if (["failed", "exited", "killed"].includes(run.status)) {
-      return [{ run: run.run, reason: `terminal-${run.status}`, suggested_inspect: `inspect target=run:${run.run} view=tail` }];
+      return [{
+        run: run.run,
+        reason: `terminal-${run.status}`,
+        suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+      }];
     }
     return [];
   });