@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/registry.js

@@ -0,0 +1,504 @@
+/**
+ * Registry mutation use-cases
+ * Zones: registry mutations, persistence, runtime activation
+ * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import * as CommandTemplates from "./command-templates.js";
+import * as Config from "./config.js";
+import * as ExecutionOutput from "./execution-output.js";
+import { withFileMutationLock, writeJsonAtomic, writeTextAtomic, } from "./file-state.js";
+import * as Identity from "./identity.js";
+import * as Paths from "./paths.js";
+import * as RecipesContext from "./recipes-context.js";
+import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesReferences from "./recipes-references.js";
+import * as Schema from "./schema.js";
+function textContent(text) {
+    return { type: "text", text };
+}
+function listTools(deps) {
+    const names = [...deps.getTools().keys()].sort();
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(names.length > 0
+                ? `Registered tools:\n${names.map((name) => `- ${name}`).join("\n")}`
+                : "No registered tools.")),
+        ],
+        details: { tool: "register_tool" },
+    };
+}
+function getRecipeRoot(deps) {
+    return deps.recipeRoot ?? Paths.getRecipeRoot(dirname(deps.configPath));
+}
+function getToolRecipePath(deps, name) {
+    return join(getRecipeRoot(deps), `${name}.json`);
+}
+function activationBoundary(activation) {
+    if (activation?.callable_now)
+        return "current_session";
+    if (!activation)
+        return "session_activation_unverified";
+    if (!activation.host_registered)
+        return "host_registration";
+    if (!activation.active_tool)
+        return "active_tool_set";
+    return "callability_verification";
+}
+function recipeDoctorAction(source) {
+    return /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(source)
+        ? `inspect target=recipes view=doctor identity=${source}`
+        : "inspect target=recipes view=doctor";
+}
+function registrationNextActions(tool, source, callableNow) {
+    if (callableNow) {
+        return [
+            `call tool ${tool}`,
+            `inspect target=tool:${tool} view=status`,
+        ];
+    }
+    return [
+        `inspect target=tool:${tool} view=status`,
+        ...(source === "template" || source === "draft"
+            ? []
+            : [recipeDoctorAction(source)]),
+    ];
+}
+function activeSkillSummary(resolutionContext) {
+    const names = Object.keys(RecipesReferences.getActiveSkillRecipeNamespaces(resolutionContext.activeSkills))
+        .sort()
+        .slice(0, 20);
+    return names.length > 0 ? names.join(", ") : "<none>";
+}
+function assertDraftPath(deps, draft) {
+    const draftRoot = resolve(getRecipeRoot(deps), "drafts");
+    const path = resolve(draft);
+    const relation = relative(draftRoot, path);
+    if (relation === "" ||
+        relation.startsWith("..") ||
+        resolve(relation) === relation) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft must be under ${draftRoot}. Use inspect target=recipes view=summary to list drafts.`));
+    }
+    if (!existsSync(path)) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft not found: ${path}`));
+    }
+    return path;
+}
+function promoteDraftRecipe(name, input, ctx, deps) {
+    const draftPath = assertDraftPath(deps, String(input.draft ?? ""));
+    const targetPath = getToolRecipePath(deps, name);
+    const tools = deps.getTools();
+    const existing = tools.get(name);
+    const blocker = deps.getToolNameBlocker(name);
+    if (blocker)
+        throw new Error(ExecutionOutput.formatToolText(blocker));
+    if ((existing || existsSync(targetPath)) && !input.update) {
+        throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+    }
+    const raw = RecipesReferences.readRawRecipeConfig(draftPath);
+    if (!raw) {
+        const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(draftPath);
+        throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid${reason ? `: ${reason}` : "."}`));
+    }
+    const authoredRecipe = buildAuthoredRecipe({
+        ...input,
+        description: input.description ??
+            (typeof raw.description === "string" ? raw.description : undefined),
+    }, existing, raw);
+    const resolutionContext = getRegistrationResolutionContext(ctx, deps);
+    const candidate = RecipesDiscovery.admitUserRecipe(targetPath, resolutionContext, authoredRecipe);
+    if (!candidate.validated || !candidate.tool) {
+        throw new Error(ExecutionOutput.formatToolText(`Draft recipe is invalid: ${candidate.diagnostics.join("; ")}`));
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeJsonAtomic(targetPath, authoredRecipe);
+    const promoted = RecipesDiscovery.admitUserRecipe(targetPath, resolutionContext).tool;
+    tools.set(name, promoted);
+    const activation = deps.registerRuntimeTool(promoted) ?? undefined;
+    const argSummary = RecipesDiscovery.summarizeRegisteredToolArgs(promoted);
+    const callableNow = activation?.callable_now ?? false;
+    const nextActions = registrationNextActions(name, "draft", callableNow);
+    deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" from draft; callable_now=${callableNow}; next=${nextActions[0]}.`)),
+        ],
+        details: {
+            active_tool: activation?.active_tool ?? false,
+            activation: activation?.activation ?? "unverified",
+            activation_boundary: activationBoundary(activation),
+            args: promoted.args,
+            callable_now: callableNow,
+            defaults: promoted.defaults,
+            host_registered: activation?.host_registered ?? false,
+            next_actions: nextActions,
+            optional_args: argSummary.optional,
+            persisted: true,
+            promoted: true,
+            registry_active: tools.get(name) === promoted,
+            required_args: argSummary.required,
+            resolved: true,
+            source: "draft",
+            tool: name,
+            validated: true,
+        },
+    };
+}
+function persistToolRecipe(deps, name, recipe) {
+    const path = getToolRecipePath(deps, name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonAtomic(path, recipe);
+    return path;
+}
+function deleteTool(name, ctx, deps) {
+    const tools = deps.getTools();
+    if (!tools.has(name)) {
+        return {
+            content: [
+                textContent(ExecutionOutput.formatToolText(`Tool "${name}" not found.`)),
+            ],
+            details: { tool: name },
+        };
+    }
+    const recipePath = getToolRecipePath(deps, name);
+    if (existsSync(recipePath))
+        unlinkSync(recipePath);
+    tools.delete(name);
+    deps.setActiveTools(deps.getActiveTools().filter((toolName) => toolName !== name));
+    deps.notify(ctx, `Deleted tool: ${name}`, "info");
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(`Deleted tool "${name}". Reload to remove it from the complete registry.`)),
+        ],
+        details: { tool: name },
+    };
+}
+function readAuthoritativeStoredTool(deps, name) {
+    const path = getToolRecipePath(deps, name);
+    if (!existsSync(path))
+        return { exists: false };
+    try {
+        const bytes = readFileSync(path, "utf8");
+        const recipe = JSON.parse(bytes);
+        const normalized = Config.normalizeStoredTool(name, recipe, deps.reservedToolNames);
+        if (!normalized.cfg)
+            return { bytes, exists: true, recipe };
+        return {
+            bytes,
+            exists: true,
+            recipe,
+            tool: { ...normalized.cfg, sourcePath: path },
+        };
+    }
+    catch {
+        return { exists: true };
+    }
+}
+function looksLikeRecipeReference(value) {
+    const trimmed = value.trim();
+    return (trimmed.endsWith(".json") ||
+        trimmed.endsWith(".md") ||
+        /^[^/:\\]+\/[^/:\\]+$/.test(trimmed));
+}
+function assertTemplateIsNotNestedRecipe(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const record = value;
+    if (typeof record.template === "string" &&
+        looksLikeRecipeReference(record.template) &&
+        (Object.keys(record).length === 1 ||
+            ["artifacts", "async", "control", "description", "imports", "values"].some((key) => Object.hasOwn(record, key)))) {
+        throw new Error(ExecutionOutput.formatToolText("Nested Recipe-shaped templates are not a register_tool source mode. Next: retry with from=<skill>/<recipe> and defaults={...}."));
+    }
+}
+function getInputTemplate(value) {
+    assertTemplateIsNotNestedRecipe(value);
+    if (typeof value === "string")
+        return value.trim();
+    if (value === null || value === undefined)
+        return value;
+    if (Array.isArray(value)) {
+        const steps = CommandTemplates.expandCommandTemplateConfigs({
+            template: value,
+        });
+        if (steps.length === 0)
+            throw new Error(ExecutionOutput.formatToolText("Tool template sequence is empty."));
+        return value;
+    }
+    if (value && typeof value === "object") {
+        CommandTemplates.expandCommandTemplateConfigs(value);
+        return value;
+    }
+    throw new Error(ExecutionOutput.formatToolText("Tool template must be a string, object, or sequence."));
+}
+function getRegistrationResolutionContext(ctx, deps) {
+    const runtimeContext = deps.getRecipeResolutionContext?.();
+    if (runtimeContext)
+        return runtimeContext;
+    if (ctx && typeof ctx === "object" && "recipeResolutionContext" in ctx) {
+        const resolutionContext = ctx.recipeResolutionContext;
+        if (resolutionContext)
+            return resolutionContext;
+    }
+    return RecipesContext.createEmptyRecipeResolutionContext("offline-register-tool", getRecipeRoot(deps));
+}
+function normalizeDefaults(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(ExecutionOutput.formatToolText("Tool defaults must be an object."));
+    }
+    return { ...value };
+}
+function normalizeFromReference(value, resolutionContext) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(ExecutionOutput.formatToolText("Tool from must be a non-empty Recipe reference. Next: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path."));
+    }
+    if (trimmed.startsWith("std:")) {
+        throw new Error(ExecutionOutput.formatToolText("std: Recipe references were removed; use <skill>/<recipe> or an explicit .json/.md file path."));
+    }
+    if (trimmed.startsWith("skill:")) {
+        throw new Error(ExecutionOutput.formatToolText(`skill: Recipe references were removed; use ${trimmed.slice("skill:".length)} without a prefix.`));
+    }
+    if (trimmed.endsWith(".json") || trimmed.endsWith(".md")) {
+        return resolve(resolutionContext.cwd, trimmed);
+    }
+    if (!looksLikeRecipeReference(trimmed)) {
+        throw new Error(ExecutionOutput.formatToolText("Tool from must use <skill>/<recipe> or an explicit .json/.md file path."));
+    }
+    return trimmed;
+}
+function buildAuthoredRecipe(input, existing, existingRecipe) {
+    const explicitArgs = input.args === undefined
+        ? undefined
+        : Schema.parseToolArgDeclarations(input.args);
+    if (explicitArgs?.error)
+        throw new Error(ExecutionOutput.formatToolText(explicitArgs.error));
+    const from = typeof input.from === "string" ? input.from.trim() : "";
+    const description = (input.description ?? existing?.description ?? "").trim();
+    if (!description && !from) {
+        throw new Error(ExecutionOutput.formatToolText("Tool description is required for command-template registration."));
+    }
+    const inputDefaults = normalizeDefaults(input.defaults);
+    if (from) {
+        const runtimeOwnedDefault = Object.keys(inputDefaults ?? {}).find((key) => RecipesReferences.isRuntimeOwnedRecipeInput(key));
+        if (runtimeOwnedDefault) {
+            throw new Error(ExecutionOutput.formatToolText(`Tool defaults cannot set runtime-owned input: ${runtimeOwnedDefault}. Next: remove that default and retry register_tool; the runtime supplies it.`));
+        }
+        const authored = {
+            ...(description ? { description } : {}),
+            template: from,
+        };
+        const retainedDefaults = inputDefaults ??
+            (existingRecipe?.defaults && typeof existingRecipe.defaults === "object"
+                ? existingRecipe.defaults
+                : undefined);
+        if (retainedDefaults && Object.keys(retainedDefaults).length > 0)
+            authored.defaults = retainedDefaults;
+        return authored;
+    }
+    const template = getInputTemplate(input.template);
+    if (template === null) {
+        throw new Error(ExecutionOutput.formatToolText("Tool template cannot be null here."));
+    }
+    const finalTemplate = template === undefined || template === ""
+        ? existingRecipe?.template ?? existing?.template
+        : template;
+    if (!finalTemplate) {
+        throw new Error(ExecutionOutput.formatToolText("Tool template is required."));
+    }
+    const authored = {
+        ...(existingRecipe ?? {}),
+        description,
+        template: finalTemplate,
+    };
+    if (typeof input.async === "boolean")
+        authored.async = input.async;
+    if (explicitArgs) {
+        authored.args = explicitArgs.declarations;
+        const defaults = { ...explicitArgs.defaults, ...(inputDefaults ?? {}) };
+        if (Object.keys(defaults).length > 0)
+            authored.defaults = defaults;
+        else
+            delete authored.defaults;
+    }
+    else if (inputDefaults !== undefined) {
+        if (Object.keys(inputDefaults).length > 0)
+            authored.defaults = inputDefaults;
+        else
+            delete authored.defaults;
+    }
+    return authored;
+}
+function assertRegisterToolInputModes(input) {
+    const record = input;
+    if (Object.hasOwn(record, "values")) {
+        throw new Error(ExecutionOutput.formatToolText("register_tool values was removed. Next: retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition."));
+    }
+    const fromProvided = Object.hasOwn(record, "from");
+    if (fromProvided &&
+        (typeof input.from !== "string" || input.from.trim().length === 0)) {
+        throw new Error(ExecutionOutput.formatToolText("Tool from must be a non-empty Recipe reference. Next: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path."));
+    }
+    const draftProvided = typeof input.draft === "string" && input.draft.trim().length > 0;
+    const templateProvided = Object.hasOwn(record, "template");
+    const modeCount = Number(fromProvided) + Number(draftProvided) + Number(templateProvided);
+    if (modeCount > 1) {
+        throw new Error(ExecutionOutput.formatToolText("Use exactly one register_tool source mode: from, template, or draft. Next: remove the extra source fields and retry register_tool."));
+    }
+    if (fromProvided &&
+        (Object.hasOwn(record, "args") || Object.hasOwn(record, "async"))) {
+        throw new Error(ExecutionOutput.formatToolText("register_tool from inherits args and async behavior. Next: retry register_tool with from and optional defaults only; omit args and async."));
+    }
+}
+function executeRegisterToolUnlocked(params, ctx, deps) {
+    const rawInput = params && typeof params === "object"
+        ? params
+        : {};
+    assertRegisterToolInputModes(rawInput);
+    let input = rawInput;
+    if (!input.name)
+        return listTools(deps);
+    const name = Identity.normalizeToolName(input.name);
+    if (!name)
+        throw new Error(ExecutionOutput.formatToolText("Invalid tool name."));
+    if (deps.reservedToolNames.has(name)) {
+        throw new Error(ExecutionOutput.formatToolText(`Reserved tool name: ${name}`));
+    }
+    if (typeof input.draft === "string" && input.draft.trim()) {
+        return promoteDraftRecipe(name, input, ctx, deps);
+    }
+    const resolutionContext = getRegistrationResolutionContext(ctx, deps);
+    const requestedSource = typeof rawInput.from === "string" ? rawInput.from.trim() : undefined;
+    if (typeof input.from === "string") {
+        try {
+            input = {
+                ...input,
+                from: normalizeFromReference(input.from, resolutionContext),
+            };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message.trim() : String(error);
+            const diagnosticSource = requestedSource?.startsWith("skill:")
+                ? requestedSource.slice("skill:".length)
+                : requestedSource ?? "";
+            throw new Error(ExecutionOutput.formatToolText(`Recipe source "${requestedSource}" is invalid: ${reason}. Active Skills: ${activeSkillSummary(resolutionContext)}. Next: ${recipeDoctorAction(diagnosticSource)}`));
+        }
+    }
+    const templateProvided = Object.hasOwn(input, "template");
+    const template = getInputTemplate(input.template);
+    if (templateProvided && (template === null || template === ""))
+        return deleteTool(name, ctx, deps);
+    const tools = deps.getTools();
+    const authoritative = readAuthoritativeStoredTool(deps, name);
+    const existing = authoritative.tool ?? tools.get(name);
+    const blocker = deps.getToolNameBlocker(name);
+    if (blocker)
+        throw new Error(ExecutionOutput.formatToolText(blocker));
+    if ((authoritative.exists || existing) && !input.update) {
+        throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+    }
+    if (template === undefined && !input.from && !existing) {
+        throw new Error(ExecutionOutput.formatToolText("New registration requires exactly one source mode: from, template, or draft. Next: retry register_tool with one source field."));
+    }
+    const recipePath = getToolRecipePath(deps, name);
+    const authoredRecipe = buildAuthoredRecipe(input, existing, authoritative.recipe);
+    const candidate = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext, authoredRecipe);
+    if (!candidate.validated || !candidate.tool) {
+        const sourceDiagnostic = requestedSource
+            ? `Recipe source "${requestedSource}" validation failed: ${candidate.diagnostics.join("; ")}. Active Skills: ${activeSkillSummary(resolutionContext)}. Next: ${recipeDoctorAction(requestedSource)}`
+            : `Tool recipe validation failed: ${candidate.diagnostics.join("; ")}`;
+        throw new Error(ExecutionOutput.formatToolText(sourceDiagnostic));
+    }
+    const activeBefore = deps.getActiveTools();
+    let persisted = false;
+    let activation;
+    let cfg;
+    let transactionStage = "persist";
+    try {
+        persistToolRecipe(deps, name, authoredRecipe);
+        persisted = true;
+        transactionStage = "persisted_admission";
+        const admitted = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext);
+        if (!admitted.validated || !admitted.tool) {
+            throw new Error(`Persisted tool recipe admission failed: ${admitted.diagnostics.join("; ")}`);
+        }
+        cfg = admitted.tool;
+        tools.set(name, cfg);
+        transactionStage = "runtime_activation";
+        activation = deps.registerRuntimeTool(cfg) ?? undefined;
+        if (activation &&
+            (!activation.host_registered ||
+                !activation.active_tool ||
+                !activation.callable_now)) {
+            throw new Error(`Tool "${name}" activation failed at ${activationBoundary(activation)}; host_registered=${activation.host_registered}, active_tool=${activation.active_tool}, callable_now=${activation.callable_now}. Registration was rolled back. Next: inspect target=runtime view=status; do not use spawn as proof of tool invocation.`);
+        }
+    }
+    catch (error) {
+        if (persisted) {
+            if (authoritative.bytes !== undefined)
+                writeTextAtomic(recipePath, authoritative.bytes);
+            else if (existsSync(recipePath))
+                unlinkSync(recipePath);
+        }
+        if (existing) {
+            tools.set(name, existing);
+            deps.registerRuntimeTool(existing);
+        }
+        else {
+            tools.delete(name);
+        }
+        deps.setActiveTools(activeBefore);
+        throw new Error(ExecutionOutput.formatToolText(`Tool registration transaction failed at ${transactionStage} (${resolutionContext.generation}; active Skills: ${activeSkillSummary(resolutionContext)}): ${error instanceof Error ? error.message : String(error)}`));
+    }
+    deps.notify(ctx, `Tool activated: ${name}`, "info");
+    const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.recipe?.template === "object" && !Array.isArray(cfg.recipe.template)
+        ? cfg.recipe.template
+        : { template: cfg.recipe?.template ?? cfg.template });
+    const warningText = templateWarnings.length > 0
+        ? `\nWarnings:\n${templateWarnings.map((warning) => `- ${warning}`).join("\n")}`
+        : "";
+    const callableNow = activation?.callable_now ?? false;
+    const source = requestedSource ?? "template";
+    const argSummary = RecipesDiscovery.summarizeRegisteredToolArgs(cfg);
+    const nextActions = registrationNextActions(name, source, callableNow);
+    const outcomeText = callableNow
+        ? `${existing ? "Updated" : "Registered"} tool "${name}" from ${source}; callable_now=true`
+        : `Persisted tool "${name}" from ${source}; callable_now=false; activation_boundary=${activationBoundary(activation)}`;
+    return {
+        content: [
+            textContent(ExecutionOutput.formatToolText(`${outcomeText}; required=${Schema.formatToolArgs(argSummary.required)}; optional=${Schema.formatToolArgs(argSummary.optional)}; next=${nextActions[0]}.${warningText}`)),
+        ],
+        details: {
+            active_tool: activation?.active_tool ?? false,
+            activation: activation?.activation ?? "unverified",
+            activation_boundary: activationBoundary(activation),
+            args: cfg.args,
+            callable_now: callableNow,
+            defaults: cfg.defaults,
+            host_registered: activation?.host_registered ?? false,
+            next_actions: nextActions,
+            optional_args: argSummary.optional,
+            persisted: true,
+            registry_active: tools.get(name) === cfg,
+            required_args: argSummary.required,
+            resolved: true,
+            source,
+            ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
+            ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
+            tool: name,
+            validated: true,
+        },
+    };
+}
+export async function executeRegisterTool(params, ctx, deps) {
+    const input = params;
+    if (!input.name)
+        return executeRegisterToolUnlocked(params, ctx, deps);
+    const name = Identity.normalizeToolName(input.name);
+    if (!name)
+        return executeRegisterToolUnlocked(params, ctx, deps);
+    return withFileMutationLock(getToolRecipePath(deps, name), () => executeRegisterToolUnlocked(params, ctx, deps));
+}

package/node_modules/@llblab/pi-actors/dist/lib/review-control.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Automatic recipe-review operator control.
+ * Owns: explicit retry/reset transitions over durable draft/tool admission state.
+ */
+export type AutomaticReviewScope = "draft" | "tool";
+export type AutomaticReviewControlAction = "review.reset" | "review.retry";
+export interface AutomaticReviewControlOptions {
+    draftStatePath?: string;
+    scheduleDraft?(): void;
+    scheduleTool?(): void;
+    toolStatePath?: string;
+}
+export declare function controlAutomaticReview(action: AutomaticReviewControlAction, scope: AutomaticReviewScope, options?: AutomaticReviewControlOptions): Record<string, unknown>;
+export declare function parseAutomaticReviewScope(input: unknown): AutomaticReviewScope;

package/node_modules/@llblab/pi-actors/dist/lib/review-control.js

@@ -0,0 +1,110 @@
+/**
+ * Automatic recipe-review operator control.
+ * Owns: explicit retry/reset transitions over durable draft/tool admission state.
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.js";
+import * as Paths from "./paths.js";
+function readState(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statePath(scope, options) {
+    return scope === "draft"
+        ? options.draftStatePath ?? Paths.getDraftSleepStatePath()
+        : options.toolStatePath ?? Paths.getToolReviewStatePath();
+}
+function schedule(scope, options) {
+    if (scope === "draft")
+        options.scheduleDraft?.();
+    else
+        options.scheduleTool?.();
+}
+export function controlAutomaticReview(action, scope, options = {}) {
+    const path = statePath(scope, options);
+    const result = withFileMutationLock(path, () => {
+        const state = readState(path);
+        if (!state) {
+            return { action, changed: false, phase: "idle", reason: "review_state_unavailable", scope };
+        }
+        const phase = String(state.phase ?? "unknown");
+        if (action === "review.reset") {
+            if (!["completed", "failed", "processing_failed"].includes(phase)) {
+                return { action, changed: false, phase, reason: "review_state_not_terminal", scope };
+            }
+            if (scope === "tool" &&
+                (state.approvedPath || state.transactionEvidencePath || state.lineageJournalPath)) {
+                return {
+                    action,
+                    changed: false,
+                    phase,
+                    reason: "review_recovery_evidence_requires_retry",
+                    scope,
+                };
+            }
+            rmSync(path, { force: true });
+            return { action, changed: true, phase: "idle", previous_phase: phase, scope };
+        }
+        if (!["failed", "processing_failed"].includes(phase)) {
+            return { action, changed: false, phase, reason: "review_state_not_retryable", scope };
+        }
+        const resumeDraftTransaction = scope === "draft" &&
+            phase === "processing_failed" &&
+            typeof state.inputPath === "string" &&
+            typeof state.runId === "string" &&
+            existsSync(join(dirname(state.inputPath), "journal.json"));
+        const nextPhase = resumeDraftTransaction
+            ? "launched"
+            : scope === "tool" && state.approvedPath
+                ? state.transactionEvidencePath
+                    ? "lineage_pending"
+                    : "approved"
+                : "captured";
+        const next = {
+            ...state,
+            attempts: 0,
+            lastError: undefined,
+            nextAction: undefined,
+            failedStage: undefined,
+            phase: nextPhase,
+            processingAttempts: 0,
+            runId: resumeDraftTransaction ? state.runId : undefined,
+            updatedAt: new Date().toISOString(),
+        };
+        writeJsonAtomic(path, next);
+        return {
+            action,
+            changed: true,
+            phase: nextPhase,
+            previous_phase: phase,
+            scope,
+        };
+    });
+    if (result.changed === true)
+        schedule(scope, options);
+    const nextActions = ["inspect target=recipes view=reviews"];
+    if (action === "review.retry" &&
+        scope === "tool" &&
+        (result.phase === "approved" || result.phase === "lineage_pending"))
+        nextActions.push("/reload");
+    return {
+        ...result,
+        next_actions: nextActions,
+    };
+}
+export function parseAutomaticReviewScope(input) {
+    const record = input && typeof input === "object" && !Array.isArray(input)
+        ? input
+        : {};
+    if (record.scope === "draft" || record.scope === "tool")
+        return record.scope;
+    throw new Error("review Control requires input.scope=draft or input.scope=tool.");
+}

package/node_modules/@llblab/pi-actors/dist/lib/review-diagnostics.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Automatic recipe-review diagnostics.
+ * Zones: bounded draft/tool cycle evidence, lineage summaries, revision snapshot inventory
+ * Owns read-only diagnostic projection; schedulers and transactions own mutation.
+ */
+export interface AutomaticReviewDiagnosticOptions {
+    draftStatePath?: string;
+    recipeRoot?: string;
+    toolStatePath?: string;
+}
+export declare function readAutomaticReviewDiagnostics(options?: AutomaticReviewDiagnosticOptions): Record<string, unknown>;