@llblab/pi-actors 0.40.1 → 0.41.1

package/scripts/async-runner.mjs

@@ -13,6 +13,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   statSync,
 } from "node:fs";
 import { dirname, join, relative } from "node:path";
@@ -31,8 +32,11 @@ async function importRuntimeModule(name) {
   );
 }
 
-const { appendRecipeContextToPiArgs, materializePiPrintPromptArg } =
-  await importRuntimeModule("recipes-context");
+const {
+  appendRecipeContextToPiArgs,
+  attachPiSessionDir,
+  materializePiPrintPromptArg,
+} = await importRuntimeModule("recipes-context");
 const { buildReviewPreflightDiagnostic, formatReviewPreflightDiagnostic } =
   await importRuntimeModule("preflight-diagnostics");
 const { execCommandTemplate } = await importRuntimeModule("command-templates");
@@ -126,11 +130,24 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     });
   }
 
+  function commandSessionFiles(sessionDir) {
+    if (!sessionDir) return [];
+    try {
+      return readdirSync(sessionDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => relative(stateDir, join(sessionDir, entry.name)))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
   function commandEvidenceStartRecord({
     commandDetail,
     commandId,
     materialized,
     options,
+    sessionDir,
     stage,
     occurrence,
   }) {
@@ -155,6 +172,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
       attempts: [],
       semantic_acceptance:
         options?.evidenceContext?.acceptOutput === "review_evidence" ||
@@ -172,6 +190,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     options,
     result,
     rawExitCode,
+    sessionDir,
     stage,
     occurrence,
     startedAt,
@@ -234,6 +253,10 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(commandSessionFiles(sessionDir).length > 0
+        ? { session_files: commandSessionFiles(sessionDir) }
+        : {}),
       attempts,
       exit_code: rawExitCode ?? result.code,
       effective_exit_code: result.code,
@@ -301,21 +324,26 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   }
 
   async function observedExec(command, args, options) {
+    captureCounter += 1;
+    const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
     const contextArgs = appendRecipeContextToPiArgs(
       command,
       args,
       meta.recipe_context_records,
       options?.actorRecipeContext,
     );
-    const materialized = materializePiPrintPromptArg(
+    const session = attachPiSessionDir(
       command,
       contextArgs,
+      join(stateDir, "sessions", commandId),
+    );
+    const materialized = materializePiPrintPromptArg(
+      command,
+      session.args,
       promptFilePath,
     );
     const execArgs = materialized.args;
     const commandDetail = formatCommandDetail(command, execArgs);
-    captureCounter += 1;
-    const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
     const stage =
       options?.actorRecipeContext?.alias ||
       options?.actorRecipeContext?.name ||
@@ -346,6 +374,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       commandId,
       materialized,
       options,
+      sessionDir: session.sessionDir,
       stage,
       occurrence,
     });
@@ -357,6 +386,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       command: commandDetail,
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
     });
     progressRunning();
     const captureDir = join(stateDir, "captures", commandId);
@@ -400,6 +430,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       options,
       result,
       rawExitCode: rawResult.code,
+      sessionDir: session.sessionDir,
       stage,
       occurrence,
       startedAt: startedEvidence.started_at,
@@ -426,6 +457,10 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...captureDetails(result),
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(commandSessionFiles(session.sessionDir).length > 0
+        ? { session_files: commandSessionFiles(session.sessionDir) }
+        : {}),
       ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
     });
     outbox(

package/scripts/coordinator.mjs

@@ -238,14 +238,24 @@ function terminateProcessGroup(child, signal) {
   }
 }
 
-function runPi(prompt, model, thinking, ttlMs = 0) {
+function sessionKey(value) {
+  return String(value).replaceAll(/[^A-Za-z0-9_.-]+/g, "-");
+}
+
+function runPi(prompt, model, thinking, ttlMs = 0, sessionDir, ownerSessionId) {
   return new Promise((resolve) => {
     const args = [
       "--tools",
       "inspect,message",
       "--no-context-files",
       "--no-skills",
-      "--no-session",
+      ...(sessionDir
+        ? [
+            "--session-dir",
+            sessionDir,
+            ...(ownerSessionId ? ["--session-id", ownerSessionId] : []),
+          ]
+        : ["--no-session"]),
     ];
     if (model) {
       args.push("--model", model);
@@ -346,7 +356,14 @@ async function synthesize(config, locker) {
   }
   const transcript = await readRoomTranscript(config);
   const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
-  const result = await runPi(prompt, config.model, config.thinking, config.subagentTtlMs);
+  const result = await runPi(
+    prompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/coordinator-synthesis`,
+    config.ownerSessionId,
+  );
   const output = result.stdout.trim();
   const diagnostics = config.stats
     ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
@@ -443,7 +460,7 @@ async function updateInboxMessagesStatus(runId, branchName, ids, status) {
   });
 }
 
-async function executeParticipantPrompt(role, basePrompt, config) {
+async function executeParticipantPrompt(role, basePrompt, config, phase) {
   const branchName = role.name;
   const queuedMessages = await claimQueuedInboxMessages(
     config.runId,
@@ -469,7 +486,14 @@ async function executeParticipantPrompt(role, basePrompt, config) {
     finalPrompt += inboxSection;
   }
 
-  const result = await runPi(finalPrompt, config.model, config.thinking, config.subagentTtlMs);
+  const result = await runPi(
+    finalPrompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/${sessionKey(`${role.name}-${phase}`)}`,
+    config.ownerSessionId,
+  );
 
   if (claimedIds.length > 0) {
     const finalStatus = result.code === 0 ? "handled" : "failed";
@@ -488,7 +512,7 @@ async function participantRound(role, round, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses. End stdout with summary <=160 chars.`;
-  const result = await executeParticipantPrompt(role, prompt, config);
+  const result = await executeParticipantPrompt(role, prompt, config, `round-${round}`);
   if (config.stats) {
     config.stats.participantAttempts += 1;
     if (result.code === 0) config.stats.participantSuccess += 1;
@@ -506,14 +530,28 @@ async function participantJoin(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-  await runPi(joinPrompt, config.model, config.thinking, config.subagentTtlMs);
+  await runPi(
+    joinPrompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/${sessionKey(`${role.name}-join`)}`,
+    config.ownerSessionId,
+  );
 }
 
 async function participantLeave(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-  await runPi(leavePrompt, config.model, config.thinking, config.subagentTtlMs);
+  await runPi(
+    leavePrompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/${sessionKey(`${role.name}-leave`)}`,
+    config.ownerSessionId,
+  );
 }
 
 // 1. consensus / swarm mode: iterative chat in a room
@@ -601,7 +639,12 @@ async function runPool(config, locker) {
 
         const taskId = assignedTask.task;
         const prompt = `You are ${role.name}, ${role.persona}. You have been assigned task ${taskId}: "${assignedTask.task}". Solve it as part of the overall mission: ${config.mission}. End your response with a clear summary.`;
-        const result = await executeParticipantPrompt(role, prompt, config);
+        const result = await executeParticipantPrompt(
+          role,
+          prompt,
+          config,
+          `task-${taskId}`,
+        );
 
         process.stdout.write(
           `[${role.name} completed ${taskId}] code=${result.code}\n${result.stdout}\n`,
@@ -711,6 +754,9 @@ if (!config.model) {
   process.exit(2);
 }
 config.room = `room:${config.runId}`;
+config.ownerSessionId = String(
+  (await readJsonFile(`${runStateDir(config.runId)}/run.json`)).ownerId ?? "",
+);
 
 const failures = [];
 const locker = await startLocker(config);

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.40.1
+  version: 0.41.1
 ---
 
 # Actors (pi-actors)
@@ -125,21 +125,13 @@ Views:
 - `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
 - `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
-Actor inspector commands:
-
-- `/actors-inspector-toggle [rows]`: open/close the compact table or set row count; default is 12 log rows when no size is supplied.
-- `/actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|current-branch <name>|mention <text>`: narrow table previews without changing room/run state.
-- `/actors-inspect <number>`: open one visible row as a full-message view.
-
-The table is compact and optimistic by default: bounded body previews, capped noisy room rows, branch-local inbox previews, stable event ids in selected-message details, and an inline roster summary in the form `name/role` that wraps only when needed. Use `unread` for queued branch inbox work and `branch <name>` / `current-branch <name>` for one branch's room/direct/inbox traffic. Rows with `metadata.requires_response=true` show a `!` attention marker. `/actors-inspect <number>` marks that row read for the current session filter. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
-
-Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
+Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
 
 ## Runtime Communication Rules
 
 - Keep one public communication model: `spawn` creates actors, `message` sends typed envelopes, and `inspect` observes. Avoid adding public side channels or storage nouns when a normal actor address/view can express the operation.
 - Keep route and semantic type separate. Direct, room, coordinator, and session messages may share `type`; delivery behavior comes from `to`.
-- Treat inspector-visible communication logs as recipe evidence. Use `inspect room:<run> view=messages|previews`, `inspect run:<id> view=communication`, and the actor inspector table/full-message views to improve mailbox/artifact conventions after real runs.
+- Treat persisted communication logs as recipe evidence. Use `inspect room:<run> view=messages|previews` and `inspect run:<id> view=communication` to improve mailbox/artifact conventions after real runs.
 - Any UI, summary, or aggregate view that scans run directories must apply coordinator/session ownership filters before exposing summaries or body previews.
 - Treat `communication.json` as visible actor context, not a global mutable truth table. Run-level snapshots should identify the run actor; branch-local snapshots should identify the branch actor.
 - Prefer same-run provenance checks on lateral actor routes. If `from` is accepted for room or branch routes, validate that it belongs to the addressed run.
@@ -166,6 +158,8 @@ Controls:
 - `repeat`: repeated node expansion.
 - `output`: output behavior selection.
 - Command stdout/stderr use bounded tails plus complete spill files; tool/run diagnostics expose byte counts, truncation, and spill paths, while pipelines fail with `incomplete pipeline stdin` rather than consuming a partial tail.
+- Detached child `pi -p` commands receive isolated session storage under `sessions/command-NNN` in their owned run state, and command evidence records any resulting JSONL files. Coordinator-managed room/swarm participants use role/phase-scoped directories under the same run-local `sessions/` root so their turns remain discoverable too. Explicit `--no-session`, `--session`, `--session-id`, `--session-dir`, or `--fork` policy remains caller-owned and is never replaced.
+- Persisted child-session inspection follows the latest JSONL entry branch, correlates tool results by call id, bounds previews, and redacts common secret-bearing fields/text. Thinking content is evidence only when Pi persisted an explicit `thinking` block; never infer or advertise hidden reasoning.
 
 Placeholders:
 

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.40.1
+  version: 0.41.1
 ---
 
 # Swarm