@llblab/pi-actors 0.42.3 → 0.43.1

package/docs/task-first-recipes.md

@@ -1,263 +0,0 @@
-# Task-First Recipe Design
-
-Task-first recipe design starts from a high-level operator or coordinator task, then derives the component cells, utility recipes, helper scripts, and runtime semantics needed to make that task reusable.
-
-This complements atom-first growth. Atom-first asks: "What small capability can we expose?" Task-first asks: "What complete work pattern should an agent/operator be able to invoke, and which atoms must exist to support it?"
-
-## Method
-
-For each high-level recipe candidate:
-
-1. Name the task in operator language.
-2. Define the trigger and expected output artifact.
-3. Sketch the recipe pipeline at the highest useful abstraction.
-4. Identify missing component cells.
-5. Decide which cells are subagent components, local utilities, or helper-backed transforms.
-6. Keep domain policy knobs public: models, tools, paths, evidence/risk policy, output shape, mailbox contract, and validation gates.
-7. Add only the next smallest recipe/helper slice that validates the design.
-
-## High-Level Recipe Cells
-
-### Release Readiness Cell
-
-Purpose: decide whether a repo/package is ready for release.
-
-Pipeline:
-
-```text
-scope snapshot → changelog/package check → release lens reviews → risk verifier → readiness report → release checklist artifact
-```
-
-Likely needed cells:
-
-- Package metadata reader
-- Changelog section extractor
-- Package contents summarizer
-- Validation command wrapper
-- Release-risk reviewer
-- Readiness merger/judge
-- Release checklist artifact writer
-
-Existing seeds:
-
-- `utility-changelog-section`
-- `utility-package-summary`
-- `utility-validation-wrapper`
-- `pipeline-review-readiness`
-- `subagent-judge`
-- `subagent-artifact`
-
-Implemented seed:
-
-- `pipeline-release-readiness`: changelog section → package summary → packaged skill summary → validation wrapper → release review coordinator → artifact report.
-
-### Repository Health Cell
-
-Purpose: summarize repo state for the next coordinator turn or release prep.
-
-Pipeline:
-
-```text
-git status/log → package/docs/backlog snapshot → validation summary → health report → next action recommendation
-```
-
-Likely needed cells:
-
-- Git status/log utility
-- Package version reader
-- Backlog open/blocked extractor
-- Docs index checker
-- Validation summary normalizer
-- Next-action recommender
-
-Existing seeds:
-
-- `utility-markdown-index`
-- `utility-validation-wrapper`
-- `subagent-normalize`
-- `subagent-plan`
-
-Implemented seed:
-
-- `pipeline-repo-health`: git status/log → docs index → validation wrapper → normalized artifact report.
-
-### Async Run Operations Cell
-
-Purpose: inspect, summarize, and decide actions for local async runs.
-
-Pipeline:
-
-```text
-run-state summary → actor-message tail → stale/active classification → recommended action → optional stop/control message
-```
-
-Likely needed cells:
-
-- Run summary helper
-- JSONL actor-message tailer
-- Stale-run classifier
-- Control-message recommender
-- Run report artifact
-
-Existing seeds:
-
-- `utility-run-summary`
-- `utility-jsonl-tail`
-- `subagent-message`
-- `pipeline-artifact-report`
-
-Implemented seed:
-
-- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines run summary, actor-message tail, and recommended inspect/control messages before the LLM normalization step.
-
-### Research Brief Cell
-
-Purpose: turn a question and source set into a bounded evidence-backed brief.
-
-Pipeline:
-
-```text
-question framing → evidence map → contradiction map → claim verification → synthesis → evidence gaps → next evidence slice
-```
-
-Likely needed cells:
-
-- Question framer
-- Source inventory utility
-- Evidence mapper
-- Contradiction mapper
-- Verifier
-- Synthesis merger
-- Limitations normalizer
-
-Existing seeds:
-
-- `pipeline-research-synthesis`
-- `subagent-evidence-map`
-- `subagent-contradiction-map`
-- `subagent-verify`
-
-### Consensus-First Build Cell
-
-Purpose: turn several expert proposals into one coherent artifact without parallel writers fragmenting the result.
-
-Pipeline:
-
-```text
-mission → lens proposers in room → consensus transcript → named implementer writes artifact → QA reviewer checks artifact + transcript → finalizer applies fixes → artifact assertions
-```
-
-Use this for creative demos, single-file artifacts, specs, docs, prompt packs, and product/UX deliverables where broad input matters but one owner should shape the final file. Proposers should have message/inspect tools only. The implementer should be the first role with write tools. QA should inspect/read but not mutate. The finalizer may write only after reading QA evidence.
-
-Required gates:
-
-- Artifact path, report path, and minimum acceptance checks are explicit inputs.
-- The workflow fails if the requested artifact is missing, too small, or not self-contained enough for the task.
-- `run.done` is emitted only after QA/finalizer passes, not merely after room discussion.
-
-Existing seeds:
-
-- `pipeline-room-swarm` for room-visible discussion and rosters.
-- `subagent-message` for explicit room handoffs.
-- `subagent-review` / `subagent-verify` for QA roles.
-- `pipeline-artifact-write` or a small helper script for deterministic artifact assertion.
-
-Next recipe direction:
-
-- Add a generic packaged consensus-build pipeline once the interface stabilizes around proposer roles, implementer prompt, QA prompt, artifact assertions, and public model/tool knobs.
-
-### Implementation Tasking Cell
-
-Purpose: prepare bounded work for one or more implementation agents.
-
-Pipeline:
-
-```text
-goal → mutation zones → task cards → validation gates → conflict risks → integrator handoff
-```
-
-Likely needed cells:
-
-- Mutation-zone planner
-- Task-card generator
-- Ownership/conflict checker
-- Validation-gate normalizer
-- Integrator handoff artifact
-
-Existing seeds:
-
-- `pipeline-development-tasking`
-- `subagent-task-card`
-- `subagent-conflict-report`
-
-### Documentation Maintenance Cell
-
-Purpose: keep docs/index/readme surfaces coherent after changes.
-
-Pipeline:
-
-```text
-doc file inventory → index diff → stale link/routing review → rewrite suggestion → docs maintenance artifact
-```
-
-Likely needed cells:
-
-- Markdown index utility
-- Link checker wrapper
-- Docs consistency reviewer
-- Docs update planner
-- Docs artifact writer
-
-Existing seeds:
-
-- `utility-markdown-index`
-- `subagent-review`
-- `subagent-plan`
-- `subagent-artifact`
-
-Implemented seed:
-
-- `pipeline-docs-maintenance`: docs index → documentation review → maintenance plan → artifact report.
-
-### Media/Playlist Operations Cell
-
-Purpose: convert local media directories into controllable playback workflows.
-
-Pipeline:
-
-```text
-media scan → playlist build → playback start → message summary → controls
-```
-
-Likely needed cells:
-
-- Playlist builder
-- Music player
-- Run/message summary
-- Control recommender
-
-Existing seeds:
-
-- `utility-playlist-build`
-- `music-player`
-- `utility-run-summary`
-- `utility-jsonl-tail`
-
-Implemented seed:
-
-- `pipeline-media-library`: playlist build → media-library artifact report.
-
-## Selection Rule
-
-Prefer adding a high-level recipe when at least three cells already exist and the missing cells are small. Prefer adding an atom when multiple high-level recipes need the same missing cell.
-
-## Near-Term Candidates
-
-Good next candidates for the standard library after the first task-first wave:
-
-1. Package/release metadata enrichment: implemented in `pipeline-release-readiness` by adding `utility-package-summary` and `utility-skill-summary` between changelog extraction and validation, making release-readiness reports more evidence-rich without adding publish automation.
-2. Evidence-only release summary: implemented as `pipeline-release-summary`, which composes changelog/package/skill/validation evidence into a release summary, risk checklist, and PR body draft artifact while leaving commit, PR, merge, tag, and publish actions to explicit release gates.
-3. Artifact packaging and manifesting: implemented as `pipeline-artifact-bundle`, which composes optional validation, `pipeline-artifact-write`, `utility-artifact-manifest`, deterministic manifest writing, and an actor-message handoff when the caller explicitly requests filesystem writes.
-4. Async run cleanup planning: extend async-run operations with stale-run classification and recommended `message`, `cancel`, or `kill` controls, keeping actual control execution operator-gated.
-
-Each candidate should land with the minimum missing cells rather than a broad one-shot framework. Already implemented task-first seeds include `pipeline-release-readiness`, `pipeline-release-summary`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle`.

package/fixtures/protocol/actor-message-branch.json

@@ -1,13 +0,0 @@
-{
-  "to": "branch:demo/reviewer",
-  "from": "run:demo",
-  "type": "task.assign",
-  "summary": "Review the current slice",
-  "body": {
-    "task": "Check mailbox loop semantics"
-  },
-  "correlation_id": "task-001",
-  "metadata": {
-    "requires_response": true
-  }
-}

package/fixtures/protocol/mailbox-contract.json

@@ -1,15 +0,0 @@
-{
-  "accepts": [
-    "task.assign",
-    {
-      "type": "control.stop",
-      "description": "Request graceful worker shutdown"
-    }
-  ],
-  "emits": [
-    "task.claim",
-    "task.result",
-    "awaiting_assignment",
-    "actor.leave"
-  ]
-}

package/fixtures/protocol/room-message.json

@@ -1,11 +0,0 @@
-{
-  "to": "room:demo",
-  "from": "branch:demo/worker",
-  "type": "task.result",
-  "summary": "Worker completed task",
-  "body": {
-    "id": "inbox-001",
-    "result": "ok"
-  },
-  "received_at": "2026-05-26T00:00:00.000Z"
-}

package/fixtures/protocol/room-roster.json

@@ -1,11 +0,0 @@
-{
-  "room": "main",
-  "members": {
-    "branch:demo/worker": {
-      "display": "worker",
-      "role": "worker",
-      "status": "present",
-      "last_seen": "2026-05-26T00:00:00.000Z"
-    }
-  }
-}

package/fixtures/protocol/run-inbox-message.json

@@ -1,9 +0,0 @@
-{
-  "id": "inbox-001",
-  "status": "queued",
-  "queued_at": "2026-05-26T00:00:00.000Z",
-  "to": "run:demo",
-  "from": "coordinator",
-  "type": "control.continue",
-  "body": "continue"
-}

package/fixtures/protocol/run-outbox-event.json

@@ -1,9 +0,0 @@
-{
-  "id": "event-001",
-  "type": "task.result",
-  "summary": "Worker completed task",
-  "body": {
-    "result": "ok"
-  },
-  "created_at": "2026-05-26T00:00:00.000Z"
-}

package/lib/mailbox-loop.ts

@@ -1,144 +0,0 @@
-/**
- * Mailbox worker loop primitives.
- * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
- * Owns reusable claim/handle/drain behavior across run and branch inboxes; scheduling and task policy stay outside.
- */
-
-import {
-  claimBranchInboxMessage,
-  updateBranchInboxMessageStatus,
-  type BranchInboxRecord,
-} from "./rooms.ts";
-import {
-  claimRunInboxMessage,
-  updateRunInboxMessageStatus,
-  type RunInboxMessage,
-} from "./async-runs.ts";
-
-export type MailboxLoopMessage = RunInboxMessage | BranchInboxRecord;
-
-export type MailboxLoopTarget =
-  | {
-      kind: "run";
-      runOrDir: string;
-    }
-  | {
-      address: string;
-      kind: "branch";
-      run: string;
-      stateDir: string;
-    };
-
-export interface MailboxLoopClaimOptions {
-  owner?: string;
-  statuses?: string[];
-}
-
-export interface MailboxLoopHandleResult {
-  handled: boolean;
-  id?: string;
-  message?: MailboxLoopMessage;
-  target: MailboxLoopTarget;
-}
-
-export interface MailboxLoopDrainOptions extends MailboxLoopClaimOptions {
-  maxMessages?: number;
-  stopOnControl?: boolean;
-}
-
-export interface MailboxLoopDrainResult {
-  handled: number;
-  stopped: boolean;
-  target: MailboxLoopTarget;
-}
-
-export function isMailboxLoopStopMessage(message: unknown): boolean {
-  const type =
-    message && typeof message === "object" && "type" in message
-      ? (message as { type?: unknown }).type
-      : undefined;
-  return type === "control.kill";
-}
-
-function messageId(
-  message: MailboxLoopMessage | undefined,
-): string | undefined {
-  return typeof message?.id === "string" ? message.id : undefined;
-}
-
-export function claimMailboxLoopMessage(
-  target: MailboxLoopTarget,
-  options: MailboxLoopClaimOptions = {},
-): MailboxLoopMessage | undefined {
-  const owner = options.owner ?? "mailbox-loop";
-  const statuses = options.statuses ?? ["queued"];
-  return target.kind === "run"
-    ? claimRunInboxMessage(target.runOrDir, owner, statuses)
-    : claimBranchInboxMessage(
-        target.stateDir,
-        target.run,
-        target.address,
-        owner,
-        statuses,
-      );
-}
-
-export function updateMailboxLoopMessageStatus(
-  target: MailboxLoopTarget,
-  id: string,
-  status: "claimed" | "handled" | "failed",
-  metadata: Record<string, unknown> = {},
-): boolean {
-  return target.kind === "run"
-    ? updateRunInboxMessageStatus(target.runOrDir, id, status, metadata)
-    : updateBranchInboxMessageStatus(
-        target.stateDir,
-        target.run,
-        target.address,
-        id,
-        status,
-        metadata,
-      );
-}
-
-export async function handleMailboxLoopOnce(
-  target: MailboxLoopTarget,
-  handler: (message: MailboxLoopMessage) => Promise<void> | void,
-  options: MailboxLoopClaimOptions = {},
-): Promise<MailboxLoopHandleResult> {
-  const message = claimMailboxLoopMessage(target, options);
-  const id = messageId(message);
-  if (!message || !id) return { handled: false, target };
-  try {
-    await handler(message);
-    updateMailboxLoopMessageStatus(target, id, "handled");
-    return { handled: true, id, message, target };
-  } catch (error) {
-    updateMailboxLoopMessageStatus(target, id, "failed", {
-      error: error instanceof Error ? error.message : String(error),
-    });
-    throw error;
-  }
-}
-
-export async function drainMailboxLoopMessages(
-  target: MailboxLoopTarget,
-  handler: (message: MailboxLoopMessage) => Promise<void> | void,
-  options: MailboxLoopDrainOptions = {},
-): Promise<MailboxLoopDrainResult> {
-  const maxMessages = Math.max(1, Math.floor(options.maxMessages ?? 100));
-  let handled = 0;
-  for (; handled < maxMessages; handled += 1) {
-    const result = await handleMailboxLoopOnce(target, handler, options);
-    if (!result.handled || !result.message) {
-      return { handled, stopped: false, target };
-    }
-    if (
-      options.stopOnControl !== false &&
-      isMailboxLoopStopMessage(result.message)
-    ) {
-      return { handled: handled + 1, stopped: true, target };
-    }
-  }
-  return { handled, stopped: false, target };
-}

package/lib/messages.ts

@@ -1,151 +0,0 @@
-/**
- * Actor message protocol.
- * Zones: addressed envelopes, address parsing, route normalization
- * Owns pure validation/normalization for semantic actor messages; transport routing stays in adapters.
- */
-
-export type ActorAddressKind =
-  | "branch"
-  | "coordinator"
-  | "room"
-  | "run"
-  | "session"
-  | "tool";
-
-export interface ActorAddress {
-  kind: ActorAddressKind;
-  value?: string;
-  branch?: string;
-  room?: string;
-}
-
-export interface ActorMessage {
-  to: string;
-  type: string;
-  body?: unknown;
-  correlation_id?: string;
-  from?: string;
-  metadata?: Record<string, unknown>;
-  reply_to?: string;
-  summary?: string;
-}
-
-const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
-const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
-
-function assertToken(value: string, label: string): string {
-  const normalized = value.trim();
-  if (!normalized) throw new Error(`${label} is required`);
-  if (!ADDRESS_PATTERN.test(normalized)) {
-    throw new Error(`${label} contains unsupported characters: ${value}`);
-  }
-  return normalized;
-}
-
-export function parseActorAddress(address: string): ActorAddress {
-  const value = address.trim();
-  if (value === "coordinator") return { kind: "coordinator" };
-  const separator = value.indexOf(":");
-  if (separator < 0)
-    throw new Error(`Actor address must include kind: ${address}`);
-  const kind = value.slice(0, separator) as ActorAddressKind;
-  const rest = value.slice(separator + 1);
-  switch (kind) {
-    case "branch": {
-      const [run, branch, ...extra] = rest.split("/");
-      if (extra.length > 0)
-        throw new Error(`Branch address has too many parts: ${address}`);
-      return {
-        kind,
-        value: assertToken(run || "", "branch run"),
-        branch: assertToken(branch || "", "branch id"),
-      };
-    }
-    case "room": {
-      const [run, room, ...extra] = rest.split("/");
-      if (extra.length > 0)
-        throw new Error(`Room address has too many parts: ${address}`);
-      if (room && room !== "main") {
-        throw new Error("Task rooms do not support named subrooms; use room:<run>.");
-      }
-      return {
-        kind,
-        value: assertToken(run || "", "room run"),
-        room: "main",
-      };
-    }
-    case "run":
-    case "session":
-    case "tool":
-      return { kind, value: assertToken(rest, `${kind} address`) };
-    default:
-      throw new Error(`Unsupported actor address kind: ${kind}`);
-  }
-}
-
-export function formatActorAddress(address: ActorAddress): string {
-  if (address.kind === "coordinator") return "coordinator";
-  if (address.kind === "branch") {
-    return `branch:${assertToken(address.value || "", "branch run")}/${assertToken(address.branch || "", "branch id")}`;
-  }
-  if (address.kind === "room") {
-    return `room:${assertToken(address.value || "", "room run")}`;
-  }
-  return `${address.kind}:${assertToken(address.value || "", `${address.kind} address`)}`;
-}
-
-function normalizeOptionalString(
-  value: unknown,
-  label: string,
-): string | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value !== "string") throw new Error(`${label} must be a string`);
-  const normalized = value.trim();
-  return normalized || undefined;
-}
-
-function normalizeMetadata(
-  value: unknown,
-): Record<string, unknown> | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("message metadata must be an object");
-  }
-  return value as Record<string, unknown>;
-}
-
-export function normalizeActorMessage(input: unknown): ActorMessage {
-  if (!input || typeof input !== "object" || Array.isArray(input)) {
-    throw new Error("actor message must be an object");
-  }
-  const record = input as Record<string, unknown>;
-  const to = normalizeOptionalString(record.to, "message.to");
-  if (!to) throw new Error("message.to is required");
-  const parsedTo = parseActorAddress(to);
-  const type = normalizeOptionalString(record.type, "message.type");
-  if (!type) throw new Error("message.type is required");
-  if (!MESSAGE_TYPE_PATTERN.test(type)) {
-    throw new Error(`message.type contains unsupported characters: ${type}`);
-  }
-  const from = normalizeOptionalString(record.from, "message.from");
-  if (from) parseActorAddress(from);
-  const normalizedTo = formatActorAddress(parsedTo);
-  return {
-    to: normalizedTo,
-    type,
-    ...(record.body !== undefined ? { body: record.body } : {}),
-    ...(record.correlation_id !== undefined
-      ? { correlation_id: String(record.correlation_id) }
-      : {}),
-    ...(from ? { from: formatActorAddress(parseActorAddress(from)) } : {}),
-    ...(record.metadata !== undefined
-      ? { metadata: normalizeMetadata(record.metadata) }
-      : {}),
-    ...(record.reply_to !== undefined
-      ? { reply_to: String(record.reply_to) }
-      : {}),
-    ...(record.summary !== undefined
-      ? { summary: String(record.summary) }
-      : {}),
-  };
-}