@llblab/pi-actors 0.14.2 → 0.15.0

package/scripts/recipe-utils.mjs

@@ -1,17 +1,26 @@
 #!/usr/bin/env node
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+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> <message-file> [lines] [stale-minutes]
+  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 package-summary <package-json>
+  recipe-utils.mjs skill-summary <skill-md> [package-json]`);
 }
 
 function fail(message) {
@@ -24,7 +33,8 @@ 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}`);
+  if (!ADDRESS_PATTERN.test(normalized))
+    fail(`${label} contains unsupported characters: ${value}`);
   return normalized;
 }
 
@@ -37,16 +47,19 @@ function validateActorAddress(address, label) {
   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}`);
+    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)}`;
+  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}`);
+  if (!MESSAGE_TYPE_PATTERN.test(value))
+    fail(`Invalid actor message type: ${type}`);
   return value;
 }
 
@@ -100,7 +113,13 @@ function collectRunSummary(rootValue) {
       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 ?? "",
+      updated:
+        progress?.updatedAt ??
+        result?.completedAt ??
+        run.updated_at ??
+        run.completed_at ??
+        run.started_at ??
+        "",
     });
   }
   rows.sort((a, b) =>
@@ -114,43 +133,82 @@ function runSummary(rootValue) {
 }
 
 function tailJsonl(fileValue, linesValue = "80") {
-  const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  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 };
-    }
-  });
+  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, messageFileValue, linesValue = "80", staleMinutesValue = "60") {
+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;
+    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" },
-      }];
+      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 [
+        {
+          run: run.run,
+          reason: `terminal-${run.status}`,
+          suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+        },
+      ];
     }
     return [];
   });
-  console.log(JSON.stringify({ runs, messages: tailJsonl(messageFileValue, linesValue), recommendations }, null, 2));
+  console.log(
+    JSON.stringify(
+      {
+        runs,
+        inspectedRun,
+        messages: tailJsonl(messageFile, linesValue),
+        recommendations,
+      },
+      null,
+      2,
+    ),
+  );
 }
 
 function playlist(
@@ -177,23 +235,38 @@ function playlist(
   else console.log(files.join("\n"));
 }
 
-function artifactManifest(pathValue, title = "Artifact", status = "draft", summary = "") {
-  const path = resolve(pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+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));
+  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 ?? "~"));
+  const path = resolve(
+    pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
   if (!["create", "overwrite", "append"].includes(mode)) {
     fail(`Invalid artifact write mode: ${mode}`);
   }
@@ -205,10 +278,20 @@ function artifactWrite(pathValue, mode = "create") {
   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));
+  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 = "") {
+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");
@@ -216,7 +299,8 @@ function actorMessage(type = "event", to = "coordinator", from = "run:{run_id}",
   if (metadataValue) {
     try {
       const parsed = JSON.parse(metadataValue);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) metadata = parsed;
+      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}`);
@@ -232,47 +316,114 @@ function actorMessage(type = "event", to = "coordinator", from = "run:{run_id}",
       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));
+  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 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));
+  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) {
@@ -301,7 +452,12 @@ if (!command) {
 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] ?? "~/.pi/agent/tmp/pi-actors/runs/music/outbox.jsonl", args[2], args[3]);
+  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")
@@ -314,6 +470,8 @@ 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/scripts/validate-recipe.mjs

@@ -13,7 +13,9 @@ Validates one template recipe file, or all *.json files in a directory when --al
 }
 
 function expandPath(value) {
-  return resolve(String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? homedir()));
+  return resolve(
+    String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? homedir()),
+  );
 }
 
 function templateKind(template) {
@@ -21,7 +23,8 @@ function templateKind(template) {
   if (Array.isArray(template)) return "sequence";
   if (template && typeof template === "object") {
     if (typeof template.template === "string") return "leaf";
-    if (Array.isArray(template.template)) return template.parallel === true ? "parallel" : "sequence";
+    if (Array.isArray(template.template))
+      return template.parallel === true ? "parallel" : "sequence";
     if (template.parallel === true) return "parallel";
     return "object";
   }
@@ -32,7 +35,8 @@ function recipeFiles(target, all) {
   if (!existsSync(target)) throw new Error(`Recipe path not found: ${target}`);
   const stat = statSync(target);
   if (stat.isFile()) return [target];
-  if (!stat.isDirectory()) throw new Error(`Recipe path is not a file or directory: ${target}`);
+  if (!stat.isDirectory())
+    throw new Error(`Recipe path is not a file or directory: ${target}`);
   if (!all) throw new Error("Directory validation requires --all.");
   return readdirSync(target)
     .filter((file) => file.endsWith(".json"))
@@ -43,19 +47,33 @@ function recipeFiles(target, all) {
 function validateFile(file) {
   try {
     const config = readResolvedRecipeConfig(file);
-    if (!config?.template) throw new Error("Recipe must define a non-empty template.");
+    if (!config?.template)
+      throw new Error("Recipe must define a non-empty template.");
     return {
       file,
       ok: true,
       name: config.name ?? "",
       async: Boolean(config.async),
       args: Array.isArray(config.args) ? config.args : [],
-      defaults: config.defaults && typeof config.defaults === "object" ? Object.keys(config.defaults).sort() : [],
-      imports: config.imports && typeof config.imports === "object" ? Object.keys(config.imports).sort() : [],
-      mailbox: config.mailbox && typeof config.mailbox === "object" ? {
-        accepts: Array.isArray(config.mailbox.accepts) ? config.mailbox.accepts : [],
-        emits: Array.isArray(config.mailbox.emits) ? config.mailbox.emits : [],
-      } : undefined,
+      defaults:
+        config.defaults && typeof config.defaults === "object"
+          ? Object.keys(config.defaults).sort()
+          : [],
+      imports:
+        config.imports && typeof config.imports === "object"
+          ? Object.keys(config.imports).sort()
+          : [],
+      mailbox:
+        config.mailbox && typeof config.mailbox === "object"
+          ? {
+              accepts: Array.isArray(config.mailbox.accepts)
+                ? config.mailbox.accepts
+                : [],
+              emits: Array.isArray(config.mailbox.emits)
+                ? config.mailbox.emits
+                : [],
+            }
+          : undefined,
       template: templateKind(config.template),
     };
   } catch (error) {