@llblab/pi-actors 0.22.5 → 0.24.0

package/lib/recipe-references.ts

@@ -26,9 +26,21 @@ export interface TemplateRecipeImportBinding {
 
 export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 
+export type TemplateRecipeMailboxEntry =
+  | string
+  | {
+      type: string;
+      body_schema?: unknown;
+      ack?: boolean | string;
+      idempotency?: string;
+      requires_response?: boolean;
+      level?: string;
+      summary?: string;
+    };
+
 export interface TemplateRecipeMailbox {
-  accepts?: string[];
-  emits?: string[];
+  accepts?: TemplateRecipeMailboxEntry[];
+  emits?: TemplateRecipeMailboxEntry[];
 }
 
 export interface TemplateRecipeDefinition {
@@ -299,6 +311,35 @@ function parseMarkdownFrontmatterObject(
   return result;
 }
 
+function normalizeMarkdownFrontmatterField(
+  key: string,
+  value: unknown,
+): unknown {
+  if (key === "args" && typeof value === "string") {
+    return value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+  if (key === "defaults" && Array.isArray(value)) {
+    return Object.fromEntries(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => {
+          const separator = item.indexOf(":");
+          return separator < 0
+            ? [item.trim(), ""]
+            : [
+                item.slice(0, separator).trim(),
+                parseMarkdownScalar(item.slice(separator + 1)),
+              ];
+        })
+        .filter(([name]) => Boolean(name)),
+    );
+  }
+  return value;
+}
+
 function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   const lines = value.split(/\r?\n/);
@@ -308,7 +349,10 @@ function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
     const match = line.match(/^([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
     if (!match) continue;
     if (match[2]) {
-      result[match[1]] = parseMarkdownScalar(match[2]);
+      result[match[1]] = normalizeMarkdownFrontmatterField(
+        match[1],
+        parseMarkdownScalar(match[2]),
+      );
       continue;
     }
     const nested: string[] = [];
@@ -316,7 +360,10 @@ function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
       index += 1;
       nested.push(lines[index]);
     }
-    result[match[1]] = parseMarkdownFrontmatterObject(nested);
+    result[match[1]] = normalizeMarkdownFrontmatterField(
+      match[1],
+      parseMarkdownFrontmatterObject(nested),
+    );
   }
   return result;
 }
@@ -834,14 +881,18 @@ export function readResolvedRecipeConfig(
             ...(Array.isArray(substituted.mailbox.accepts)
               ? {
                   accepts: substituted.mailbox.accepts.filter(
-                    (value): value is string => typeof value === "string",
+                    (value): value is TemplateRecipeMailboxEntry =>
+                      typeof value === "string" ||
+                      (isRecord(value) && typeof value.type === "string"),
                   ),
                 }
               : {}),
             ...(Array.isArray(substituted.mailbox.emits)
               ? {
                   emits: substituted.mailbox.emits.filter(
-                    (value): value is string => typeof value === "string",
+                    (value): value is TemplateRecipeMailboxEntry =>
+                      typeof value === "string" ||
+                      (isRecord(value) && typeof value.type === "string"),
                   ),
                 }
               : {}),

package/lib/recipe-usage.ts

@@ -11,9 +11,14 @@ import { writeJsonAtomic } from "./file-state.ts";
 
 interface RecipeUsageRecord {
   calls?: number;
-  last_called?: string;
+  direct_calls?: number;
   fingerprint?: string;
+  last_called?: string;
+  launch_kind?: string;
   reset_at?: string;
+  reset_reason?: string;
+  spawn_calls?: number;
+  tool_calls?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -40,23 +45,45 @@ function getRecipeFingerprint(raw: Record<string, unknown>): string {
   return createHash("sha256").update(stableStringify(content)).digest("hex");
 }
 
-export function recordRecipeLaunch(path: string, now = new Date()): boolean {
+export type RecipeLaunchKind = "direct" | "spawn" | "tool";
+
+function launchCounterKey(
+  kind: RecipeLaunchKind,
+): "direct_calls" | "spawn_calls" | "tool_calls" {
+  return `${kind}_calls` as "direct_calls" | "spawn_calls" | "tool_calls";
+}
+
+export function recordRecipeLaunch(
+  path: string,
+  now = new Date(),
+  kind: RecipeLaunchKind = "direct",
+): 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 changed =
+      typeof usage.fingerprint === "string" &&
+      usage.fingerprint !== fingerprint;
     const nowIso = now.toISOString();
+    const counterKey = launchCounterKey(kind);
     writeJsonAtomic(path, {
       ...raw,
       usage: {
         ...usage,
         calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
+        [counterKey]: (changed ? 0 : normalizeCalls(usage[counterKey])) + 1,
         last_called: nowIso,
+        launch_kind: kind,
         fingerprint,
-        ...(changed ? { reset_at: nowIso } : {}),
+        ...(changed
+          ? {
+              reset_at: nowIso,
+              reset_reason: "recipe content fingerprint changed",
+            }
+          : {}),
       },
     });
     return true;

package/lib/recipe-utils.ts

@@ -0,0 +1,486 @@
+/**
+ * Recipe utility command bundle entrypoint logic.
+ * Zones: recipe utilities, deterministic helper subcommands
+ */
+
+// @ts-nocheck
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+function usage() {
+  console.error(`Usage:
+  recipe-utils.mjs run-summary <state-root>
+  recipe-utils.mjs run-ops-snapshot <state-root> <run-id> [lines] [stale-minutes]
+  recipe-utils.mjs playlist <source-dir> [extensions] [max-depth] [paths|m3u|inline]
+  recipe-utils.mjs changelog-section <file> <version>
+  recipe-utils.mjs artifact-manifest <artifact-path> <title> <status> [summary]
+  recipe-utils.mjs artifact-write <artifact-path> [create|overwrite|append]
+  recipe-utils.mjs actor-message <type> [to] [from] [summary] [metadata-json] [correlation-id] [reply-to]
+  recipe-utils.mjs package-summary <package-json>
+  recipe-utils.mjs skill-summary <skill-md> [package-json]`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
+function assertToken(value, label) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) fail(`${label} is required`);
+  if (!ADDRESS_PATTERN.test(normalized))
+    fail(`${label} contains unsupported characters: ${value}`);
+  return normalized;
+}
+
+function validateActorAddress(address, label) {
+  const value = String(address ?? "").trim();
+  if (value === "coordinator") return value;
+  const separator = value.indexOf(":");
+  if (separator < 0) fail(`${label} must include an actor kind: ${address}`);
+  const kind = value.slice(0, separator);
+  const rest = value.slice(separator + 1);
+  if (kind === "branch") {
+    const [run, branch, ...extra] = rest.split("/");
+    if (extra.length > 0)
+      fail(`${label} branch address has too many parts: ${address}`);
+    return `branch:${assertToken(run, `${label} branch run`)}/${assertToken(branch, `${label} branch id`)}`;
+  }
+  if (["run", "session", "tool"].includes(kind))
+    return `${kind}:${assertToken(rest, label)}`;
+  fail(`${label} has unsupported actor kind: ${kind}`);
+}
+
+function validateMessageType(type) {
+  const value = String(type ?? "").trim();
+  if (!MESSAGE_TYPE_PATTERN.test(value))
+    fail(`Invalid actor message type: ${type}`);
+  return value;
+}
+
+function walkFiles(dir, maxDepth = 2, depth = 0, out = []) {
+  if (depth > maxDepth || !existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) walkFiles(path, maxDepth, depth + 1, out);
+    else if (stat.isFile()) out.push(path);
+  }
+  return out;
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function getRunStatus(run, progress, result) {
+  if (progress?.phase) return progress.phase;
+  if (result?.code !== undefined) return result.code === 0 ? "done" : "failed";
+  return run.status ?? "unknown";
+}
+
+function collectRunSummary(rootValue) {
+  const root = resolve(
+    rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+  const rows = [];
+  for (const file of files) {
+    const run = readJson(file);
+    if (!run) {
+      rows.push({
+        run: relative(root, file),
+        status: "invalid-json",
+        recipe: "",
+        updated: "",
+      });
+      continue;
+    }
+    const runDir = dirname(file);
+    const progress = readJson(join(runDir, "progress.json"));
+    const result = readJson(join(runDir, "result.json"));
+    rows.push({
+      run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+      status: getRunStatus(run, progress, result),
+      recipe: run.recipe ?? run.recipe_file ?? "",
+      updated:
+        progress?.updatedAt ??
+        result?.completedAt ??
+        run.updated_at ??
+        run.completed_at ??
+        run.started_at ??
+        "",
+    });
+  }
+  rows.sort((a, b) =>
+    `${a.status}:${a.run}`.localeCompare(`${b.status}:${b.run}`),
+  );
+  return rows;
+}
+
+function runSummary(rootValue) {
+  console.log(JSON.stringify(collectRunSummary(rootValue), null, 2));
+}
+
+function tailJsonl(fileValue, linesValue = "80") {
+  const file = resolve(
+    fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  if (!existsSync(file)) return [];
+  const lines = Number.parseInt(linesValue, 10);
+  const count = Number.isFinite(lines) && lines > 0 ? lines : 80;
+  return readFileSync(file, "utf8")
+    .trimEnd()
+    .split("\n")
+    .filter(Boolean)
+    .slice(-count)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return { raw: line };
+      }
+    });
+}
+
+function runOpsSnapshot(
+  rootValue,
+  runIdValue = "music",
+  linesValue = "80",
+  staleMinutesValue = "60",
+) {
+  const runs = collectRunSummary(rootValue);
+  const root = resolve(
+    rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const inspectedRun = String(runIdValue || "music");
+  const messageFile = join(root, inspectedRun, "outbox.jsonl");
+  const staleMs = Number(staleMinutesValue) * 60 * 1000;
+  const now = Date.now();
+  const recommendations = runs.flatMap((run) => {
+    const updatedMs = Date.parse(run.updated || "");
+    const stale =
+      Number.isFinite(updatedMs) &&
+      Number.isFinite(staleMs) &&
+      now - updatedMs > staleMs;
+    if (run.status === "running" && stale) {
+      return [
+        {
+          run: run.run,
+          reason: "running-stale",
+          suggested_message: {
+            to: `run:${run.run}`,
+            type: "control.stop",
+            body: "stop",
+          },
+        },
+      ];
+    }
+    if (["failed", "exited", "killed"].includes(run.status)) {
+      return [
+        {
+          run: run.run,
+          reason: `terminal-${run.status}`,
+          suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+        },
+      ];
+    }
+    return [];
+  });
+  console.log(
+    JSON.stringify(
+      {
+        runs,
+        inspectedRun,
+        messages: tailJsonl(messageFile, linesValue),
+        recommendations,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function playlist(
+  sourceValue,
+  extensionsValue = ".mp3,.ogg,.wav,.flac,.m4a",
+  maxDepthValue = "2",
+  outputMode = "paths",
+) {
+  const source = resolve(
+    sourceValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const maxDepth = Number.parseInt(maxDepthValue, 10);
+  const extensions = new Set(
+    extensionsValue
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const files = walkFiles(source, Number.isFinite(maxDepth) ? maxDepth : 2)
+    .filter((file) => extensions.has(extname(file).toLowerCase()))
+    .sort((a, b) => a.localeCompare(b));
+  if (outputMode === "m3u") console.log(["#EXTM3U", ...files].join("\n"));
+  else if (outputMode === "inline") console.log(files.join("|"));
+  else console.log(files.join("\n"));
+}
+
+function artifactManifest(
+  pathValue,
+  title = "Artifact",
+  status = "draft",
+  summary = "",
+) {
+  const path = resolve(
+    pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const exists = existsSync(path);
+  const stat = exists ? statSync(path) : undefined;
+  console.log(
+    JSON.stringify(
+      {
+        title,
+        status,
+        path,
+        exists,
+        bytes: stat?.size ?? 0,
+        modified: stat?.mtime?.toISOString?.() ?? null,
+        summary,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function artifactWrite(pathValue, mode = "create") {
+  const path = resolve(
+    pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  if (!["create", "overwrite", "append"].includes(mode)) {
+    fail(`Invalid artifact write mode: ${mode}`);
+  }
+  if (mode === "create" && existsSync(path)) {
+    fail(`Artifact already exists: ${path}`);
+  }
+  const content = readFileSync(0, "utf8");
+  mkdirSync(dirname(path), { recursive: true });
+  if (mode === "append") appendFileSync(path, content);
+  else writeFileSync(path, content, "utf8");
+  const stat = statSync(path);
+  console.log(
+    JSON.stringify({ path, mode, bytes: stat.size, written: true }, null, 2),
+  );
+}
+
+function actorMessage(
+  type = "event",
+  to = "coordinator",
+  from = "run:{run_id}",
+  summary = "",
+  metadataValue = "",
+  correlationId = "",
+  replyTo = "",
+) {
+  const messageType = validateMessageType(type);
+  const messageTo = validateActorAddress(to, "message.to");
+  const messageFrom = validateActorAddress(from, "message.from");
+  let metadata = {};
+  if (metadataValue) {
+    try {
+      const parsed = JSON.parse(metadataValue);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+        metadata = parsed;
+      else fail("Actor message metadata must be a JSON object");
+    } catch (error) {
+      fail(`Invalid actor message metadata JSON: ${error.message}`);
+    }
+  }
+  const bodyText = readFileSync(0, "utf8");
+  const trimmed = bodyText.trim();
+  let body = bodyText;
+  if (trimmed) {
+    try {
+      body = JSON.parse(trimmed);
+    } catch {
+      body = bodyText;
+    }
+  }
+  console.log(
+    JSON.stringify(
+      {
+        to: messageTo,
+        from: messageFrom,
+        type: messageType,
+        summary: summary || messageType,
+        body,
+        ...(correlationId ? { correlation_id: correlationId } : {}),
+        ...(replyTo ? { reply_to: replyTo } : {}),
+        metadata,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function packageSummary(fileValue = "package.json") {
+  const file = resolve(
+    fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const pkg = readJson(file);
+  if (!pkg) fail(`Package JSON not found or invalid: ${fileValue}`);
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === "object"
+      ? Object.keys(pkg.scripts).sort()
+      : [];
+  const dependencies =
+    pkg.dependencies && typeof pkg.dependencies === "object"
+      ? Object.keys(pkg.dependencies).sort()
+      : [];
+  const devDependencies =
+    pkg.devDependencies && typeof pkg.devDependencies === "object"
+      ? Object.keys(pkg.devDependencies).sort()
+      : [];
+  console.log(
+    JSON.stringify(
+      {
+        name: pkg.name ?? "",
+        version: pkg.version ?? "",
+        type: pkg.type ?? "",
+        private: Boolean(pkg.private),
+        packageManager: pkg.packageManager ?? "",
+        files: Array.isArray(pkg.files) ? pkg.files : [],
+        bin: pkg.bin ?? null,
+        main: pkg.main ?? "",
+        exports: pkg.exports ?? null,
+        scripts,
+        dependencyCount: dependencies.length,
+        devDependencyCount: devDependencies.length,
+        dependencies,
+        devDependencies,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function parseSkillFrontmatter(content) {
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
+  const fields = {};
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (match) fields[match[1]] = match[2].trim();
+  }
+  return { frontmatter, fields };
+}
+
+function skillSummary(skillValue, packageValue = "package.json") {
+  const skillFile = resolve(
+    skillValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const packageFile = resolve(
+    packageValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const content = readFileSync(skillFile, "utf8");
+  const pkg = readJson(packageFile) ?? {};
+  const { frontmatter, fields } = parseSkillFrontmatter(content);
+  const scalarLines = frontmatter
+    .split(/\r?\n/)
+    .filter((line) => /^\w+:\s*\S/.test(line));
+  const extraColonLines = scalarLines.filter(
+    (line) => (line.match(/:/g) ?? []).length > 1,
+  );
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+  const version =
+    fields.version ??
+    frontmatter.match(/^\s+version:\s*([^\n]+)\s*$/m)?.[1]?.trim() ??
+    "";
+  console.log(
+    JSON.stringify(
+      {
+        path: skillValue,
+        name: fields.name ?? "",
+        description: fields.description ?? "",
+        version,
+        packageVersion: pkg.version ?? "",
+        versionMatchesPackage: version === pkg.version,
+        frontmatterExtraColonLines: extraColonLines,
+        bodyLineCount: body.split(/\r?\n/).length,
+        headings: body.split(/\r?\n/).filter((line) => /^#{1,6}\s/.test(line)),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function changelogSection(fileValue, version) {
+  const file = resolve(fileValue);
+  const lines = readFileSync(file, "utf8").split(/\r?\n/);
+  const start = lines.findIndex(
+    (line) => line.startsWith("## ") && line.includes(version),
+  );
+  if (start < 0) fail(`Version section not found: ${version}`);
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (lines[index].startsWith("## ")) {
+      end = index;
+      break;
+    }
+  }
+  console.log(lines.slice(start, end).join("\n").trimEnd());
+}
+
+export function runRecipeUtils(argv = process.argv.slice(2)) {
+const [command, ...args] = argv;
+if (!command) {
+  usage();
+  process.exit(1);
+}
+
+if (command === "run-summary")
+  runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+else if (command === "run-ops-snapshot")
+  runOpsSnapshot(
+    args[0] ?? "~/.pi/agent/tmp/pi-actors/runs",
+    args[1] ?? "music",
+    args[2],
+    args[3],
+  );
+else if (command === "playlist")
+  playlist(args[0] ?? "~/Music", args[1], args[2], args[3]);
+else if (command === "changelog-section")
+  changelogSection(args[0] ?? "CHANGELOG.md", args[1] ?? "Unreleased");
+else if (command === "artifact-manifest")
+  artifactManifest(args[0] ?? "artifact.md", args[1], args[2], args[3]);
+else if (command === "artifact-write")
+  artifactWrite(args[0] ?? "artifact.md", args[1] ?? "create");
+else if (command === "actor-message")
+  actorMessage(args[0], args[1], args[2], args[3], args[4], args[5], args[6]);
+else if (command === "package-summary")
+  packageSummary(args[0] ?? "package.json");
+else if (command === "skill-summary")
+  skillSummary(args[0] ?? "skills/actors/SKILL.md", args[1] ?? "package.json");
+else {
+  usage();
+  fail(`Unknown command: ${command}`);
+}
+}

package/lib/runtime-notifier.ts

@@ -16,6 +16,8 @@ import {
 } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
+import { readJsonlFileResilient } from "./state-readers.ts";
+
 export interface RuntimeWakeEvent {
   actor: string;
   id: string;
@@ -124,12 +126,8 @@ export function parseRuntimeWakeEventLine(
 }
 
 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)
+  return readJsonlFileResilient<Record<string, unknown>>(runtimeWakeFile(stateDir))
+    .records.map((record) => parseRuntimeWakeEventLine(JSON.stringify(record)))
     .filter((event): event is RuntimeWakeEvent => Boolean(event));
 }