@llblab/pi-actors 0.29.3 → 0.30.1

package/lib/actor-inspector-tui.ts

@@ -11,7 +11,10 @@ import { visibleWidth } from "@earendil-works/pi-tui";
 import type { ActorMessage } from "./actor-messages.ts";
 import * as Limits from "./limits.ts";
 import * as Paths from "./paths.ts";
-import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.ts";
+import {
+  readJsonFileResilient,
+  readJsonlFileResilient,
+} from "./state-readers.ts";
 
 export interface ActorInspectorPreview {
   body_preview?: string;
@@ -66,6 +69,223 @@ 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 function getActorInspectorPreviewOptions(
+  state: ActorInspectorControllerState,
+  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,
+    };
+  }
+  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 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,
+    };
+  }
+  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),
+  );
+  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;
+}
+
 function asRecord(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)

package/lib/observability.ts

@@ -4,7 +4,13 @@
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  watch,
+  type FSWatcher,
+} from "node:fs";
 import {
   basename,
   dirname,
@@ -58,6 +64,108 @@ export interface RunSummary {
   total: number;
 }
 
+export interface RunUiObservationState {
+  eventLines: Map<string, number>;
+  frame: number;
+  observed: Map<string, RunObservedStatus>;
+  outboxEventIds: Map<string, Set<string>>;
+}
+
+export interface RunUiSnapshot {
+  outboxEvents: RunOutboxEvent[];
+  status: string | undefined;
+  summary: RunSummary;
+  transitions: RunTransition[];
+}
+
+export interface RunUiNotificationSink {
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  sendFollowUp(message: {
+    customType: string;
+    content: string;
+    display: true;
+    details: unknown;
+  }): void;
+}
+
+export function createRunUiObservationState(): RunUiObservationState {
+  return {
+    eventLines: new Map<string, number>(),
+    frame: 0,
+    observed: new Map<string, RunObservedStatus>(),
+    outboxEventIds: new Map<string, Set<string>>(),
+  };
+}
+
+export function readRunUiSnapshot(
+  state: RunUiObservationState,
+  ownerId: string,
+): RunUiSnapshot {
+  const summary = summarizeRuns(undefined, ownerId);
+  const status = renderRunStatus(summary, state.frame++);
+  return {
+    outboxEvents: detectRunOutboxEvents(
+      state.eventLines,
+      summary,
+      state.outboxEventIds,
+    ),
+    status,
+    summary,
+    transitions: detectRunTransitions(state.observed, summary),
+  };
+}
+
+export function pruneRunUiObservationState(
+  state: RunUiObservationState,
+  snapshot: Pick<RunUiSnapshot, "summary" | "transitions">,
+): void {
+  pruneRunObservationState(
+    state.observed,
+    state.eventLines,
+    snapshot.summary,
+    snapshot.transitions.map(
+      (transition) => transition.stateDir ?? transition.run,
+    ),
+    state.outboxEventIds,
+  );
+}
+
+export function deliverRunTransitionNotifications(
+  transitions: RunTransition[],
+  sink: RunUiNotificationSink,
+): void {
+  for (const transition of transitions) {
+    if (!shouldNotifyRunTransition(transition)) continue;
+    const text = formatRunTransitionMessage(transition);
+    sink.notify(text, getRunTransitionNotificationType(transition));
+    if (!shouldSendRunTransitionFollowUp(transition)) continue;
+    sink.sendFollowUp({
+      customType: "pi-actors-run",
+      content: text,
+      display: true,
+      details: transition,
+    });
+  }
+}
+
+export function deliverRunOutboxNotifications(
+  events: RunOutboxEvent[],
+  sink: RunUiNotificationSink,
+): void {
+  for (const event of events) {
+    if (!shouldNotifyRunOutboxEvent(event)) continue;
+    const text = formatRunOutboxMessage(event);
+    sink.notify(text, getRunOutboxNotificationType(event));
+    if (!shouldSendRunOutboxFollowUp(event)) continue;
+    sink.sendFollowUp({
+      customType: "pi-actors-run-message",
+      content: text,
+      display: true,
+      details: event,
+    });
+  }
+}
+
 export interface RunRetirementCandidate {
   activeSubagents: number;
   childRuns: number;
@@ -74,6 +182,58 @@ export interface RunRetirementExecution {
   stateDir: string;
 }
 
+export interface RunStateWatcher {
+  close(): void;
+  refresh(): void;
+}
+
+export function createRunStateWatcher(input: {
+  stateRoot?: string;
+  onChange: () => void;
+}): RunStateWatcher {
+  const stateRoot = input.stateRoot ?? Paths.getRunStateRoot();
+  let stateRootWatcher: FSWatcher | undefined;
+  const runDirWatchers = new Map<string, FSWatcher>();
+  const close = (): void => {
+    stateRootWatcher?.close();
+    stateRootWatcher = undefined;
+    for (const watcher of runDirWatchers.values()) watcher.close();
+    runDirWatchers.clear();
+  };
+  const watchRunDir = (stateDir: string): void => {
+    if (runDirWatchers.has(stateDir) || !existsSync(stateDir)) return;
+    try {
+      const watcher = watch(stateDir, input.onChange);
+      watcher.on("error", () => {
+        watcher.close();
+        runDirWatchers.delete(stateDir);
+      });
+      runDirWatchers.set(stateDir, watcher);
+    } catch {
+      // Watching is best-effort; explicit inspect remains available.
+    }
+  };
+  function refresh(): void {
+    if (!existsSync(stateRoot)) return;
+    if (!stateRootWatcher) {
+      try {
+        stateRootWatcher = watch(stateRoot, input.onChange);
+        stateRootWatcher.on("error", () => {
+          stateRootWatcher?.close();
+          stateRootWatcher = undefined;
+        });
+      } catch {
+        // Watching is best-effort; explicit inspect remains available.
+      }
+    }
+    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      watchRunDir(`${stateRoot}/${entry.name}`);
+    }
+  }
+  return { close, refresh };
+}
+
 export interface RunRetirementExecutorOptions {
   attempted?: Set<string>;
   cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;
@@ -612,39 +772,39 @@ function parseOutboxRecord(
   index: number,
 ): RunOutboxEvent | undefined {
   if (!run.stateDir) return undefined;
-    const event =
-      typeof raw.event === "string" && raw.event.trim()
-        ? raw.event.trim()
-        : "run.event";
-    const summary =
-      typeof raw.summary === "string" && raw.summary.trim()
-        ? raw.summary.trim()
-        : event;
-    const ts =
-      typeof raw.ts === "string" && raw.ts.trim()
-        ? raw.ts.trim()
-        : new Date(0).toISOString();
-    const id =
-      typeof raw.id === "string" && raw.id.trim()
-        ? raw.id.trim()
-        : `${run.run}:${index}`;
-    return {
-      ...(raw.body !== undefined ? { body: raw.body } : {}),
-      ...(raw.data !== undefined ? { data: raw.data } : {}),
-      delivery: normalizeOutboxDelivery(raw.delivery),
-      event,
-      id,
-      level: normalizeOutboxLevel(raw.level),
-      ...(raw.metadata &&
-      typeof raw.metadata === "object" &&
-      !Array.isArray(raw.metadata)
-        ? { metadata: raw.metadata as Record<string, unknown> }
-        : {}),
-      run: run.run,
-      stateDir: run.stateDir,
-      summary,
-      ts,
-    };
+  const event =
+    typeof raw.event === "string" && raw.event.trim()
+      ? raw.event.trim()
+      : "run.event";
+  const summary =
+    typeof raw.summary === "string" && raw.summary.trim()
+      ? raw.summary.trim()
+      : event;
+  const ts =
+    typeof raw.ts === "string" && raw.ts.trim()
+      ? raw.ts.trim()
+      : new Date(0).toISOString();
+  const id =
+    typeof raw.id === "string" && raw.id.trim()
+      ? raw.id.trim()
+      : `${run.run}:${index}`;
+  return {
+    ...(raw.body !== undefined ? { body: raw.body } : {}),
+    ...(raw.data !== undefined ? { data: raw.data } : {}),
+    delivery: normalizeOutboxDelivery(raw.delivery),
+    event,
+    id,
+    level: normalizeOutboxLevel(raw.level),
+    ...(raw.metadata &&
+    typeof raw.metadata === "object" &&
+    !Array.isArray(raw.metadata)
+      ? { metadata: raw.metadata as Record<string, unknown> }
+      : {}),
+    run: run.run,
+    stateDir: run.stateDir,
+    summary,
+    ts,
+  };
 }
 
 function readOutboxRecords(run: RunObservation): Record<string, unknown>[] {

package/lib/paths.ts

@@ -17,6 +17,12 @@ export function getAgentDir(
     : join(homedir(), ".pi", "agent");
 }
 
+export interface ExtensionRuntimePaths {
+  configPath: string;
+  runStateRoot: string;
+  tempDir: string;
+}
+
 export function getConfigPath(agentDir = getAgentDir()): string {
   return join(agentDir, "legacy-tool-registry.json");
 }
@@ -32,6 +38,27 @@ export function getRunStateRoot(agentDir = getAgentDir()): string {
   return join(getExtensionTmpDir(agentDir), "runs");
 }
 
+export function getExtensionRuntimePaths(
+  agentDir = getAgentDir(),
+): ExtensionRuntimePaths {
+  return {
+    configPath: getConfigPath(agentDir),
+    runStateRoot: getRunStateRoot(agentDir),
+    tempDir: getExtensionTmpDir(agentDir),
+  };
+}
+
+export const EXTENSION_RUNTIME_PATHS = getExtensionRuntimePaths();
+
+export function getExtensionSkillsDir(extensionUrl: string): string {
+  return join(dirname(fileURLToPath(extensionUrl)), "skills");
+}
+
+export function getExistingExtensionSkillPaths(extensionUrl: string): string[] {
+  const skillsDir = getExtensionSkillsDir(extensionUrl);
+  return existsSync(skillsDir) ? [skillsDir] : [];
+}
+
 export function getRecipeRoot(agentDir = getAgentDir()): string {
   return join(agentDir, "recipes");
 }

package/lib/pi.ts

@@ -0,0 +1,47 @@
+/**
+ * Pi SDK adapter boundary.
+ * Zones: pi agent sdk boundary, extension host adapters
+ * Owns direct pi SDK imports and exposes narrow pi-actors-facing helpers/types for the composition root.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+export type { ExtensionAPI, ExtensionContext };
+
+export interface PiNotificationSink {
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  sendFollowUp(message: {
+    customType: string;
+    content: string;
+    display: true;
+    details: unknown;
+  }): void;
+}
+
+export function getSessionId(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionId();
+}
+
+export function createNotificationSink(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): PiNotificationSink {
+  return {
+    notify: (message, level) => ctx.ui.notify(message, level),
+    sendFollowUp: (message) =>
+      pi.sendMessage(message, {
+        deliverAs: "followUp",
+        triggerTurn: true,
+      }),
+  };
+}
+
+export function registerToolDefinitions(
+  pi: ExtensionAPI,
+  definitions: Iterable<unknown>,
+): void {
+  for (const definition of definitions) pi.registerTool(definition as never);
+}

package/lib/runtime.ts

@@ -4,6 +4,8 @@
  * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
  */
 
+import { existsSync, watch, type FSWatcher } from "node:fs";
+
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
 import * as Paths from "./paths.ts";
@@ -47,6 +49,11 @@ export interface ToolRegistryRuntime {
   registerRuntimeTool(cfg: Config.RegisteredTool): void;
 }
 
+export interface RecipeToolReloadWatcher {
+  close(): void;
+  watch(ctx: RuntimeContext): void;
+}
+
 export function createAutoToolsRuntime(
   deps: ToolRegistryRuntimeDeps,
 ): ToolRegistryRuntime {
@@ -179,3 +186,51 @@ export function createAutoToolsRuntime(
     registerRuntimeTool,
   };
 }
+
+export function createRecipeToolReloadWatcher(
+  runtime: Pick<ToolRegistryRuntime, "loadTools">,
+): RecipeToolReloadWatcher {
+  let reloadTimeout: NodeJS.Timeout | undefined;
+  let rootWatcher: FSWatcher | undefined;
+  let failureNotified = false;
+  const close = (): void => {
+    rootWatcher?.close();
+    rootWatcher = undefined;
+    if (reloadTimeout) clearTimeout(reloadTimeout);
+    reloadTimeout = undefined;
+  };
+  const notifyFailure = (ctx: RuntimeContext): void => {
+    if (failureNotified) return;
+    failureNotified = true;
+    ctx.ui.notify(
+      "Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.",
+      "warning",
+    );
+  };
+  const scheduleReload = (ctx: RuntimeContext): void => {
+    failureNotified = false;
+    if (reloadTimeout) clearTimeout(reloadTimeout);
+    reloadTimeout = setTimeout(() => {
+      runtime.loadTools(ctx);
+      ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+    }, 150);
+    reloadTimeout.unref?.();
+  };
+  return {
+    close,
+    watch(ctx: RuntimeContext): void {
+      const recipeRoot = Paths.getRecipeRoot();
+      if (rootWatcher || !existsSync(recipeRoot)) return;
+      try {
+        rootWatcher = watch(recipeRoot, () => scheduleReload(ctx));
+        rootWatcher.on("error", () => {
+          rootWatcher?.close();
+          rootWatcher = undefined;
+          notifyFailure(ctx);
+        });
+      } catch {
+        notifyFailure(ctx);
+      }
+    },
+  };
+}