@llblab/pi-actors 0.41.1 → 0.42.0

package/lib/tool-review.ts

@@ -0,0 +1,270 @@
+/**
+ * Automatic active-tool portfolio review contract.
+ * Zones: thirty-six-tool reviewer input, evolution decisions, mechanical contract gates
+ * Owns strict read-only keep/evolve/replace/demote/merge/split review semantics.
+ */
+
+export const TOOL_REVIEW_THRESHOLD = 36;
+
+export interface ToolReviewAssessment {
+  adaptability: number;
+  futureUsefulness: number;
+  lifetimeCalls: number;
+  redundancy: number;
+  revisionCalls: number;
+  safety: string;
+}
+
+export interface ToolReviewTool {
+  name: string;
+  path: string;
+  recipe: Record<string, unknown>;
+  riskLabels: string[];
+  sha256: string;
+  usage?: Record<string, unknown>;
+  valid: boolean;
+}
+
+export interface ToolReviewInput {
+  createdAt: string;
+  reviewId: string;
+  tools: ToolReviewTool[];
+}
+
+export interface ToolReviewOutputRecipe {
+  name: string;
+  recipe: Record<string, unknown>;
+}
+
+export type ToolReviewAction =
+  | "demote"
+  | "evolve"
+  | "keep"
+  | "merge"
+  | "replace"
+  | "split";
+
+export interface ToolReviewDecision {
+  action: ToolReviewAction;
+  assessment: ToolReviewAssessment;
+  rationale: string;
+  recipe?: Record<string, unknown>;
+  sha256: string;
+  source: string;
+  target?: string;
+  outputs?: ToolReviewOutputRecipe[];
+}
+
+export interface ToolReviewResult {
+  createdAt: string;
+  decisions: ToolReviewDecision[];
+  reviewId: string;
+}
+
+export interface ToolReviewValidation {
+  errors: string[];
+  ok: boolean;
+}
+
+const UUID_PATTERN = /^[a-f0-9-]{36}$/u;
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/u;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (!isRecord(value)) return JSON.stringify(value);
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+    .join(",")}}`;
+}
+
+function finiteScore(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function calls(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0
+    ? value
+    : 0;
+}
+
+function validateAssessment(
+  assessment: unknown,
+  tool: ToolReviewTool,
+  errors: string[],
+): void {
+  if (
+    !isRecord(assessment) ||
+    !finiteScore(assessment.adaptability) ||
+    !finiteScore(assessment.futureUsefulness) ||
+    !finiteScore(assessment.redundancy) ||
+    typeof assessment.safety !== "string" ||
+    !assessment.safety.trim() ||
+    !Number.isInteger(assessment.lifetimeCalls) ||
+    Number(assessment.lifetimeCalls) < 0 ||
+    !Number.isInteger(assessment.revisionCalls) ||
+    Number(assessment.revisionCalls) < 0
+  ) {
+    errors.push(`invalid tool assessment: ${tool.name}`);
+    return;
+  }
+  if (assessment.lifetimeCalls !== calls(tool.usage?.lifetime_calls ?? tool.usage?.calls)) {
+    errors.push(`tool lifetime calls differ from lineage: ${tool.name}`);
+  }
+  if (assessment.revisionCalls !== calls(tool.usage?.revision_calls)) {
+    errors.push(`tool revision calls differ from lineage: ${tool.name}`);
+  }
+}
+
+export function validateToolReviewInput(input: ToolReviewInput): ToolReviewValidation {
+  const errors: string[] = [];
+  if (!UUID_PATTERN.test(input.reviewId)) errors.push("tool reviewId must be a UUID");
+  if (!input.createdAt || Number.isNaN(Date.parse(input.createdAt))) {
+    errors.push("tool review createdAt must be an ISO timestamp");
+  }
+  if (!Array.isArray(input.tools) || input.tools.length !== TOOL_REVIEW_THRESHOLD) {
+    errors.push(`tool review input must contain exactly ${TOOL_REVIEW_THRESHOLD} tools`);
+  }
+  const names = new Set<string>();
+  for (const tool of input.tools ?? []) {
+    if (
+      !tool ||
+      !TOOL_NAME_PATTERN.test(tool.name) ||
+      typeof tool.path !== "string" ||
+      typeof tool.sha256 !== "string" ||
+      typeof tool.valid !== "boolean" ||
+      !isRecord(tool.recipe) ||
+      !Array.isArray(tool.riskLabels) ||
+      names.has(tool.name)
+    ) {
+      errors.push(`invalid or duplicate reviewed tool: ${String(tool?.name)}`);
+      continue;
+    }
+    names.add(tool.name);
+  }
+  return { errors, ok: errors.length === 0 };
+}
+
+export function validateToolReviewResult(
+  input: ToolReviewInput,
+  result: ToolReviewResult,
+): ToolReviewValidation {
+  const errors = [...validateToolReviewInput(input).errors];
+  if (result.reviewId !== input.reviewId) errors.push("tool review identity mismatch");
+  if (!result.createdAt || Number.isNaN(Date.parse(result.createdAt))) {
+    errors.push("tool review result createdAt must be an ISO timestamp");
+  }
+  if (!Array.isArray(result.decisions)) {
+    errors.push("tool review decisions must be an array");
+    return { errors, ok: false };
+  }
+  const inventory = new Map(input.tools.map((tool) => [tool.name, tool]));
+  const activeNames = new Set(inventory.keys());
+  const seen = new Set<string>();
+  const outputNames = new Set<string>();
+  const mergeGroups = new Map<string, Array<{ decision: ToolReviewDecision; recipe: string }>>();
+  for (const decision of result.decisions) {
+    const tool = inventory.get(decision.source);
+    if (!tool) {
+      errors.push(`unknown reviewed tool: ${decision.source}`);
+      continue;
+    }
+    if (seen.has(decision.source)) {
+      errors.push(`duplicate tool decision: ${decision.source}`);
+      continue;
+    }
+    seen.add(decision.source);
+    if (decision.sha256 !== tool.sha256) errors.push(`reviewed tool changed: ${tool.name}`);
+    if (!decision.rationale?.trim()) errors.push(`missing tool rationale: ${tool.name}`);
+    validateAssessment(decision.assessment, tool, errors);
+    if (decision.action === "keep" || decision.action === "demote") {
+      if (decision.target || decision.recipe || decision.outputs) {
+        errors.push(`${decision.action} declares evolution fields: ${tool.name}`);
+      }
+      continue;
+    }
+    if (decision.action === "replace" || decision.action === "split") {
+      errors.push(`${decision.action} requires explicit operator-authored recipe mutation: ${tool.name}`);
+      continue;
+    }
+    if (decision.action === "evolve") {
+      if (!decision.target || !TOOL_NAME_PATTERN.test(decision.target)) {
+        errors.push(`evolve requires snake_case target: ${tool.name}`);
+      }
+      if (decision.recipe !== undefined || decision.outputs !== undefined) {
+        errors.push(`evolve must not supply executable recipe content: ${tool.name}`);
+      }
+      if (
+        decision.target &&
+        activeNames.has(decision.target) &&
+        decision.target !== tool.name
+      ) {
+        errors.push(`evolve target collides with active tool: ${decision.target}`);
+      }
+      if (decision.target && outputNames.has(decision.target)) {
+        errors.push(`duplicate evolved target: ${decision.target}`);
+      } else if (decision.target) outputNames.add(decision.target);
+      continue;
+    }
+    if (decision.action === "merge") {
+      if (!decision.target || !TOOL_NAME_PATTERN.test(decision.target)) {
+        errors.push(`merge requires snake_case target: ${tool.name}`);
+        continue;
+      }
+      if (decision.recipe !== undefined || decision.outputs !== undefined) {
+        errors.push(`merge must not supply executable recipe content: ${tool.name}`);
+      }
+      const group = mergeGroups.get(decision.target) ?? [];
+      group.push({ decision, recipe: canonicalJson(tool.recipe) });
+      mergeGroups.set(decision.target, group);
+      continue;
+    }
+    errors.push(`invalid tool review action: ${tool.name}`);
+  }
+  for (const tool of input.tools) {
+    if (!seen.has(tool.name)) errors.push(`missing tool decision: ${tool.name}`);
+  }
+  for (const [target, group] of mergeGroups) {
+    if (group.length < 2) errors.push(`merge target requires at least two sources: ${target}`);
+    if (
+      activeNames.has(target) &&
+      !group.some((entry) => entry.decision.source === target)
+    ) {
+      errors.push(`merge target collides with unrelated active tool: ${target}`);
+    }
+    if (new Set(group.map((entry) => entry.recipe)).size !== 1) {
+      errors.push(`merge target recipes differ: ${target}`);
+    }
+    if (outputNames.has(target)) errors.push(`duplicate evolved target: ${target}`);
+    outputNames.add(target);
+  }
+  return { errors, ok: errors.length === 0 };
+}
+
+export function parseToolReviewResult(stdout: string): ToolReviewResult {
+  const marker = "TOOL_REVIEW_RESULT";
+  const markerIndex = stdout.lastIndexOf(marker);
+  if (markerIndex < 0) throw new Error("Tool reviewer output marker is missing.");
+  const payload = stdout.slice(markerIndex + marker.length).trim();
+  if (!payload.startsWith("{") || !payload.endsWith("}")) {
+    throw new Error("Tool reviewer output must end with one JSON object.");
+  }
+  const value = JSON.parse(payload) as unknown;
+  if (!isRecord(value)) throw new Error("Tool reviewer result must be an object.");
+  return value as unknown as ToolReviewResult;
+}
+
+export function createToolReviewPrompt(inputPath: string): string {
+  return [
+    `Review the attached immutable active-tool portfolio from ${inputPath}.`,
+    "Evaluate all 36 tools independently from lifetime/revision usage, adaptability, redundancy, safety, contract quality, and likely future usefulness.",
+    "Choose exactly one action per source: keep, evolve, demote, or merge. There is no quota for any action.",
+    "evolve may only rename one unchanged captured recipe; demote moves the unchanged recipe to draft memory; merge may only deduplicate at least two canonically identical captured recipes. Never return recipe or outputs fields. replace and split require explicit operator-authored mutation and are unavailable to automatic review.",
+    "Do not mutate, register, move, or delete recipes. You are a read-only selector; the deterministic executor derives exact recipe bytes from captured sources and owns every portfolio mutation.",
+    "End stdout with TOOL_REVIEW_RESULT on its own line followed by exactly one JSON object with reviewId, createdAt, and decisions.",
+  ].join("\n");
+}

package/lib/tools-inspect.ts

@@ -13,6 +13,7 @@ import * as Limits from "./limits.ts";
 import * as Messages from "./messages.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as ReviewDiagnostics from "./review-diagnostics.ts";
 import * as Rooms from "./rooms.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsAccess from "./tools-access.ts";
@@ -22,6 +23,17 @@ import * as ToolsResponse from "./tools-response.ts";
 const asRecord = ToolsResponse.asRecord;
 const maybeJsonText = ToolsResponse.maybeJsonText;
 
+function compactAutomaticReviewDiagnostics(
+  diagnostics: Record<string, unknown>,
+): string {
+  const draft = asRecord(diagnostics.draft_review);
+  const tool = asRecord(diagnostics.tool_review);
+  return [
+    `automatic_reviews draft=${String(draft.phase ?? "idle")} tool=${String(tool.phase ?? "idle")}`,
+    `lineages=${String(diagnostics.lineage_count ?? 0)} revision_snapshots=${String(diagnostics.revision_snapshots ?? 0)}`,
+  ].join("\n");
+}
+
 function compactRunMessages(messages: AsyncRuns.RunOutboxEvent[]): string {
   if (messages.length === 0) return "\n(no actor messages)";
   return `\n${messages
@@ -259,6 +271,7 @@ function getPiActorsRuntimeStatus(): Record<string, unknown> {
   }
   const entrypoint = new URL(import.meta.url).pathname;
   return {
+    automatic_recipe_review: Paths.isAutomaticRecipeReviewEnabled(),
     entrypoint,
     git_commit,
     mode: entrypoint.includes("/dist/") ? "dist" : "source",
@@ -271,7 +284,7 @@ function getPiActorsRuntimeStatus(): Record<string, unknown> {
 }
 
 function compactPiActorsRuntimeStatus(status: Record<string, unknown>): string {
-  return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
+  return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} automatic_review=${String(status.automatic_recipe_review)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
 }
 
 function isStaleClaim(message: AsyncRuns.RunInboxMessage, now: number): boolean {
@@ -515,12 +528,29 @@ export function createInspectToolDefinition<TContext = unknown>(
           view !== "status" &&
           view !== "summary" &&
           view !== "doctor" &&
-          view !== "imports"
+          view !== "imports" &&
+          view !== "reviews"
         ) {
           throw new Error(
-            "inspect recipes supports view=status, view=summary, view=doctor, or view=imports.",
+            "inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.",
           );
         }
+        if (view === "reviews") {
+          const diagnostics = ReviewDiagnostics.readAutomaticReviewDiagnostics({
+            recipeRoot: deps.recipeRoot ?? Paths.getRecipeRoot(),
+          });
+          return {
+            content: [{
+              type: "text" as const,
+              text: maybeJsonText(
+                diagnostics,
+                input.verbose === true,
+                compactAutomaticReviewDiagnostics(diagnostics),
+              ),
+            }],
+            details: diagnostics,
+          };
+        }
         const discovered = RecipesDiscovery.discoverRecipeSources([
           {
             root: deps.recipeRoot ?? Paths.getRecipeRoot(),

package/lib/tools-local.ts

@@ -162,8 +162,14 @@ export function createRuntimeToolDefinition(
       ctx: RuntimeToolContext,
     ) {
       try {
-        if (cfg.sourcePath)
-          RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
+        if (
+          cfg.sourcePath &&
+          !RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool")
+        ) {
+          throw new Error(
+            `Recipe launch rejected because its source changed during activation: ${cfg.sourcePath}. Reload recipe tools and retry.`,
+          );
+        }
         if (isAsyncRecipe) {
           const input = params as Record<string, unknown>;
           const { run_id, ...values } = input;

package/lib/tools-message.ts

@@ -290,6 +290,10 @@ function compactActorMessageResult(
 
 export interface ActorMessageToolDeps<TContext = unknown> {
   getTool?: (name: string) => any | undefined;
+  handleRuntimeMessage?: (
+    type: string,
+    body: unknown,
+  ) => Record<string, unknown>;
 }
 
 export function createActorMessageToolDefinition<TContext = unknown>(
@@ -363,7 +367,14 @@ export function createActorMessageToolDefinition<TContext = unknown>(
               ]
             : [];
         if (message.type === "control.kill") {
-          result = AsyncRuns.killRun(address.value);
+          result = typeof status.run_instance_id === "string"
+            ? AsyncRuns.killRun(address.value, {
+                ...(typeof status.ownerId === "string"
+                  ? { ownerId: status.ownerId }
+                  : {}),
+                runInstanceId: status.run_instance_id,
+              })
+            : { killed: false, reason: "run generation unavailable" };
         } else if (message.type === "control.archive") {
           result = AsyncRuns.archiveRun(address.value);
         } else if (message.type === "control.prune") {
@@ -463,36 +474,40 @@ export function createActorMessageToolDefinition<TContext = unknown>(
             : {}),
         };
       } else if (address.kind === "tool" && address.value) {
-        const tool = deps.getTool?.(address.value);
-        if (!tool || typeof tool.execute !== "function") {
-          throw new Error(
-            `tool actor not found or not executable: ${address.value}`,
-          );
-        }
-        const toolParams = messageBodyToToolParams(message);
-        let toolResult: unknown;
-        try {
-          toolResult = await tool.execute(
-            `message:${message.type}`,
-            toolParams,
-            _signal,
-            _onUpdate,
-            ctx,
-          );
-        } catch (error) {
-          throw formatToolActorFailure(
-            address.value,
-            message,
-            toolParams,
-            error,
-          );
+        if (address.value === "pi-actors" && deps.handleRuntimeMessage) {
+          result = deps.handleRuntimeMessage(message.type, message.body);
+        } else {
+          const tool = deps.getTool?.(address.value);
+          if (!tool || typeof tool.execute !== "function") {
+            throw new Error(
+              `tool actor not found or not executable: ${address.value}`,
+            );
+          }
+          const toolParams = messageBodyToToolParams(message);
+          let toolResult: unknown;
+          try {
+            toolResult = await tool.execute(
+              `message:${message.type}`,
+              toolParams,
+              _signal,
+              _onUpdate,
+              ctx,
+            );
+          } catch (error) {
+            throw formatToolActorFailure(
+              address.value,
+              message,
+              toolParams,
+              error,
+            );
+          }
+          result = {
+            invoked: true,
+            sent: true,
+            tool: address.value,
+            tool_result: toolResult,
+          };
         }
-        result = {
-          invoked: true,
-          sent: true,
-          tool: address.value,
-          tool_result: toolResult,
-        };
       } else if (address.kind === "coordinator" || address.kind === "session") {
         if (!message.from) {
           throw new Error(`message to ${address.kind} requires from=run:<id>.`);

package/lib/tools-spawn.ts

@@ -8,10 +8,12 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
+import { withFileMutationLock } from "./file-state.ts";
 import * as Messages from "./messages.ts";
 import * as ModelContext from "./model-context.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as RecipesUsage from "./recipes-usage.ts";
 import * as Rooms from "./rooms.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsResponse from "./tools-response.ts";
@@ -90,7 +92,12 @@ function writeSpawnDraftRecipe(
     ...(defaults ? { defaults } : {}),
     template: input.template,
   };
-  writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
+  withFileMutationLock(root, () =>
+    withFileMutationLock(path, () =>
+      writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" }),
+    ),
+  );
+  RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
   return path;
 }
 

package/lib/tools.ts

@@ -25,6 +25,10 @@ export interface CoreActorToolDefinitionDeps<
   configPath: string;
   getActiveTools: () => string[];
   getRuntimeTool: (name: string) => unknown;
+  handleRuntimeMessage?: (
+    type: string,
+    body: unknown,
+  ) => Record<string, unknown>;
   registryRuntime: Pick<
     RegisterToolRuntimeDeps<TContext>,
     "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"
@@ -71,6 +75,7 @@ export function createCoreActorToolDefinitions<
     ToolsSpawn.createSpawnToolDefinition<TContext>(),
     ToolsMessage.createActorMessageToolDefinition<TContext>({
       getTool: (name) => deps.getRuntimeTool(name),
+      handleRuntimeMessage: deps.handleRuntimeMessage,
     }),
     ToolsInspect.createInspectToolDefinition<TContext>({
       getTool: (name) => deps.getRuntimeTool(name),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -30,7 +30,8 @@
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "pack:dry": "npm pack --dry-run",
     "recipes:qa": "node scripts/validate-recipe.mjs recipes --all --qa --summary",
-    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run pack:dry",
+    "release:validate": "npm run validate && node scripts/release-gates.mjs",
+    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run conformance && npm audit --audit-level=high && npm run pack:dry",
     "build": "node scripts/build-dist.mjs",
     "prepack": "npm run build"
   },

package/recipes/draft-review.json

@@ -0,0 +1,24 @@
+{
+  "async": true,
+  "args": [
+    "input_path:path",
+    "model:string",
+    "thinking:string"
+  ],
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  },
+  "description": "Read-only background reviewer for one immutable automatic draft-memory batch.",
+  "mailbox": {
+    "accepts": [
+      "control.kill"
+    ],
+    "emits": [
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": "pi -p --model {model} --thinking {thinking} --no-tools @{input_path} Review the attached immutable pi-actors draft batch. Evaluate every draft independently using launch history, universality, flexibility, parameterization, duplication, safety, and likely future usefulness. Treat draft and sha256 fields as batch-local opaque occurrence/content-group identifiers and return them verbatim. Choose exactly one promote or discard decision per draft; there is no selection quota. Promotion requires a unique absent snake_case target and targetSha256 null. Never return recipe content: the executor derives the exact immutable captured source. Invalid or secret-touching drafts must be discarded. Include assessment with launches, universality, flexibility, futureUsefulness, and safety. Do not mutate, move, register, or delete recipes. End stdout with DRAFT_REVIEW_RESULT on its own line followed by exactly one JSON object with batchId, createdAt, and decisions."
+}

package/recipes/tool-review.json

@@ -0,0 +1,24 @@
+{
+  "async": true,
+  "args": [
+    "input_path:path",
+    "model:string",
+    "thinking:string"
+  ],
+  "defaults": {
+    "model": "{current_model}",
+    "thinking": "{current_thinking}"
+  },
+  "description": "Read-only background reviewer for one immutable 36-tool evolution portfolio.",
+  "mailbox": {
+    "accepts": [
+      "control.kill"
+    ],
+    "emits": [
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": "pi -p --model {model} --thinking {thinking} --no-tools @{input_path} Review the attached immutable pi-actors active-tool portfolio. Evaluate all 36 tools independently using lifetime and revision usage, adaptability, redundancy, safety, contract quality, and likely future usefulness. Treat source/name and sha256 fields as batch-local opaque occurrence/content-group identifiers, return them verbatim, and infer exact duplication only from a shared content group. Choose exactly one keep, evolve, demote, or merge decision per tool; there is no action quota. evolve may only rename one unchanged captured recipe, demote moves the unchanged recipe to draft memory, and merge may only deduplicate at least two canonically identical captured recipes. Never return recipe or outputs fields; replace and split require explicit operator-authored mutation and are unavailable to automatic review. Do not mutate, register, move, or delete recipes. End stdout with TOOL_REVIEW_RESULT on its own line followed by exactly one JSON object with reviewId, createdAt, and decisions."
+}