@llblab/pi-actors 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/AGENTS.md +125 -60
  2. package/BACKLOG.md +93 -188
  3. package/CHANGELOG.md +22 -0
  4. package/README.md +13 -0
  5. package/dist/fixtures/protocol/actor-message-branch.json +13 -0
  6. package/dist/fixtures/protocol/artifact-manifest.json +9 -0
  7. package/dist/fixtures/protocol/mailbox-contract.json +15 -0
  8. package/dist/fixtures/protocol/recipe-summary.json +16 -0
  9. package/dist/fixtures/protocol/room-message.json +11 -0
  10. package/dist/fixtures/protocol/room-roster.json +11 -0
  11. package/dist/fixtures/protocol/run-inbox-message.json +9 -0
  12. package/dist/fixtures/protocol/run-outbox-event.json +9 -0
  13. package/dist/fixtures/protocol/run-state.json +10 -0
  14. package/dist/index.js +3 -2
  15. package/dist/lib/actor-inspector-tui.js +5 -32
  16. package/dist/lib/actor-rooms.d.ts +8 -0
  17. package/dist/lib/actor-rooms.js +64 -20
  18. package/dist/lib/actor-worker.d.ts +13 -0
  19. package/dist/lib/actor-worker.js +86 -0
  20. package/dist/lib/async-runner.d.ts +5 -0
  21. package/dist/lib/async-runner.js +134 -0
  22. package/dist/lib/async-runs.js +9 -28
  23. package/dist/lib/build-dist.d.ts +5 -0
  24. package/dist/lib/build-dist.js +24 -0
  25. package/dist/lib/conformance.d.ts +12 -0
  26. package/dist/lib/conformance.js +28 -0
  27. package/dist/lib/coordinator.d.ts +5 -0
  28. package/dist/lib/coordinator.js +557 -0
  29. package/dist/lib/locker.d.ts +5 -0
  30. package/dist/lib/locker.js +310 -0
  31. package/dist/lib/mailbox-loop.d.ts +41 -0
  32. package/dist/lib/mailbox-loop.js +62 -0
  33. package/dist/lib/observability.d.ts +2 -2
  34. package/dist/lib/observability.js +51 -53
  35. package/dist/lib/prompts.d.ts +1 -1
  36. package/dist/lib/prompts.js +1 -1
  37. package/dist/lib/recipe-references.js +25 -2
  38. package/dist/lib/recipe-utils.d.ts +5 -0
  39. package/dist/lib/recipe-utils.js +385 -0
  40. package/dist/lib/runtime-notifier.js +3 -7
  41. package/dist/lib/state-readers.d.ts +21 -0
  42. package/dist/lib/state-readers.js +74 -0
  43. package/dist/lib/tools.js +1 -1
  44. package/dist/lib/validate-recipe.d.ts +6 -0
  45. package/dist/lib/validate-recipe.js +104 -0
  46. package/dist/recipes/actor-worker.json +35 -0
  47. package/dist/recipes/coordinator-locker.json +45 -0
  48. package/dist/recipes/lens-swarm.json +66 -0
  49. package/dist/recipes/locker.json +45 -0
  50. package/dist/recipes/music-player.json +38 -0
  51. package/dist/recipes/pipeline-architect-coordinator.json +95 -0
  52. package/dist/recipes/pipeline-artifact-bundle.json +100 -0
  53. package/dist/recipes/pipeline-artifact-report.json +58 -0
  54. package/dist/recipes/pipeline-artifact-write.json +72 -0
  55. package/dist/recipes/pipeline-async-run-ops.json +70 -0
  56. package/dist/recipes/pipeline-checkpoint-continuation.json +67 -0
  57. package/dist/recipes/pipeline-development-tasking.json +81 -0
  58. package/dist/recipes/pipeline-docs-maintenance.json +80 -0
  59. package/dist/recipes/pipeline-media-library.json +59 -0
  60. package/dist/recipes/pipeline-quorum-review.json +79 -0
  61. package/dist/recipes/pipeline-release-readiness.json +110 -0
  62. package/dist/recipes/pipeline-release-summary.json +88 -0
  63. package/dist/recipes/pipeline-repo-health.json +89 -0
  64. package/dist/recipes/pipeline-research-synthesis.json +94 -0
  65. package/dist/recipes/pipeline-review-readiness.json +54 -0
  66. package/dist/recipes/pipeline-room-swarm.json +50 -0
  67. package/dist/recipes/subagent-artifact.json +32 -0
  68. package/dist/recipes/subagent-checkpoint.json +33 -0
  69. package/dist/recipes/subagent-conflict-report.json +32 -0
  70. package/dist/recipes/subagent-contradiction-map.json +33 -0
  71. package/dist/recipes/subagent-critic.json +35 -0
  72. package/dist/recipes/subagent-evidence-map.json +33 -0
  73. package/dist/recipes/subagent-followup.json +33 -0
  74. package/dist/recipes/subagent-judge.json +33 -0
  75. package/dist/recipes/subagent-merge.json +33 -0
  76. package/dist/recipes/subagent-message.json +34 -0
  77. package/dist/recipes/subagent-normalize.json +31 -0
  78. package/dist/recipes/subagent-plan.json +33 -0
  79. package/dist/recipes/subagent-prompt.json +28 -0
  80. package/dist/recipes/subagent-quorum.json +43 -0
  81. package/dist/recipes/subagent-review-coordinator.json +114 -0
  82. package/dist/recipes/subagent-review.json +37 -0
  83. package/dist/recipes/subagent-task-card.json +35 -0
  84. package/dist/recipes/subagent-tools.json +27 -0
  85. package/dist/recipes/subagent-verify.json +34 -0
  86. package/dist/recipes/subagents-prompts.json +51 -0
  87. package/dist/recipes/utility-actor-message.json +23 -0
  88. package/dist/recipes/utility-artifact-manifest.json +16 -0
  89. package/dist/recipes/utility-artifact-write.json +16 -0
  90. package/dist/recipes/utility-changelog-head.json +11 -0
  91. package/dist/recipes/utility-changelog-section.json +13 -0
  92. package/dist/recipes/utility-coordinator-lock-snapshot.json +13 -0
  93. package/dist/recipes/utility-git-log.json +11 -0
  94. package/dist/recipes/utility-git-status.json +9 -0
  95. package/dist/recipes/utility-jsonl-tail.json +10 -0
  96. package/dist/recipes/utility-markdown-index.json +14 -0
  97. package/dist/recipes/utility-package-summary.json +11 -0
  98. package/dist/recipes/utility-playlist-build.json +17 -0
  99. package/dist/recipes/utility-playlist-scan.json +11 -0
  100. package/dist/recipes/utility-run-ops-snapshot.json +17 -0
  101. package/dist/recipes/utility-run-state-files.json +13 -0
  102. package/dist/recipes/utility-run-summary.json +11 -0
  103. package/dist/recipes/utility-skill-summary.json +13 -0
  104. package/dist/recipes/utility-validate-recipe.json +13 -0
  105. package/dist/recipes/utility-validation-wrapper.json +13 -0
  106. package/dist/scripts/actor-worker.mjs +31 -0
  107. package/dist/scripts/async-runner.mjs +31 -0
  108. package/dist/scripts/build-dist.mjs +25 -0
  109. package/dist/scripts/conformance.mjs +33 -0
  110. package/dist/scripts/coordinator.mjs +31 -0
  111. package/dist/scripts/locker.mjs +33 -0
  112. package/dist/scripts/music-player.mjs +964 -0
  113. package/dist/scripts/recipe-utils.mjs +31 -0
  114. package/dist/scripts/validate-recipe.mjs +34 -0
  115. package/dist/skills/actors/SKILL.md +375 -0
  116. package/dist/skills/swarm/SKILL.md +467 -0
  117. package/dist/skills/swarm/references/development-swarm.md +596 -0
  118. package/docs/actor-messages.md +2 -2
  119. package/docs/async-runs.md +11 -0
  120. package/docs/template-recipes.md +1 -1
  121. package/fixtures/protocol/actor-message-branch.json +13 -0
  122. package/fixtures/protocol/artifact-manifest.json +9 -0
  123. package/fixtures/protocol/mailbox-contract.json +15 -0
  124. package/fixtures/protocol/recipe-summary.json +16 -0
  125. package/fixtures/protocol/room-message.json +11 -0
  126. package/fixtures/protocol/room-roster.json +11 -0
  127. package/fixtures/protocol/run-inbox-message.json +9 -0
  128. package/fixtures/protocol/run-outbox-event.json +9 -0
  129. package/fixtures/protocol/run-state.json +10 -0
  130. package/index.ts +3 -0
  131. package/lib/actor-inspector-tui.ts +11 -34
  132. package/lib/actor-rooms.ts +88 -18
  133. package/lib/actor-worker.ts +118 -0
  134. package/lib/async-runner.ts +173 -0
  135. package/lib/async-runs.ts +12 -22
  136. package/lib/build-dist.ts +30 -0
  137. package/lib/conformance.ts +46 -0
  138. package/lib/coordinator.ts +649 -0
  139. package/lib/locker.ts +340 -0
  140. package/lib/mailbox-loop.ts +148 -0
  141. package/lib/observability.ts +24 -19
  142. package/lib/prompts.ts +1 -1
  143. package/lib/recipe-references.ts +37 -2
  144. package/lib/recipe-utils.ts +486 -0
  145. package/lib/runtime-notifier.ts +4 -6
  146. package/lib/state-readers.ts +93 -0
  147. package/lib/tools.ts +1 -1
  148. package/lib/validate-recipe.ts +110 -0
  149. package/package.json +10 -2
  150. package/recipes/actor-worker.json +35 -0
  151. package/recipes/pipeline-quorum-review.json +12 -7
  152. package/scripts/actor-worker.mjs +31 -0
  153. package/scripts/async-runner.mjs +11 -201
  154. package/scripts/build-dist.mjs +25 -0
  155. package/scripts/conformance.mjs +21 -35
  156. package/scripts/coordinator.mjs +15 -625
  157. package/scripts/locker.mjs +20 -332
  158. package/scripts/recipe-utils.mjs +17 -477
  159. package/scripts/validate-recipe.mjs +18 -121
  160. package/skills/actors/SKILL.md +5 -2
  161. package/skills/swarm/SKILL.md +3 -1
@@ -12,6 +12,7 @@ import { basename, dirname, extname, join, resolve } from "node:path";
12
12
  import { fileURLToPath } from "node:url";
13
13
  import { substituteCommandTemplateToken } from "./command-templates.js";
14
14
  import { writeJsonAtomic } from "./file-state.js";
15
+ import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.js";
15
16
  import * as Paths from "./paths.js";
16
17
  import * as RecipeReferences from "./recipe-references.js";
17
18
  import * as RecipeUsage from "./recipe-usage.js";
@@ -189,12 +190,7 @@ function resolveStartParams(params) {
189
190
  };
190
191
  }
191
192
  function readJson(path) {
192
- try {
193
- return JSON.parse(readFileSync(path, "utf8"));
194
- }
195
- catch {
196
- return undefined;
197
- }
193
+ return readJsonFileResilient(path, undefined).value;
198
194
  }
199
195
  function isAlive(pid) {
200
196
  try {
@@ -232,20 +228,12 @@ function tailLines(path, lines) {
232
228
  return content ? content.split("\n") : [];
233
229
  }
234
230
  function getInterruptedRunStatus(stateDir) {
235
- const events = tailFile(join(stateDir, "events.jsonl"), 200);
236
- if (!events)
237
- return undefined;
238
- for (const line of events.split("\n").reverse()) {
239
- try {
240
- const event = JSON.parse(line);
241
- if (event.event === "run.kill")
242
- return "killed";
243
- if (event.event === "run.cancel")
244
- return "cancelled";
245
- }
246
- catch {
247
- // Ignore malformed event lines.
248
- }
231
+ const events = readJsonlFileResilient(join(stateDir, "events.jsonl")).records.slice(-200);
232
+ for (const event of events.reverse()) {
233
+ if (event.event === "run.kill")
234
+ return "killed";
235
+ if (event.event === "run.cancel")
236
+ return "cancelled";
249
237
  }
250
238
  return undefined;
251
239
  }
@@ -655,14 +643,7 @@ function parseRunInboxLine(line) {
655
643
  }
656
644
  }
657
645
  function readRunInboxMessagesFromStateDir(stateDir) {
658
- const file = runInboxFile(stateDir);
659
- if (!existsSync(file))
660
- return [];
661
- return readFileSync(file, "utf8")
662
- .split("\n")
663
- .filter((line) => line.trim())
664
- .map(parseRunInboxLine)
665
- .filter((message) => Boolean(message));
646
+ return readJsonlFileResilient(runInboxFile(stateDir)).records;
666
647
  }
667
648
  function writeRunInboxMessages(stateDir, messages) {
668
649
  writeFileSync(runInboxFile(stateDir), messages.length
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Dist build pipeline entrypoint logic.
3
+ * Zones: packaging, JavaScript-only distributive tree
4
+ */
5
+ export declare function buildDist(): void;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Dist build pipeline entrypoint logic.
3
+ * Zones: packaging, JavaScript-only distributive tree
4
+ */
5
+ import { spawnSync } from "node:child_process";
6
+ import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
7
+ import { join } from "node:path";
8
+ function run(command, args) {
9
+ const result = spawnSync(command, args, { stdio: "inherit" });
10
+ if (result.status !== 0)
11
+ process.exit(result.status ?? 1);
12
+ }
13
+ export function buildDist() {
14
+ rmSync("dist", { recursive: true, force: true });
15
+ mkdirSync("dist", { recursive: true });
16
+ run("tsc", ["-p", "tsconfig.build.json"]);
17
+ for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
18
+ cpSync(dir, join("dist", dir), { recursive: true });
19
+ }
20
+ const builtScripts = readdirSync(join("dist", "scripts"))
21
+ .filter((name) => name.endsWith(".mjs"))
22
+ .map((name) => join("dist", "scripts", name));
23
+ run(process.execPath, ["--check", ...builtScripts]);
24
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Internal conformance runner logic.
3
+ * Zones: CI/release validation, protocol regression suite selection
4
+ */
5
+ export declare const conformanceSuites: string[];
6
+ export interface ConformanceReport {
7
+ code: number;
8
+ output: string;
9
+ summary: string;
10
+ suites: number;
11
+ }
12
+ export declare function runConformance(cwd?: URL): ConformanceReport;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Internal conformance runner logic.
3
+ * Zones: CI/release validation, protocol regression suite selection
4
+ */
5
+ import { spawnSync } from "node:child_process";
6
+ export const conformanceSuites = [
7
+ "tests/protocol-examples.test.ts",
8
+ "tests/recipe-discovery.test.ts",
9
+ "tests/registry.test.ts",
10
+ "tests/runtime-registry.test.ts",
11
+ "tests/async-runs.test.ts",
12
+ "tests/actor-rooms.test.ts",
13
+ "tests/tools.test.ts",
14
+ ];
15
+ export function runConformance(cwd = new URL("..", import.meta.url)) {
16
+ const result = spawnSync(process.execPath, ["--experimental-strip-types", "--test", ...conformanceSuites], { cwd, encoding: "utf8", stdio: "pipe" });
17
+ const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
18
+ const summary = output
19
+ .split("\n")
20
+ .filter((line) => /^ℹ (tests|pass|fail|cancelled|skipped|todo|duration_ms) /.test(line))
21
+ .join("\n");
22
+ return {
23
+ code: result.status ?? 1,
24
+ output,
25
+ summary,
26
+ suites: conformanceSuites.length,
27
+ };
28
+ }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Multi-actor coordinator helper entrypoint logic.
3
+ * Zones: swarm coordination, worker pool orchestration
4
+ */
5
+ export declare function runCoordinator(argv?: string[]): Promise<void>;