@llblab/pi-actors 0.21.0 → 0.22.0

package/lib/runtime-notifier.ts

@@ -0,0 +1,207 @@
+/**
+ * Runtime wake notifications for actor state.
+ * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
+ * Owns best-effort live wake signals while durable mailbox/state files remain canonical.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  watch,
+  type FSWatcher,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export interface RuntimeWakeEvent {
+  actor: string;
+  id: string;
+  metadata?: Record<string, unknown>;
+  reason: string;
+  state_dir: string;
+  ts: string;
+}
+
+export interface RuntimeNotifierSubscription {
+  close(): void;
+}
+
+export type RuntimeReconcileReason = "initial" | "poll" | "wake";
+
+export interface RuntimeReconcileEvent {
+  actor: string;
+  reason: RuntimeReconcileReason;
+  state_dir: string;
+  ts: string;
+}
+
+export interface RuntimeNotifierSubscribeOptions {
+  onReconcile?: (event: RuntimeReconcileEvent) => void;
+}
+
+export interface FileRuntimeNotifierOptions {
+  pollIntervalMs?: number;
+  replay?: boolean;
+  watch?: boolean;
+}
+
+export interface RuntimeNotifier {
+  notify(event: { actor: string; metadata?: Record<string, unknown>; reason: string }): RuntimeWakeEvent;
+  subscribe(
+    actor: string,
+    onWake: (event: RuntimeWakeEvent) => void,
+    options?: RuntimeNotifierSubscribeOptions,
+  ): RuntimeNotifierSubscription;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+
+export function runtimeWakeFile(stateDir: string): string {
+  return join(stateDir, "wake.jsonl");
+}
+
+function normalizeWakeEvent(
+  stateDir: string,
+  event: { actor: string; metadata?: Record<string, unknown>; reason: string },
+): RuntimeWakeEvent {
+  const actor = event.actor.trim();
+  const reason = event.reason.trim();
+  if (!actor) throw new Error("Runtime wake event requires actor.");
+  if (!reason) throw new Error("Runtime wake event requires reason.");
+  return {
+    actor,
+    id: randomUUID(),
+    ...(event.metadata ? { metadata: event.metadata } : {}),
+    reason,
+    state_dir: stateDir,
+    ts: new Date().toISOString(),
+  };
+}
+
+export function notifyRuntimeWake(
+  stateDir: string,
+  event: { actor: string; metadata?: Record<string, unknown>; reason: string },
+): RuntimeWakeEvent {
+  const normalized = normalizeWakeEvent(stateDir, event);
+  const file = runtimeWakeFile(stateDir);
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, `${JSON.stringify(normalized)}\n`, "utf8");
+  return normalized;
+}
+
+export function parseRuntimeWakeEventLine(
+  line: string,
+): RuntimeWakeEvent | undefined {
+  try {
+    const record = JSON.parse(line) as Record<string, unknown>;
+    if (
+      typeof record.actor !== "string" ||
+      typeof record.id !== "string" ||
+      typeof record.reason !== "string" ||
+      typeof record.state_dir !== "string" ||
+      typeof record.ts !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      actor: record.actor,
+      id: record.id,
+      ...(record.metadata &&
+      typeof record.metadata === "object" &&
+      !Array.isArray(record.metadata)
+        ? { metadata: record.metadata as Record<string, unknown> }
+        : {}),
+      reason: record.reason,
+      state_dir: record.state_dir,
+      ts: record.ts,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readRuntimeWakeEvents(stateDir: string): RuntimeWakeEvent[] {
+  const file = runtimeWakeFile(stateDir);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map(parseRuntimeWakeEventLine)
+    .filter((event): event is RuntimeWakeEvent => Boolean(event));
+}
+
+export function createFileRuntimeNotifier(
+  stateDir: string,
+  options: FileRuntimeNotifierOptions = {},
+): RuntimeNotifier {
+  const file = runtimeWakeFile(stateDir);
+  const pollIntervalMs = Math.max(
+    25,
+    Number(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS),
+  );
+
+  return {
+    notify: (event) => notifyRuntimeWake(stateDir, event),
+    subscribe: (actor, onWake, subscribeOptions = {}) => {
+      mkdirSync(dirname(file), { recursive: true });
+      let position =
+        options.replay || !existsSync(file) ? 0 : statSync(file).size;
+      let closed = false;
+      const reconcile = (reason: RuntimeReconcileReason): void => {
+        if (closed) return;
+        subscribeOptions.onReconcile?.({
+          actor,
+          reason,
+          state_dir: stateDir,
+          ts: new Date().toISOString(),
+        });
+      };
+      const drain = (): void => {
+        if (closed || !existsSync(file)) return;
+        const buffer = readFileSync(file);
+        if (position > buffer.length) position = 0;
+        const chunk = buffer.subarray(position).toString("utf8");
+        position = buffer.length;
+        for (const line of chunk.split("\n")) {
+          if (!line.trim()) continue;
+          const event = parseRuntimeWakeEventLine(line);
+          if (event && event.actor === actor) {
+            onWake(event);
+            reconcile("wake");
+          }
+        }
+      };
+
+      let watcher: FSWatcher | undefined;
+      if (options.watch !== false) {
+        try {
+          watcher = watch(
+            dirname(file),
+            { persistent: false },
+            (_eventType, changedFile) => {
+              if (!changedFile || String(changedFile) === basename(file)) drain();
+            },
+          );
+        } catch {
+          // fs.watch availability varies by platform/filesystem; polling below is the fallback.
+        }
+      }
+      reconcile("initial");
+      const timer = setInterval(() => {
+        drain();
+        reconcile("poll");
+      }, pollIntervalMs);
+      timer.unref?.();
+      return {
+        close: () => {
+          closed = true;
+          clearInterval(timer);
+          watcher?.close();
+        },
+      };
+    },
+  };
+}

package/lib/tools.ts

@@ -287,8 +287,11 @@ function compactCommunicationSnapshot(
   return `\nself=${snapshot.self} root=${snapshot.root} rooms=${snapshot.rooms.length} updated_at=${snapshot.updated_at}`;
 }
 
-function compactBranchInbox(messages: Array<Record<string, unknown>>): string {
-  if (messages.length === 0) return "\n(no branch inbox messages)";
+function compactInboxMessages(
+  messages: Array<Record<string, unknown>>,
+  emptyLabel: string,
+): string {
+  if (messages.length === 0) return `\n(no ${emptyLabel} messages)`;
   return `\n${messages
     .map((message) =>
       [
@@ -298,6 +301,7 @@ function compactBranchInbox(messages: Array<Record<string, unknown>>): string {
         `from=${String(message.from ?? "")}`,
         `to=${String(message.to ?? "")}`,
         ...(message.queued_at ? [`queued_at=${String(message.queued_at)}`] : []),
+        ...(message.sent_at ? [`sent_at=${String(message.sent_at)}`] : []),
         ...(message.claimed_at ? [`claimed_at=${String(message.claimed_at)}`] : []),
         ...(message.handled_at ? [`handled_at=${String(message.handled_at)}`] : []),
         ...(message.failed_at ? [`failed_at=${String(message.failed_at)}`] : []),
@@ -306,6 +310,18 @@ function compactBranchInbox(messages: Array<Record<string, unknown>>): string {
     .join("\n")}`;
 }
 
+function compactBranchInbox(messages: Array<Record<string, unknown>>): string {
+  return compactInboxMessages(messages, "branch inbox");
+}
+
+function compactRunMailbox(
+  run: string,
+  mailbox: Record<string, unknown>,
+  messages: Array<Record<string, unknown>>,
+): string {
+  return `\nrun=${run} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}${compactInboxMessages(messages, "run inbox")}`;
+}
+
 function compactActorFiles(status: Record<string, unknown>): string {
   const run = String(status.run ?? "<unknown>");
   const artifacts = asRecord(status.artifacts);
@@ -984,18 +1000,23 @@ export function createInspectToolDefinition<TContext = unknown>(
         case "mailbox": {
           const status = assertRunAccessibleToContext(runId, ctx);
           const mailbox = asRecord(status.mailbox);
+          const messages = AsyncRuns.readRunInboxMessages(
+            runId,
+            Number(input.lines || 40),
+          );
+          const details = { mailbox, messages };
           return {
             content: [
               {
                 type: "text" as const,
                 text: maybeJsonText(
-                  mailbox,
+                  details,
                   input.verbose === true,
-                  `\nrun=${String(status.run ?? runId)} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}`,
+                  compactRunMailbox(String(status.run ?? runId), mailbox, messages),
                 ),
               },
             ],
-            details: { mailbox },
+            details,
           };
         }
         case "communication": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -33,7 +33,6 @@
     "prepack": "npm run build"
   },
   "files": [
-    "index.js",
     "index.ts",
     "lib",
     "scripts",
@@ -49,7 +48,7 @@
   ],
   "pi": {
     "extensions": [
-      "./index.js"
+      "./dist/index.js"
     ],
     "skills": [
       "./skills/actors/SKILL.md",

package/recipes/music-player.json

@@ -6,7 +6,7 @@
     "source:string",
     "loop:bool",
     "volume:int",
-    "player:enum(auto,mpv,ffplay,cvlc,play)",
+    "player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)",
     "state_dir:path"
   ],
   "defaults": {