@llblab/pi-actors 0.16.3 → 0.17.0

package/lib/actor-rooms.ts

@@ -0,0 +1,369 @@
+/**
+ * Actor room persistence helpers.
+ * Zones: room timelines, room rosters, cross-branch discovery state
+ * Owns small file-backed room state; routing policy stays in tools/runtime adapters.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { ActorMessage } from "./actor-messages.ts";
+
+export interface RoomMember {
+  address: string;
+  caps?: unknown;
+  claim?: unknown;
+  joined_at: string;
+  last_seen: string;
+  parent?: unknown;
+  role?: unknown;
+  status?: string;
+}
+
+export interface RoomTimelineEntry extends ActorMessage {
+  received_at: string;
+}
+
+export interface RoomAppendResult {
+  room: string;
+  message_count: number;
+  roster_count: number;
+  sent: true;
+}
+
+export interface RoomMessagePreview {
+  body_preview?: string;
+  from?: string;
+  summary?: string;
+  timestamp: string;
+  to: string;
+  type: string;
+}
+
+export interface RoomStatus {
+  room: string;
+  message_count: number;
+  roster_count: number;
+  last_message_at?: string;
+  last_message_from?: string;
+  last_message_summary?: string;
+  last_message_type?: string;
+}
+
+export interface RoomContact {
+  address: string;
+  caps?: unknown;
+  claim?: unknown;
+  parent?: unknown;
+  role?: unknown;
+  status?: string;
+}
+
+export interface ActorCommunicationSnapshot {
+  contacts?: RoomContact[];
+  parent?: string;
+  root: string;
+  self: string;
+  rooms: Array<{
+    address: string;
+    members?: RoomMember[];
+    name: string;
+  }>;
+  updated_at: string;
+}
+
+function roomDir(stateDir: string, room: string): string {
+  return path.join(stateDir, "rooms", room);
+}
+
+function messagesFile(stateDir: string, room: string): string {
+  return path.join(roomDir(stateDir, room), "messages.jsonl");
+}
+
+function rosterFile(stateDir: string, room: string): string {
+  return path.join(roomDir(stateDir, room), "roster.json");
+}
+
+function snapshotFile(stateDir: string): string {
+  return path.join(stateDir, "communication.json");
+}
+
+function branchSnapshotFile(stateDir: string, branch: string): string {
+  return path.join(stateDir, "branches", branch, "communication.json");
+}
+
+function branchIdFromAddress(address: string | undefined, run: string): string | undefined {
+  if (!address) return undefined;
+  const match = new RegExp(`^branch:${run}/(.+)$`).exec(address);
+  return match?.[1];
+}
+
+function ensureRoomDir(stateDir: string, room: string): void {
+  fs.mkdirSync(roomDir(stateDir, room), { recursive: true });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function runFromRoomAddress(address: string): string | undefined {
+  const match = /^room:([^/]+)(?:\/main)?$/.exec(address);
+  return match?.[1];
+}
+
+function readJsonFile<T>(file: string, fallback: T): T {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+function writeJsonFile(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function readRoomRoster(
+  stateDir: string,
+  room: string,
+): Record<string, RoomMember> {
+  return readJsonFile<Record<string, RoomMember>>(rosterFile(stateDir, room), {});
+}
+
+function writeRoomRoster(
+  stateDir: string,
+  room: string,
+  roster: Record<string, RoomMember>,
+): void {
+  ensureRoomDir(stateDir, room);
+  writeJsonFile(rosterFile(stateDir, room), roster);
+}
+
+function updateRosterForMessage(
+  stateDir: string,
+  room: string,
+  message: ActorMessage,
+  receivedAt: string,
+): Record<string, RoomMember> {
+  const roster = readRoomRoster(stateDir, room);
+  if (!message.from) return roster;
+  if (message.type === "actor.leave") {
+    delete roster[message.from];
+    writeRoomRoster(stateDir, room, roster);
+    return roster;
+  }
+  const body = asRecord(message.body);
+  const current = roster[message.from];
+  roster[message.from] = {
+    address: message.from,
+    joined_at: current?.joined_at ?? receivedAt,
+    last_seen: receivedAt,
+    ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
+    ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
+    ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
+    ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+    status: String(body.status ?? current?.status ?? "present"),
+  };
+  writeRoomRoster(stateDir, room, roster);
+  return roster;
+}
+
+export function appendRoomMessage(
+  stateDir: string,
+  room: string,
+  message: ActorMessage,
+): RoomAppendResult {
+  ensureRoomDir(stateDir, room);
+  const receivedAt = new Date().toISOString();
+  const entry: RoomTimelineEntry = { ...message, received_at: receivedAt };
+  fs.appendFileSync(messagesFile(stateDir, room), `${JSON.stringify(entry)}\n`);
+  const roster = updateRosterForMessage(stateDir, room, message, receivedAt);
+  const run = runFromRoomAddress(message.to);
+  if (run) {
+    writeCommunicationSnapshot(stateDir, run);
+    if (message.from && branchIdFromAddress(message.from, run)) {
+      writeBranchCommunicationSnapshot(stateDir, run, message.from);
+    }
+  }
+  return {
+    message_count: readRoomMessages(stateDir, room).length,
+    room,
+    roster_count: Object.keys(roster).length,
+    sent: true,
+  };
+}
+
+export function readRoomMessages(
+  stateDir: string,
+  room: string,
+  limit = 40,
+): RoomTimelineEntry[] {
+  try {
+    const lines = fs
+      .readFileSync(messagesFile(stateDir, room), "utf8")
+      .split("\n")
+      .filter(Boolean);
+    return lines.slice(-Math.max(1, limit)).map((line) => JSON.parse(line));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+function previewValue(value: unknown, maxLength = 120): string | undefined {
+  if (value === undefined) return undefined;
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  const compact = text.replaceAll(/\s+/g, " ").trim();
+  if (!compact) return undefined;
+  return compact.length > maxLength
+    ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
+    : compact;
+}
+
+export function readRoomMessagePreviews(
+  stateDir: string,
+  room: string,
+  limit = 40,
+): RoomMessagePreview[] {
+  return readRoomMessages(stateDir, room, limit).map((message) => ({
+    ...(previewValue(message.body) ? { body_preview: previewValue(message.body) } : {}),
+    ...(message.from ? { from: message.from } : {}),
+    ...(message.summary ? { summary: message.summary } : {}),
+    timestamp: message.received_at,
+    to: message.to,
+    type: message.type,
+  }));
+}
+
+export function getRoomStatus(stateDir: string, room: string): RoomStatus {
+  const messages = readRoomMessages(stateDir, room, Number.MAX_SAFE_INTEGER);
+  const last = messages[messages.length - 1];
+  return {
+    ...(last
+      ? {
+          last_message_at: last.received_at,
+          ...(last.from ? { last_message_from: last.from } : {}),
+          ...(last.summary ? { last_message_summary: last.summary } : {}),
+          last_message_type: last.type,
+        }
+      : {}),
+    message_count: messages.length,
+    room,
+    roster_count: Object.keys(readRoomRoster(stateDir, room)).length,
+  };
+}
+
+export function ensureRoomMember(
+  stateDir: string,
+  run: string,
+  room: string,
+  address: string,
+  body: Record<string, unknown>,
+  summary: string,
+): RoomAppendResult {
+  const roster = readRoomRoster(stateDir, room);
+  if (roster[address]) {
+    return {
+      message_count: readRoomMessages(stateDir, room).length,
+      room,
+      roster_count: Object.keys(roster).length,
+      sent: true,
+    };
+  }
+  return appendRoomMessage(stateDir, room, {
+    body,
+    from: address,
+    summary,
+    to: `room:${run}`,
+    type: "actor.join",
+  });
+}
+
+export function ensureDefaultRoom(stateDir: string, run: string): RoomAppendResult {
+  return ensureRoomMember(
+    stateDir,
+    run,
+    "main",
+    `run:${run}`,
+    { role: "run", status: "present" },
+    "Run joined default room",
+  );
+}
+
+export function readCommunicationSnapshot(
+  stateDir: string,
+): ActorCommunicationSnapshot | undefined {
+  try {
+    return JSON.parse(
+      fs.readFileSync(snapshotFile(stateDir), "utf8"),
+    ) as ActorCommunicationSnapshot;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export function readRoomContacts(
+  stateDir: string,
+  room: string,
+  self?: string,
+): RoomContact[] {
+  return Object.values(readRoomRoster(stateDir, room))
+    .filter((member) => member.address !== self)
+    .map((member) => ({
+      address: member.address,
+      ...(member.caps !== undefined ? { caps: member.caps } : {}),
+      ...(member.claim !== undefined ? { claim: member.claim } : {}),
+      ...(member.parent !== undefined ? { parent: member.parent } : {}),
+      ...(member.role !== undefined ? { role: member.role } : {}),
+      ...(member.status !== undefined ? { status: member.status } : {}),
+    }));
+}
+
+function buildCommunicationSnapshot(
+  stateDir: string,
+  run: string,
+  self: string,
+): ActorCommunicationSnapshot {
+  const mainRoster = Object.values(readRoomRoster(stateDir, "main"));
+  const contacts = readRoomContacts(stateDir, "main", self);
+  return {
+    ...(contacts.length > 0 ? { contacts } : {}),
+    ...(self !== `run:${run}` ? { parent: `run:${run}` } : {}),
+    root: `run:${run}`,
+    self,
+    rooms: [
+      {
+        address: `room:${run}`,
+        ...(mainRoster.length > 0 ? { members: mainRoster } : {}),
+        name: "main",
+      },
+    ],
+    updated_at: new Date().toISOString(),
+  };
+}
+
+export function writeCommunicationSnapshot(
+  stateDir: string,
+  run: string,
+): ActorCommunicationSnapshot {
+  const snapshot = buildCommunicationSnapshot(stateDir, run, `run:${run}`);
+  writeJsonFile(snapshotFile(stateDir), snapshot);
+  return snapshot;
+}
+
+export function writeBranchCommunicationSnapshot(
+  stateDir: string,
+  run: string,
+  self: string,
+): ActorCommunicationSnapshot {
+  const branch = branchIdFromAddress(self, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
+  const snapshot = buildCommunicationSnapshot(stateDir, run, self);
+  writeJsonFile(branchSnapshotFile(stateDir, branch), snapshot);
+  return snapshot;
+}

package/lib/async-runs.ts

@@ -296,6 +296,7 @@ function prepareStateDirForStart(stateDir: string): void {
   }
   for (const file of [
     "events.jsonl",
+    "inbox.jsonl",
     "outbox.jsonl",
     "progress.json",
     "result.json",
@@ -331,6 +332,9 @@ export function startRun(
   const argv = ["--experimental-strip-types", RUNNER_PATH, stateDir];
   const values = {
     ...(startParams.values || {}),
+    actor_address: `run:${run}`,
+    communication_file: join(stateDir, "communication.json"),
+    default_room: `room:${run}`,
     run_id: run,
     state_dir: stateDir,
   };
@@ -481,6 +485,7 @@ export function getRunStatus(runOrDir: string): Record<string, unknown> {
   return {
     ...meta,
     eventsFile: join(stateDir, "events.jsonl"),
+    inboxFile: join(stateDir, "inbox.jsonl"),
     outboxFile: join(stateDir, "outbox.jsonl"),
     progress: readJson(join(stateDir, "progress.json")) || null,
     result: result || null,
@@ -632,11 +637,22 @@ export function sendRunMessage(
     const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
       trimmedMessage,
     );
+    const ts = new Date().toISOString();
     writeFileSync(
       join(stateDir, "events.jsonl"),
-      `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts: new Date().toISOString() })}\n`,
+      `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`,
       { flag: "a" },
     );
+    try {
+      const envelope = JSON.parse(message) as Record<string, unknown>;
+      writeFileSync(
+        join(stateDir, "inbox.jsonl"),
+        `${JSON.stringify({ ...envelope, received_at: ts })}\n`,
+        { flag: "a" },
+      );
+    } catch {
+      // Plain control lines are already represented in events.jsonl.
+    }
     if (terminalMessage) {
       markTerminalHandled(stateDir, {
         event: "run.message",

package/lib/config.ts

@@ -1,7 +1,7 @@
 /**
  * Persistent tool registry config helpers
  * Zones: registry config, persistence, migration boundary
- * Owns actors-tools.json loading, normalization, unsupported-shape rejection, and serialization
+ * Owns registered-tool config loading, normalization, unsupported-shape rejection, and serialization
  */
 
 import { existsSync, readFileSync } from "node:fs";

package/lib/paths.ts

@@ -17,7 +17,7 @@ export function getAgentDir(
 }
 
 export function getConfigPath(agentDir = getAgentDir()): string {
-  return join(agentDir, "actors-tools.json");
+  return join(agentDir, "legacy-tool-registry.json");
 }
 
 export function getExtensionTmpDir(

package/lib/prompts.ts

@@ -24,11 +24,12 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - 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.
+- ~/.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.
 - 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 writes user recipe files in ~/.pi/agent/recipes; that root is the default tool set, while packaged recipes are the lower-priority standard library.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged recipes are lower-priority components, not tools by location.
 - 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.`;

package/lib/recipe-discovery.ts

@@ -74,7 +74,7 @@ function listRecipeFiles(root: string): string[] {
       (entry) =>
         entry.isFile() &&
         entry.name.endsWith(".json") &&
-        entry.name !== "actors-tools-migration-report.json",
+        entry.name !== "legacy-tool-registry-migration-report.json",
     )
     .map((entry) => join(root, entry.name))
     .sort();
@@ -192,7 +192,87 @@ export function discoverRecipes(roots: string[]): RecipeDiscoveryResult {
   return discoverRecipeSources(roots.map((root) => ({ root })));
 }
 
+function recipeUsage(config: TemplateRecipeConfig | undefined): Record<string, unknown> | undefined {
+  const usage = (config as { usage?: unknown } | undefined)?.usage;
+  return usage && typeof usage === "object" && !Array.isArray(usage)
+    ? (usage as Record<string, unknown>)
+    : undefined;
+}
+
+function cleanupRecommendation(entry: DiscoveredRecipe): Record<string, unknown> | undefined {
+  if (entry.invalid) {
+    return {
+      id: entry.id,
+      path: entry.path,
+      reason: "invalid recipe blocks lower-priority entries with the same id",
+      actions: ["fix", "delete", "archive"],
+    };
+  }
+  if (entry.shadowed) {
+    return {
+      id: entry.id,
+      path: entry.path,
+      reason: "shadowed by a higher-priority recipe",
+      actions: ["merge", "delete", "archive"],
+    };
+  }
+  if (entry.disabled) {
+    return {
+      id: entry.id,
+      path: entry.path,
+      reason: "disabled recipe is retained but not exposed as a tool",
+      actions: ["keep disabled", "delete", "archive"],
+    };
+  }
+  const usage = recipeUsage(entry.config);
+  const calls = Number(usage?.calls ?? 0);
+  if (entry.mutableUsage && entry.tool && calls === 0) {
+    return {
+      id: entry.id,
+      path: entry.path,
+      reason: "active user tool has no recorded launches",
+      actions: ["keep as tool", "set tool false", "delete", "archive"],
+    };
+  }
+  if (entry.mutableUsage && !entry.tool) {
+    return {
+      id: entry.id,
+      path: entry.path,
+      reason: "user recipe is a component, not an active tool",
+      actions: ["keep component", "enable tool", "merge", "delete", "archive"],
+    };
+  }
+  if (entry.shadows.length > 0) {
+    return {
+      id: entry.id,
+      path: entry.path,
+      reason: `overrides ${entry.shadows.length} lower-priority recipe(s)`,
+      actions: ["keep override", "merge", "delete", "archive"],
+    };
+  }
+  return undefined;
+}
+
+function recommendationForEntry(
+  entry: DiscoveredRecipe,
+  activePath: string | undefined,
+): Record<string, unknown> | undefined {
+  const recommendation = cleanupRecommendation(entry);
+  if (!recommendation) return undefined;
+  if (entry.shadowed && activePath) {
+    return {
+      ...recommendation,
+      reason: `shadowed by ${activePath}`,
+    };
+  }
+  return recommendation;
+}
+
 export function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown> {
+  const recommendations = result.entries
+    .map((entry) => recommendationForEntry(entry, result.active.get(entry.id)?.path))
+    .filter((entry): entry is Record<string, unknown> => Boolean(entry))
+    .sort((a, b) => String(a.id).localeCompare(String(b.id)) || String(a.path).localeCompare(String(b.path)));
   return {
     active: [...result.active.values()].map((entry) => ({
       id: entry.id,
@@ -202,6 +282,7 @@ export function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string
       disabled: entry.disabled,
       invalid: entry.invalid,
       shadows: entry.shadows,
+      ...(recipeUsage(entry.config) ? { usage: recipeUsage(entry.config) } : {}),
     })).sort((a, b) => a.id.localeCompare(b.id)),
     shadowed: result.entries
       .filter((entry) => entry.shadowed)
@@ -215,6 +296,7 @@ export function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string
       .filter((entry) => entry.disabled)
       .map((entry) => ({ id: entry.id, path: entry.path }))
       .sort((a, b) => a.id.localeCompare(b.id)),
+    recommendations,
     diagnostics: result.diagnostics,
   };
 }

package/lib/recipe-migration.ts

@@ -1,5 +1,5 @@
 /**
- * Legacy actors-tools.json to recipe-file migration helpers
+ * Legacy tool-registry to recipe-file migration helpers
  * Zones: registry migration, recipe persistence, compatibility diagnostics
  * Owns one-way migration from legacy tool registry entries into user recipe files
  */
@@ -98,7 +98,7 @@ export function migrateLegacyToolRegistry(
 
   if (loaded.tools.size === 0) result.skipped.push(basename(configPath));
 
-  const reportPath = join(recipeRoot, "actors-tools-migration-report.json");
+  const reportPath = join(recipeRoot, "legacy-tool-registry-migration-report.json");
   writeJsonAtomic(reportPath, {
     source: configPath,
     migrated: result.migrated,

package/lib/recipe-references.ts

@@ -50,6 +50,7 @@ export interface TemplateRecipeDefinition {
   recover?: CommandTemplateValue;
   repeat?: number;
   values?: Record<string, unknown>;
+  usage?: Record<string, unknown>;
 }
 
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
@@ -597,6 +598,7 @@ export function readResolvedRecipeConfig(
       ? { repeat: substituted.repeat }
       : {}),
     ...(isRecord(substituted.values) ? { values: substituted.values } : {}),
+    ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
   };
 }
 

package/lib/recipe-usage.ts

@@ -4,6 +4,7 @@
  * Owns lightweight launch counters for user-owned recipe files
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 
 import { writeJsonAtomic } from "./file-state.ts";
@@ -11,6 +12,8 @@ import { writeJsonAtomic } from "./file-state.ts";
 interface RecipeUsageRecord {
   calls?: number;
   last_called?: string;
+  fingerprint?: string;
+  reset_at?: string;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -23,18 +26,37 @@ function normalizeCalls(value: unknown): number {
     : 0;
 }
 
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (!isRecord(value)) return JSON.stringify(value);
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(",")}}`;
+}
+
+function getRecipeFingerprint(raw: Record<string, unknown>): string {
+  const { usage: _usage, ...content } = raw;
+  return createHash("sha256").update(stableStringify(content)).digest("hex");
+}
+
 export function recordRecipeLaunch(path: string, now = new Date()): boolean {
   if (!existsSync(path)) return false;
   try {
     const raw = JSON.parse(readFileSync(path, "utf8"));
     if (!isRecord(raw)) return false;
     const usage: RecipeUsageRecord = isRecord(raw.usage) ? raw.usage : {};
+    const fingerprint = getRecipeFingerprint(raw);
+    const changed = typeof usage.fingerprint === "string" && usage.fingerprint !== fingerprint;
+    const nowIso = now.toISOString();
     writeJsonAtomic(path, {
       ...raw,
       usage: {
         ...usage,
-        calls: normalizeCalls(usage.calls) + 1,
-        last_called: now.toISOString(),
+        calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
+        last_called: nowIso,
+        fingerprint,
+        ...(changed ? { reset_at: nowIso } : {}),
       },
     });
     return true;