@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,34 @@
+/**
+ * Persistent tool registry config helpers
+ * Zones: registry config, persistence, normalization
+ * Owns registered-tool config loading, normalization, unsupported-shape rejection, and serialization
+ */
+import type { CommandTemplateValue } from "./command-templates.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import * as Schema from "./schema.ts";
+export interface RegisteredTool {
+    name: string;
+    description: string;
+    args: string[];
+    defaults: Record<string, string>;
+    argTypes?: Record<string, Schema.ToolArgType>;
+    recipe?: RecipesReferences.TemplateRecipeConfig;
+    template?: CommandTemplateValue;
+    storedArgs?: string[];
+    storedDefaults?: Record<string, string>;
+    sourcePath?: string;
+}
+export interface LoadConfigResult {
+    tools: Map<string, RegisteredTool>;
+    warnings: string[];
+    changed: boolean;
+}
+export declare function serializeTools(source: Map<string, RegisteredTool>): Record<string, unknown>;
+export declare function saveTools(path: string, source: Map<string, RegisteredTool>): string | undefined;
+export declare function getStoredEntries(raw: unknown): Array<[string | undefined, unknown]>;
+export declare function normalizeStoredTool(key: string | undefined, value: unknown, reservedToolNames: Set<string>): {
+    cfg?: RegisteredTool;
+    changed: boolean;
+    warning?: string;
+};
+export declare function loadToolConfig(path: string, reservedToolNames: Set<string>): LoadConfigResult;

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

@@ -0,0 +1,216 @@
+/**
+ * Persistent tool registry config helpers
+ * Zones: registry config, persistence, normalization
+ * Owns registered-tool config loading, normalization, unsupported-shape rejection, and serialization
+ */
+import { existsSync, readFileSync } from "node:fs";
+import * as CommandTemplates from "./command-templates.js";
+import { writeJsonAtomic } from "./file-state.js";
+import { normalizeToolName } from "./identity.js";
+import * as RecipesReferences from "./recipes-references.js";
+import * as Schema from "./schema.js";
+export function serializeTools(source) {
+    const entries = [...source.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const result = {};
+    for (const [name, cfg] of entries) {
+        const entry = {
+            description: cfg.description,
+        };
+        if (cfg.storedArgs && cfg.storedArgs.length > 0)
+            entry.args = cfg.storedArgs;
+        if (cfg.storedDefaults && Object.keys(cfg.storedDefaults).length > 0)
+            entry.defaults = cfg.storedDefaults;
+        if (cfg.recipe?.name)
+            entry.name = cfg.recipe.name;
+        if (cfg.recipe?.async !== undefined)
+            entry.async = cfg.recipe.async;
+        if (cfg.recipe?.values)
+            entry.values = cfg.recipe.values;
+        if (cfg.template)
+            entry.template = cfg.template;
+        result[name] = entry;
+    }
+    return result;
+}
+export function saveTools(path, source) {
+    try {
+        writeJsonAtomic(path, serializeTools(source));
+        return undefined;
+    }
+    catch (error) {
+        return getErrorMessage(error);
+    }
+}
+export function getStoredEntries(raw) {
+    if (Array.isArray(raw))
+        return raw.map((value) => [undefined, value]);
+    if (raw && typeof raw === "object") {
+        return Object.entries(raw);
+    }
+    return [];
+}
+function getStoredTemplate(value) {
+    if (typeof value === "string")
+        return value.trim() || undefined;
+    if (!Array.isArray(value))
+        return undefined;
+    const template = value;
+    return CommandTemplates.expandCommandTemplateConfigs({ template }).length > 0
+        ? template
+        : undefined;
+}
+function formatTemplateForDescription(template) {
+    return typeof template === "string" ? template : JSON.stringify(template);
+}
+export function normalizeStoredTool(key, value, reservedToolNames) {
+    if (!value || typeof value !== "object") {
+        return {
+            changed: true,
+            warning: `Invalid tool entry: ${key ?? "<array item>"}`,
+        };
+    }
+    const record = value;
+    const rawName = key ?? (typeof record.name === "string" ? record.name : "");
+    const name = normalizeToolName(rawName);
+    if (!name) {
+        return {
+            changed: true,
+            warning: `Invalid tool name: ${rawName || key || "<empty>"}`,
+        };
+    }
+    if (reservedToolNames.has(name)) {
+        return { changed: true, warning: `Reserved tool name skipped: ${name}` };
+    }
+    const template = getStoredTemplate(record.template);
+    if (!template && typeof record.script === "string") {
+        return {
+            changed: false,
+            warning: `Tool "${name}" uses unsupported script config. Use template because pi-actors cannot load script entries.`,
+        };
+    }
+    if (record.job !== undefined || record.recipe !== undefined) {
+        return {
+            changed: false,
+            warning: `Tool "${name}" uses unsupported job/recipe config. Use template with optional name and async fields.`,
+        };
+    }
+    const keyedRecipeName = key !== undefined && typeof record.name === "string" && record.name.trim()
+        ? record.name.trim()
+        : undefined;
+    if ((keyedRecipeName || typeof record.async === "boolean") && !template) {
+        return {
+            changed: false,
+            warning: `Tool "${name}" uses recipe config without template. Add template to make it a co-located template recipe.`,
+        };
+    }
+    if (!template) {
+        return { changed: true, warning: `Tool "${name}" has no template` };
+    }
+    const recipeName = keyedRecipeName ?? (typeof record.async === "boolean" ? name : undefined);
+    const recipe = recipeName
+        ? {
+            name: recipeName,
+            ...(typeof record.async === "boolean" ? { async: record.async } : {}),
+            template,
+            ...(record.values &&
+                typeof record.values === "object" &&
+                !Array.isArray(record.values)
+                ? { values: record.values }
+                : {}),
+        }
+        : undefined;
+    const isRecipe = RecipesReferences.isRecipeTool(template, recipe);
+    const recipeTemplate = RecipesReferences.getRecipeTemplate(template);
+    const argTemplate = recipeTemplate ?? template;
+    const description = typeof record.description === "string" && record.description.trim()
+        ? record.description.trim()
+        : isRecipe
+            ? `${recipe?.async === true || RecipesReferences.isAsyncRecipeReference(template) ? "Start async" : "Execute"} template recipe: ${recipe?.name ?? formatTemplateForDescription(template)}`
+            : `Execute command template: ${formatTemplateForDescription(template)}`;
+    const declarations = Schema.normalizeStoredToolArgDeclarations(record.args, record.defaults);
+    const storedArgs = declarations.provided
+        ? declarations.declarations
+        : undefined;
+    const storedDefaults = declarations.provided && Object.keys(declarations.defaults).length > 0
+        ? declarations.defaults
+        : undefined;
+    const argTemplateConfig = typeof argTemplate === "object" && !Array.isArray(argTemplate)
+        ? {
+            ...argTemplate,
+            ...(storedArgs !== undefined ? { args: storedArgs } : {}),
+            defaults: {
+                ...(argTemplate.defaults ?? {}),
+                ...declarations.defaults,
+            },
+        }
+        : {
+            args: storedArgs,
+            defaults: declarations.defaults,
+            template: argTemplate,
+        };
+    const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+    Schema.assertCompatibleToolArgTypes(inferredArgTypes, declarations.argTypes);
+    const argTypes = { ...inferredArgTypes, ...declarations.argTypes };
+    const cfg = {
+        name,
+        description,
+        args: isRecipe && storedArgs !== undefined
+            ? Schema.getExplicitToolArgNames(storedArgs)
+            : RecipesReferences.isRecipeReference(template) && !recipeTemplate
+                ? Schema.getExplicitToolArgNames(storedArgs)
+                : Schema.getToolArgNames(argTemplateConfig),
+        defaults: declarations.defaults,
+        ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
+        ...(recipe ? { recipe } : {}),
+        template,
+        ...(storedArgs !== undefined ? { storedArgs } : {}),
+        ...(storedDefaults !== undefined ? { storedDefaults } : {}),
+    };
+    const changed = (key === undefined && record.name !== undefined) ||
+        record.label !== undefined ||
+        JSON.stringify(record.template) !== JSON.stringify(template) ||
+        description !== record.description ||
+        declarations.changed;
+    return { cfg, changed };
+}
+export function loadToolConfig(path, reservedToolNames) {
+    const warnings = [];
+    const tools = new Map();
+    let changed = false;
+    if (!existsSync(path))
+        return { tools, warnings, changed };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const entries = getStoredEntries(raw);
+        for (const [key, value] of entries) {
+            const result = normalizeStoredTool(key, value, reservedToolNames);
+            changed = changed || result.changed;
+            if (result.warning)
+                warnings.push(result.warning);
+            if (!result.cfg)
+                continue;
+            if (tools.has(result.cfg.name)) {
+                warnings.push(`Duplicate tool kept from last entry: ${result.cfg.name}`);
+            }
+            if (tools.has(result.cfg.name))
+                changed = true;
+            tools.set(result.cfg.name, result.cfg);
+        }
+        if (entries.length === 0 && raw && typeof raw !== "object") {
+            warnings.push(`Invalid ${path} format`);
+        }
+        if (entries.length === 0 && raw && typeof raw !== "object")
+            changed = true;
+        return { tools, warnings, changed };
+    }
+    catch (error) {
+        return {
+            tools,
+            warnings: [`Failed to load ${path}: ${getErrorMessage(error)}`],
+            changed: false,
+        };
+    }
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+export interface ProjectedRunControl {
+    action: string;
+    claimed_at?: string;
+    delivered_at?: string;
+    error?: string;
+    failed_at?: string;
+    handled_at?: string;
+    id: string;
+    input?: unknown;
+    queued_at: string;
+    run_instance_id: string;
+    status: RunControlStatus;
+}
+export declare function projectRunControl(control: RunControlRecord): ProjectedRunControl;

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

@@ -0,0 +1,66 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import * as Limits from "./limits.js";
+import * as SessionEvidence from "./session-evidence.js";
+const OPTIONAL_TIMESTAMP_FIELDS = [
+    "claimed_at",
+    "delivered_at",
+    "failed_at",
+    "handled_at",
+];
+function boundedRedactedString(value, maxChars) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+    return typeof redacted === "string"
+        ? redacted
+        : String(redacted).slice(0, maxChars);
+}
+function boundedRedactedValue(value) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let serialized;
+    try {
+        serialized = JSON.stringify(redacted);
+    }
+    catch {
+        return "[UNSERIALIZABLE]";
+    }
+    if (serialized === undefined)
+        return "[UNSERIALIZABLE]";
+    if (serialized.length <= Limits.INSPECTOR_BODY_PREVIEW_CHARS)
+        return redacted;
+    let preview = serialized.slice(0, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let bounded = { preview: `${preview}…`, truncated: true };
+    while (preview &&
+        JSON.stringify(bounded).length > Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
+        const excess = JSON.stringify(bounded).length - Limits.INSPECTOR_BODY_PREVIEW_CHARS;
+        preview = preview.slice(0, Math.max(0, preview.length - Math.max(1, excess)));
+        bounded = { preview: `${preview}…`, truncated: true };
+    }
+    return bounded;
+}
+export function projectRunControl(control) {
+    const timestamps = Object.fromEntries(OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+        const value = control[field];
+        return typeof value === "string"
+            ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)]]
+            : [];
+    }));
+    return {
+        action: boundedRedactedString(control.action, Limits.COMPACT_PREVIEW_CHARS),
+        ...timestamps,
+        ...(typeof control.error === "string"
+            ? {
+                error: boundedRedactedString(control.error, Limits.INSPECTOR_BODY_PREVIEW_CHARS),
+            }
+            : {}),
+        id: boundedRedactedString(control.id, Limits.COMPACT_PREVIEW_CHARS),
+        ...(control.input !== undefined
+            ? { input: boundedRedactedValue(control.input) }
+            : {}),
+        queued_at: boundedRedactedString(control.queued_at, Limits.COMPACT_PREVIEW_CHARS),
+        run_instance_id: boundedRedactedString(control.run_instance_id, Limits.COMPACT_PREVIEW_CHARS),
+        status: boundedRedactedString(control.status, Limits.COMPACT_PREVIEW_CHARS),
+    };
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Run Control request contract.
+ * Zones: public request validation, Run/runtime target normalization, input bounds
+ * Owns pure Control validation; journaling, delivery, and lifecycle mutation stay in adapters.
+ */
+export interface ControlRequest {
+    target: `run:${string}` | "runtime";
+    action: string;
+    input?: unknown;
+    verbose?: boolean;
+}
+export declare function isControlAction(value: string): boolean;
+export declare function normalizeControlAction(value: unknown): string;
+export declare function normalizeControlInput(input: unknown): unknown;
+export declare function normalizeControlRequest(input: unknown): ControlRequest;

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

@@ -0,0 +1,97 @@
+/**
+ * Run Control request contract.
+ * Zones: public request validation, Run/runtime target normalization, input bounds
+ * Owns pure Control validation; journaling, delivery, and lifecycle mutation stay in adapters.
+ */
+import * as Limits from "./limits.js";
+const RUN_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const ACTION_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+const CONTROL_FIELDS = new Set(["action", "input", "target", "verbose"]);
+const REMOVED_FIELDS = new Set([
+    "body",
+    "correlation_id",
+    "from",
+    "metadata",
+    "reply_to",
+    "summary",
+    "to",
+    "type",
+]);
+export function isControlAction(value) {
+    return ACTION_PATTERN.test(value);
+}
+export function normalizeControlAction(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("control.action is required");
+    }
+    const action = value.trim();
+    if (!isControlAction(action)) {
+        throw new Error(`invalid control action: ${action}`);
+    }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+        throw new Error(`control.action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters`);
+    }
+    return action;
+}
+export function normalizeControlInput(input) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(input);
+    }
+    catch {
+        throw new Error("control.input must be JSON-serializable");
+    }
+    if (serialized === undefined) {
+        throw new Error("control.input must be JSON-serializable");
+    }
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > Limits.CONTROL_INPUT_MAX_BYTES) {
+        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} serialized bytes`);
+    }
+    return JSON.parse(serialized);
+}
+function normalizeTarget(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("control.target is required");
+    }
+    const target = value.trim();
+    if (target === "runtime")
+        return target;
+    if (!target.startsWith("run:")) {
+        throw new Error(`unsupported control target: ${target}; use run:<id> or runtime`);
+    }
+    const run = target.slice(4);
+    if (!RUN_ID_PATTERN.test(run)) {
+        throw new Error(`invalid control Run target: ${target}`);
+    }
+    return `run:${run}`;
+}
+export function normalizeControlRequest(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("control request must be an object");
+    }
+    const record = input;
+    const fields = Object.keys(record);
+    const removed = fields.filter((field) => REMOVED_FIELDS.has(field));
+    if (removed.length > 0) {
+        throw new Error(`actor-message fields are removed: ${removed.sort().join(", ")}; use target, action, input, verbose`);
+    }
+    const unknown = fields.filter((field) => !CONTROL_FIELDS.has(field));
+    if (unknown.length > 0) {
+        throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
+    }
+    const target = normalizeTarget(record.target);
+    const action = normalizeControlAction(record.action);
+    if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
+        throw new Error("control.verbose must be a boolean");
+    }
+    const normalizedInput = record.input === undefined
+        ? undefined
+        : normalizeControlInput(record.input);
+    return {
+        target,
+        action,
+        ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
+        ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
+    };
+}

package/node_modules/@llblab/pi-actors/dist/lib/draft-consolidation-transaction.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic draft consolidation transaction and crash recovery.
+ * Owns: cycle claim, source/target compare-and-swap, complete recipe persistence, source quarantine, journal transitions, rollback, and runtime evidence.
+ */
+import type { DraftConsolidationPlan } from "./draft-consolidation.ts";
+import { type DraftConsolidationInventoryItem } from "./draft-consolidation.ts";
+export type DraftConsolidationTransactionPhase = "prepared" | "targets_validated" | "sources_quarantined" | "committed_evidence_pending" | "committed" | "rolled_back" | "rollback_required";
+interface TargetOperation {
+    backupPath?: string;
+    expectedSha256: string | null;
+    intendedSha256: string;
+    path: string;
+    recipe: Record<string, unknown>;
+    target: string;
+}
+interface SourceOperation {
+    path: string;
+    quarantinePath: string;
+    sha256: string;
+}
+interface ConsolidationRootIdentity {
+    dev: string;
+    ino: string;
+    path: string;
+    realpath: string;
+}
+interface ConsolidationRootIdentities {
+    cycleDir: ConsolidationRootIdentity;
+    draftRoot: ConsolidationRootIdentity;
+    recipeRoot: ConsolidationRootIdentity;
+}
+export interface DraftConsolidationJournal {
+    cycleId: string;
+    error?: string;
+    operationsSha256: string;
+    phase: DraftConsolidationTransactionPhase;
+    plan: DraftConsolidationPlan;
+    planSha256: string;
+    roots: ConsolidationRootIdentities;
+    sourceScope: "batch" | "complete";
+    sources: SourceOperation[];
+    targets: TargetOperation[];
+    updatedAt: string;
+}
+export type DraftConsolidationCheckpoint = "prepared" | "target_written" | "targets_validated" | "source_quarantined" | "sources_quarantined" | "committed_evidence_pending" | "evidence_written";
+export interface DraftConsolidationTransactionOptions {
+    checkpoint?(point: DraftConsolidationCheckpoint): void;
+    cycleDir: string;
+    draftRoot: string;
+    inventory: DraftConsolidationInventoryItem[];
+    onLockContention?(): void;
+    sourceScope?: "batch" | "complete";
+    recipeRoot: string;
+}
+export interface DraftConsolidationTransactionResult {
+    cycleId: string;
+    evidencePath: string;
+    phase: "committed" | "rolled_back";
+    plan: DraftConsolidationPlan;
+    sources: number;
+    targets: number;
+}
+export declare function applyDraftConsolidationPlan(plan: DraftConsolidationPlan, options: DraftConsolidationTransactionOptions): DraftConsolidationTransactionResult;
+export declare function recoverDraftConsolidationCycle(options: Pick<DraftConsolidationTransactionOptions, "cycleDir" | "draftRoot" | "recipeRoot">): DraftConsolidationTransactionResult;
+export {};