@llblab/pi-actors 0.42.3 → 0.43.1

package/scripts/recipe-utils.mjs

@@ -26,7 +26,6 @@ function usage() {
   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]`);
 }
@@ -36,41 +35,6 @@ function fail(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)) {
@@ -172,7 +136,7 @@ function runOpsSnapshot(
     rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
   );
   const inspectedRun = String(runIdValue || "music");
-  const messageFile = join(root, inspectedRun, "outbox.jsonl");
+  const traceFile = join(root, inspectedRun, "trace.jsonl");
   const staleMs = Number(staleMinutesValue) * 60 * 1000;
   const now = Date.now();
   const recommendations = runs.flatMap((run) => {
@@ -186,10 +150,9 @@ function runOpsSnapshot(
         {
           run: run.run,
           reason: "running-stale",
-          suggested_message: {
-            to: `run:${run.run}`,
-            type: "control.stop",
-            body: "stop",
+          suggested_inspect: {
+            target: `run:${run.run}`,
+            view: "control",
           },
         },
       ];
@@ -199,7 +162,7 @@ function runOpsSnapshot(
         {
           run: run.run,
           reason: `terminal-${run.status}`,
-          suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+          suggested_inspect: { target: `run:${run.run}`, view: "trace" },
         },
       ];
     }
@@ -210,7 +173,7 @@ function runOpsSnapshot(
       {
         runs,
         inspectedRun,
-        messages: tailJsonl(messageFile, linesValue),
+        trace: tailJsonl(traceFile, linesValue),
         recommendations,
       },
       null,
@@ -291,57 +254,6 @@ function artifactWrite(pathValue, mode = "create") {
   );
 }
 
-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 ?? "~"),
@@ -475,8 +387,6 @@ 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")

package/scripts/release-gates.mjs

@@ -93,6 +93,97 @@ try {
   }
   console.log("[release] bounded secret and public-path hygiene checked");
 
+  const removedPaths = [
+    "lib/messages.ts",
+    "lib/rooms.ts",
+    "lib/mailbox-loop.ts",
+    "lib/runs-mailbox.ts",
+    "lib/runs-messages.ts",
+    "lib/runs-outbox.ts",
+    "lib/tools-mailbox.ts",
+    "scripts/actor-worker.mjs",
+    "scripts/coordinator.mjs",
+    "recipes/actor-worker.json",
+    "recipes/pipeline-room-swarm.json",
+    "recipes/subagent-message.json",
+    "recipes/utility-actor-message.json",
+    "docs/actor-messages.md",
+    "docs/run-inspector.md",
+    "lib/run-inspector.ts",
+    "lib/run-inspector-overlay.ts",
+  ];
+  for (const path of removedPaths) check(!fileSet.has(path), `removed surface returned: ${path}`);
+
+  const currentSurface = /^(?:lib\/|scripts\/|recipes\/|fixtures\/|skills\/|docs\/|README\.md|AGENTS\.md)/u;
+  const forbiddenPatterns = [
+    [/room:</u, "room address"],
+    [/branch:</u, "branch address"],
+    [/communication\.json/u, "communication snapshot"],
+    [/\bActor(?:Address|Message)\b/u, "legacy actor type"],
+    [/\b(?:actor_address|default_room)\b/u, "legacy spawn placeholder"],
+    [/inbox\.jsonl/u, "legacy inbox state"],
+  ];
+  for (const path of files.filter((candidate) => currentSurface.test(candidate))) {
+    if (path === "BACKLOG.md" || path === "CHANGELOG.md" || path === "scripts/release-gates.mjs") continue;
+    const text = stagedText(path) ?? "";
+    for (const [pattern, label] of forbiddenPatterns) {
+      check(!pattern.test(text), `${label} in current surface: ${path}`);
+    }
+  }
+  const legacyFallbacks = new Map([
+    ["lib/observability.ts", "outbox.jsonl"],
+    ["lib/runs-status.ts", "events.jsonl"],
+    ["lib/runs-start.ts", "events.jsonl"],
+  ]);
+  for (const path of files.filter((candidate) => currentSurface.test(candidate))) {
+    if (path === "BACKLOG.md" || path === "CHANGELOG.md" || path === "scripts/release-gates.mjs") continue;
+    const text = stagedText(path) ?? "";
+    for (const term of ["outbox.jsonl", "events.jsonl"]) {
+      if (!text.includes(term)) continue;
+      check(legacyFallbacks.get(path) === term, `legacy state reference outside read-only fallback: ${path} (${term})`);
+    }
+  }
+  console.log("[release] removed-surface and legacy-fallback allowlists checked");
+
+  const directTraceWrite = /(?:appendFileSync|writeFileSync|writeText(?:Atomic)?)\s*\(\s*[A-Za-z0-9_.]*?(?:trace|event)(?:Path|File)/iu;
+  for (const path of files.filter((candidate) =>
+    (candidate.startsWith("lib/") && candidate.endsWith(".ts")) ||
+    (candidate.startsWith("scripts/") && candidate.endsWith(".mjs"))
+  )) {
+    if (path === "lib/runs-trace.ts") continue;
+    check(!directTraceWrite.test(stagedText(path) ?? ""), `direct Trace writer outside canonical authority: ${path}`);
+  }
+  const canonicalTrace = stagedText("lib/runs-trace.ts") ?? "";
+  check(/withFileMutationLock\(path/u.test(canonicalTrace), "canonical Trace append lacks mutation lock");
+  for (const path of [
+    "scripts/async-runner.mjs",
+    "scripts/locker.mjs",
+    "scripts/music-player.mjs",
+  ]) {
+    const text = stagedText(path) ?? "";
+    check(
+      text.includes('importRuntimeModule("runs-trace")') && text.includes("appendRunTraceEvent"),
+      `first-party Trace writer bypasses canonical runtime module: ${path}`,
+    );
+  }
+  console.log("[release] canonical Trace writer residue checked");
+
+  check(
+    (stagedText("scripts/validate-recipe.mjs") ?? "").includes(
+      "qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0",
+    ),
+    "Recipe QA warnings are not release-blocking",
+  );
+  console.log("[release] zero-warning Recipe QA gate checked");
+
+  const baselineShippedLines = 28_853;
+  const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
+  const shippedLines = files
+    .filter((path) => shippedPath.test(path))
+    .reduce((total, path) => total + (((stagedText(path) ?? "").match(/\n/gu) ?? []).length + 1), 0);
+  check(shippedLines < baselineShippedLines, `shipped lines ${shippedLines} are not below baseline ${baselineShippedLines}`);
+  console.log(`[release] shipped lines ${shippedLines} < released baseline ${baselineShippedLines}`);
+
   const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
   const sourceSet = new Set(sources);
   const graph = new Map();

package/scripts/validate-recipe.mjs

@@ -29,7 +29,7 @@ export function validateRecipeUsage() {
   return `Usage:
   validate-recipe.mjs <recipe-file-or-dir> [--all] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks. Add --summary for compact CLI output.`;
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks, where diagnostics and warnings fail validation. Add --summary for compact CLI output.`;
 }
 
 function expandPath(value) {
@@ -63,13 +63,6 @@ function recipeFiles(target, all) {
     .map((file) => resolve(target, file));
 }
 
-function mailboxType(value) {
-  if (typeof value === "string") return value;
-  if (value && typeof value === "object" && typeof value.type === "string")
-    return value.type;
-  return undefined;
-}
-
 function collectTemplateStrings(value, out = []) {
   if (typeof value === "string") out.push(value);
   else if (Array.isArray(value)) value.forEach((item) => collectTemplateStrings(item, out));
@@ -124,46 +117,11 @@ function validateHelperPaths(file, config) {
   return diagnostics;
 }
 
-function validateMailboxContract(file, config) {
-  const diagnostics = [];
-  const mailbox = config.mailbox;
-  const accepts = Array.isArray(mailbox?.accepts) ? mailbox.accepts : [];
-  const emits = Array.isArray(mailbox?.emits) ? mailbox.emits : [];
-  if (config.async === true && !mailbox)
-    diagnostics.push("mailbox: async recipes must declare mailbox metadata");
-  if (config.async === true && !accepts.map(mailboxType).includes("control.kill"))
-    diagnostics.push("mailbox.accepts: async recipes must include control.kill");
-  const allowedLegacyTypes = new Set(["awaiting_assignment"]);
-  for (const [key, entries] of Object.entries({ accepts, emits })) {
-    entries.forEach((entry, index) => {
-      const type = mailboxType(entry);
-      if (!type) diagnostics.push(`mailbox.${key}[${index}]: must be a string or object with type`);
-      else if (
-        !allowedLegacyTypes.has(type) &&
-        !/^[a-z][a-z0-9_-]*\.(?:[a-z][a-z0-9_-]*|\*)$/.test(type)
-      )
-        diagnostics.push(`mailbox.${key}[${index}]: message type must use channel.action form`);
-    });
-  }
-  const allowedDomainTermination = new Set([
-    "coordinator-locker.json",
-    "locker.json",
-    "music-player.json",
-  ]);
-  const hasDomainTermination = accepts
-    .map(mailboxType)
-    .some((type) => type === "control.stop" || type === "control.cancel");
-  if (hasDomainTermination && !allowedDomainTermination.has(file.split(/[\\/]/).pop()))
-    diagnostics.push("mailbox.accepts: control.stop/control.cancel are reserved for actor-domain handlers");
-  return diagnostics;
-}
-
 function qaDiagnostics(file, config) {
   const diagnostics = [];
   const warnings = [];
-  if (typeof config.description !== "string" || !config.description.trim())
-    warnings.push("description: missing or empty");
-  diagnostics.push(...validateMailboxContract(file, config));
+  if (config.mailbox !== undefined)
+    diagnostics.push("recipe.mailbox was removed; use control actions and Trace events");
   diagnostics.push(...validateArtifactDeclarations(config));
   diagnostics.push(...validateHelperPaths(file, config));
   const platformSpecificTemplate = collectTemplateStrings(config.template).some(
@@ -178,7 +136,7 @@ function qaDiagnostics(file, config) {
 }
 
 function qaOk(qaReport) {
-  return qaReport.diagnostics.length === 0;
+  return qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0;
 }
 
 function validateFile(file, qa = false) {
@@ -201,17 +159,7 @@ function validateFile(file, qa = false) {
         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,
+      control: Array.isArray(config.control) ? config.control : undefined,
       ...(qa
         ? {
             qa: {
@@ -275,6 +223,9 @@ function summarizeReport(report) {
         ...(result.qa?.diagnostics?.length
           ? { diagnostics: result.qa.diagnostics }
           : {}),
+        ...(result.qa?.warnings?.length
+          ? { warnings: result.qa.warnings }
+          : {}),
       })),
   };
 }