@llblab/pi-actors 0.40.0 → 0.41.0

package/lib/inspector.ts

@@ -12,6 +12,7 @@ import { visibleWidth } from "@earendil-works/pi-tui";
 import type { ActorMessage } from "./messages.ts";
 import * as Limits from "./limits.ts";
 import * as Paths from "./paths.ts";
+import * as SessionEvidence from "./session-evidence.ts";
 import {
   readJsonFileResilient,
   readJsonlFileResilient,
@@ -63,6 +64,7 @@ export interface ActorInspectorPreviewReadOptions {
   ownerId?: string;
   branch?: string;
   currentRunOnly?: boolean;
+  run?: string;
   channels?: ActorInspectorPreview["channel"][];
   mention?: string;
   readKeys?: Iterable<string>;
@@ -70,221 +72,144 @@ export interface ActorInspectorPreviewReadOptions {
   unreadOnly?: boolean;
 }
 
-export interface ActorInspectorControllerState {
-  branch?: string;
-  channels?: ActorInspectorPreview["channel"][];
-  mention?: string;
-  readKeys: Set<string>;
-  roomLimitPerRun: number;
-  rows: number;
-  selectedSequence?: number;
-  unreadOnly: boolean;
-  visible: boolean;
-}
-
-export interface ActorInspectorCommandResult {
-  notify: string;
-  type: "info" | "warning";
-  update: boolean;
-}
-
-export const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-
-export const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS = {
-  filter:
-    "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
-  inspect: "Inspect actor message by visible number",
-  toggle: "Toggle actor inspector widget; optional row count",
-};
-
-export function createActorInspectorControllerState(): ActorInspectorControllerState {
-  return {
-    readKeys: new Set<string>(),
-    roomLimitPerRun: DEFAULT_ACTOR_INSPECTOR_ROWS,
-    rows: DEFAULT_ACTOR_INSPECTOR_ROWS,
-    unreadOnly: false,
-    visible: false,
-  };
+export interface ActorInspectorRunItem {
+  run: string;
+  status: string;
+  updatedAt?: string;
 }
 
-export function getActorInspectorPreviewOptions(
-  state: ActorInspectorControllerState,
+export function readActorInspectorRuns(
+  stateRoot: string,
   ownerId: string,
-): ActorInspectorPreviewReadOptions {
-  return {
-    channels: state.channels,
-    currentRunOnly: true,
-    branch: state.branch,
-    mention: state.mention,
-    ownerId,
-    readKeys: state.readKeys,
-    roomLimitPerRun: state.roomLimitPerRun,
-    unreadOnly: state.unreadOnly,
-  };
-}
-
-export function handleActorInspectorToggle(
-  state: ActorInspectorControllerState,
-  args: unknown,
-): ActorInspectorCommandResult {
-  const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-  if (String(raw).trim()) {
-    const rows = Number.parseInt(String(raw), 10);
-    if (!Number.isFinite(rows) || rows <= 0) {
-      return {
-        notify: "Usage: /actors-inspector-toggle [rows] where rows > 0",
-        type: "warning",
-        update: false,
-      };
-    }
-    state.rows = rows;
-    state.roomLimitPerRun = rows;
-    state.selectedSequence = undefined;
-    state.visible = true;
-    return {
-      notify: `Actor inspector rows ${rows}`,
-      type: "info",
-      update: true,
-    };
-  }
-  if (state.selectedSequence !== undefined) {
-    state.selectedSequence = undefined;
-    state.visible = true;
-    return { notify: "Actor inspector table", type: "info", update: true };
-  }
-  if (state.visible) state.visible = false;
-  else {
-    state.rows = DEFAULT_ACTOR_INSPECTOR_ROWS;
-    state.roomLimitPerRun = DEFAULT_ACTOR_INSPECTOR_ROWS;
-    state.visible = true;
-  }
-  return {
-    notify: `Actor inspector ${state.visible ? "shown" : "hidden"}`,
-    type: "info",
-    update: true,
-  };
-}
-
-export function handleActorInspectorFilter(
-  state: ActorInspectorControllerState,
-  args: unknown,
-): ActorInspectorCommandResult {
-  const parts = Array.isArray(args)
-    ? args.map(String)
-    : String(args ?? "").split(/\s+/);
-  const mode = (parts[0] ?? "").trim().toLowerCase();
-  if (!mode || mode === "all" || mode === "clear") {
-    state.channels = undefined;
-    state.mention = undefined;
-    state.branch = undefined;
-    state.unreadOnly = false;
-  } else if (mode === "room" || mode === "direct" || mode === "broadcast") {
-    state.channels = [mode];
-    state.mention = undefined;
-  } else if (mode === "unread") {
-    state.unreadOnly = true;
-  } else if (mode === "branch" || mode === "current-branch") {
-    const branch = parts.slice(1).join(" ").trim();
-    if (!branch) {
-      return {
-        notify: `Usage: /actors-inspector-filter ${mode} <branch-name>`,
-        type: "warning",
-        update: false,
-      };
-    }
-    state.branch = branch;
-  } else if (mode === "mention") {
-    const mention = parts.slice(1).join(" ").trim();
-    if (!mention) {
-      return {
-        notify: "Usage: /actors-inspector-filter mention <text>",
-        type: "warning",
-        update: false,
-      };
-    }
-    state.channels = undefined;
-    state.mention = mention;
-  } else {
-    return {
-      notify:
-        "Usage: /actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|mention <text>",
-      type: "warning",
-      update: false,
-    };
+): ActorInspectorRunItem[] {
+  try {
+    return fs
+      .readdirSync(stateRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .flatMap((entry) => {
+        const stateDir = path.join(stateRoot, entry.name);
+        if (!matchesOwner(stateDir, ownerId)) return [];
+        const progress = readJsonFileResilient<Record<string, unknown>>(
+          path.join(stateDir, "progress.json"),
+          {},
+        ).value;
+        const result = readJsonFileResilient<Record<string, unknown>>(
+          path.join(stateDir, "result.json"),
+          {},
+        ).value;
+        return [{
+          run: entry.name,
+          status: String(progress.phase ?? (Object.keys(result).length ? "terminal" : "unknown")),
+          ...(typeof progress.updatedAt === "string"
+            ? { updatedAt: progress.updatedAt }
+            : typeof result.completedAt === "string"
+              ? { updatedAt: result.completedAt }
+              : {}),
+        }];
+      })
+      .sort((left, right) =>
+        String(left.updatedAt ?? "").localeCompare(String(right.updatedAt ?? "")),
+      );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    return [];
   }
-  state.selectedSequence = undefined;
-  state.visible = true;
-  return {
-    notify: `Actor inspector filter ${mode || "all"}`,
-    type: "info",
-    update: true,
-  };
 }
 
-export function handleActorInspectorInspect(
-  state: ActorInspectorControllerState,
-  args: unknown,
-  previews: ActorInspectorPreview[],
-): ActorInspectorCommandResult {
-  const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-  return selectActorInspectorSequence(
-    state,
-    Number.parseInt(String(raw), 10),
-    previews,
-  );
+export interface ActorInspectorTurnItem extends SessionEvidence.SessionEvidenceTurn {
+  commandId: string;
+  diagnostics: string[];
+  promptBytes?: number;
+  promptFile?: string;
+  recipeContext?: unknown;
+  sessionFile: string;
+  sessionTruncated: boolean;
+  stage?: string;
 }
 
-export function selectActorInspectorSequence(
-  state: ActorInspectorControllerState,
-  sequence: number,
-  previews: ActorInspectorPreview[],
-): ActorInspectorCommandResult {
-  if (!Number.isFinite(sequence) || sequence <= 0) {
-    return {
-      notify: "Usage: /actors-inspect <number>",
-      type: "warning",
-      update: false,
-    };
+function ownedSessionPath(
+  stateDir: string,
+  sessionFile: string,
+): string | undefined {
+  if (path.isAbsolute(sessionFile)) return undefined;
+  const sessionsRoot = path.resolve(stateDir, "sessions");
+  const resolved = path.resolve(stateDir, sessionFile);
+  if (!resolved.startsWith(`${sessionsRoot}${path.sep}`)) return undefined;
+  try {
+    const canonicalRoot = fs.realpathSync(sessionsRoot);
+    const canonicalFile = fs.realpathSync(resolved);
+    return canonicalFile.startsWith(`${canonicalRoot}${path.sep}`)
+      ? canonicalFile
+      : undefined;
+  } catch {
+    return undefined;
   }
-  const preview = previews.find((item) => item.sequence === sequence);
-  if (preview) state.readKeys.add(inspectorPreviewReadKey(preview));
-  state.selectedSequence = sequence;
-  state.visible = true;
-  return {
-    notify: `Actor inspect item ${sequence}`,
-    type: "info",
-    update: true,
-  };
 }
 
-export function renderActorInspectorPanel(input: {
-  stateRoot: string;
-  state: ActorInspectorControllerState;
-  ownerId: string;
-  width: number;
-  style: ActorInspectorWidgetStyle;
-}): string[] {
-  const previews = readActorInspectorPreviews(
-    input.stateRoot,
-    input.state.rows,
-    getActorInspectorPreviewOptions(input.state, input.ownerId),
+export function readActorInspectorTurns(stateDir: string): ActorInspectorTurnItem[] {
+  const evidence = readJsonFileResilient<Record<string, unknown>>(
+    path.join(stateDir, "review-evidence.json"),
+    {},
+  ).value;
+  const commands = Array.isArray(evidence.commands)
+    ? (evidence.commands as Array<Record<string, unknown>>)
+    : [];
+  const recordedFiles = new Set(
+    commands.flatMap((command) =>
+      (Array.isArray(command.session_files) ? command.session_files : []).filter(
+        (file): file is string => typeof file === "string",
+      ),
+    ),
   );
-  const rows =
-    (input.state.selectedSequence !== undefined
-      ? renderInspectorItemView(previews, input.width, input.style, {
-          sequence: input.state.selectedSequence,
-        })
-      : renderInspectorWidget(previews, input.width, input.style)) ?? [];
-  const run = previews[0]?.run;
-  const roster =
-    input.state.selectedSequence === undefined && run
-      ? renderInspectorRosterPanel(
-          readActorInspectorRoster(input.stateRoot, run),
-          input.width,
-          input.style,
-        )
-      : undefined;
-  return roster ? [...roster, ...rows] : rows;
+  let discoveredCommands: Array<Record<string, unknown>> = [];
+  try {
+    const sessionsDir = path.join(stateDir, "sessions");
+    discoveredCommands = fs
+      .readdirSync(sessionsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .flatMap((entry) => {
+        const files = fs
+          .readdirSync(path.join(sessionsDir, entry.name), {
+            withFileTypes: true,
+          })
+          .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
+          .map((file) => path.join("sessions", entry.name, file.name))
+          .filter((file) => !recordedFiles.has(file));
+        return files.length > 0
+          ? [{ id: entry.name, session_files: files, stage: "subagent" }]
+          : [];
+      });
+  } catch {
+    discoveredCommands = [];
+  }
+  return [...commands, ...discoveredCommands].flatMap((command) =>
+    (Array.isArray(command.session_files) ? command.session_files : [])
+      .filter((file): file is string => typeof file === "string")
+      .flatMap((file) => {
+        const sessionPath = ownedSessionPath(stateDir, file);
+        if (!sessionPath) return [];
+        const session = SessionEvidence.readSessionEvidence(sessionPath);
+        return session.turns.map((turn) => ({
+          ...turn,
+          commandId: String(command.id ?? "unknown"),
+          diagnostics: session.diagnostics.map((item) =>
+            `${item.line === undefined ? "" : `line ${item.line}: `}${item.message}`,
+          ),
+          ...(typeof command.prompt_bytes === "number"
+            ? { promptBytes: command.prompt_bytes }
+            : {}),
+          ...(typeof command.prompt_file === "string"
+            ? { promptFile: command.prompt_file }
+            : {}),
+          ...(command.recipe_context !== undefined
+            ? { recipeContext: command.recipe_context }
+            : {}),
+          sessionFile: file,
+          sessionTruncated: session.truncated,
+          ...(typeof command.stage === "string" ? { stage: command.stage } : {}),
+        }));
+      }),
+  ).map((turn, index) => ({ ...turn, index: index + 1 }));
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -302,7 +227,9 @@ function previewValue(
   maxLength = Limits.INSPECTOR_BODY_PREVIEW_CHARS,
 ): string | undefined {
   if (value === undefined) return undefined;
-  const text = typeof value === "string" ? value : JSON.stringify(value);
+  const redacted = SessionEvidence.redactSessionEvidenceValue(value);
+  const text =
+    typeof redacted === "string" ? redacted : JSON.stringify(redacted);
   const compact = text.replaceAll(/\s+/g, " ").trim();
   if (!compact) return undefined;
   return compact.length > maxLength
@@ -606,6 +533,7 @@ export function readActorInspectorPreviews(
       .flatMap((entry) => {
         const stateDir = path.join(stateRoot, entry.name);
         if (!matchesOwner(stateDir, options.ownerId)) return [];
+        if (options.run && entry.name !== options.run) return [];
         return [
           ...readRoomPreviews(entry.name, stateDir),
           ...readInboxPreviews(entry.name, stateDir),

package/lib/limits.ts

@@ -10,3 +10,6 @@ export const COMPACT_PREVIEW_CHARS = 160;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export const SESSION_EVIDENCE_MAX_TURNS = 100;
+export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
+export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/lib/observability.ts

@@ -81,7 +81,7 @@ export interface RunUiSnapshot {
 
 export interface RunUiNotificationSink {
   notify(message: string, level: "info" | "warning" | "error"): void;
-  sendSteering(message: {
+  sendFollowUp(message: {
     customType: string;
     content: string;
     display: true;
@@ -140,7 +140,7 @@ export function deliverRunTransitionNotifications(
     const text = formatRunTransitionMessage(transition);
     sink.notify(text, getRunTransitionNotificationType(transition));
     if (!shouldSendRunTransitionFollowUp(transition)) continue;
-    sink.sendSteering({
+    sink.sendFollowUp({
       customType: "pi-actors-run",
       content: text,
       display: true,
@@ -164,7 +164,7 @@ export function deliverRunOutboxNotifications(
     const text = formatRunOutboxMessage(event);
     sink.notify(text, getRunOutboxNotificationType(event));
     if (!shouldSendRunOutboxFollowUp(event)) continue;
-    sink.sendSteering({
+    sink.sendFollowUp({
       customType: "pi-actors-run-message",
       content: text,
       display: true,

package/lib/pi.ts

@@ -13,7 +13,7 @@ export type { ExtensionAPI, ExtensionContext };
 
 export interface PiNotificationSink {
   notify(message: string, level: "info" | "warning" | "error"): void;
-  sendSteering(message: {
+  sendFollowUp(message: {
     customType: string;
     content: string;
     display: true;
@@ -31,9 +31,9 @@ export function createNotificationSink(
 ): PiNotificationSink {
   return {
     notify: (message, level) => ctx.ui.notify(message, level),
-    sendSteering: (message) =>
+    sendFollowUp: (message) =>
       pi.sendMessage(message, {
-        deliverAs: "steer",
+        deliverAs: "followUp",
         triggerTurn: true,
       }),
   };

package/lib/prompts.ts

@@ -22,17 +22,17 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - 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, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
+- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. When a deferred actor result gates the next step, wait for its terminal steering notification; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
-- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
+- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",

package/lib/recipes-context.ts

@@ -167,6 +167,31 @@ export function appendRecipeContextToPiArgs(
   return next;
 }
 
+export interface ManagedPiSessionArgs {
+  args: string[];
+  sessionDir?: string;
+}
+
+const PI_SESSION_POLICY_FLAGS = new Set([
+  "--fork",
+  "--no-session",
+  "--session",
+  "--session-dir",
+  "--session-id",
+]);
+
+export function attachPiSessionDir(
+  command: string,
+  args: string[],
+  sessionDir: string,
+): ManagedPiSessionArgs {
+  if (!isPiCommand(command) || findPiPrintPromptIndex(args) === undefined) {
+    return { args };
+  }
+  if (args.some((arg) => PI_SESSION_POLICY_FLAGS.has(arg))) return { args };
+  return { args: ["--session-dir", sessionDir, ...args], sessionDir };
+}
+
 export interface MaterializedPiPrintPromptArgs {
   args: string[];
   promptBytes?: number;