@llblab/pi-actors 0.19.11 → 0.20.1

package/dist/lib/config.js

@@ -0,0 +1,226 @@
+/**
+ * Persistent tool registry config helpers
+ * Zones: registry config, persistence, migration boundary
+ * 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 RecipeReferences from "./recipe-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?.state_dir)
+            entry.state_dir = cfg.recipe.state_dir;
+        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 (Object.hasOwn(record, "tool")) {
+        return {
+            changed: false,
+            warning: `Tool "${name}" cannot define tool; use template directly.`,
+        };
+    }
+    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 } : {}),
+            ...(typeof record.state_dir === "string" && record.state_dir.trim()
+                ? { state_dir: record.state_dir.trim() }
+                : {}),
+            template,
+            ...(record.values &&
+                typeof record.values === "object" &&
+                !Array.isArray(record.values)
+                ? { values: record.values }
+                : {}),
+        }
+        : undefined;
+    const isRecipe = RecipeReferences.isRecipeTool(template, recipe);
+    const recipeTemplate = RecipeReferences.getRecipeTemplate(template);
+    const argTemplate = recipeTemplate ?? template;
+    const description = typeof record.description === "string" && record.description.trim()
+        ? record.description.trim()
+        : isRecipe
+            ? `${recipe?.async === true || RecipeReferences.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);
+    const argTypes = { ...inferredArgTypes, ...declarations.argTypes };
+    const cfg = {
+        name,
+        description,
+        args: isRecipe && storedArgs !== undefined
+            ? Schema.getExplicitToolArgNames(storedArgs)
+            : RecipeReferences.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/dist/lib/execution.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Registered tool execution runtime
+ * Zones: tool execution, command templates, output formatting
+ * Owns command-template invocation execution and pi tool-result payload formatting
+ */
+import * as CommandTemplates from "./command-templates.ts";
+import type { RegisteredTool } from "./config.ts";
+export interface ToolExecOptions {
+    actorRecipeContext?: CommandTemplates.CommandTemplateActorRecipeContext;
+    cwd?: string;
+    signal?: AbortSignal;
+    stdin?: string;
+    timeout?: number;
+    retry?: number;
+}
+export interface ToolExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+export interface BranchReport {
+    code: number;
+    command: string;
+    killed: boolean;
+    label: string;
+    status: "done" | "failed" | "timeout";
+    stderr?: string;
+    stdoutBytes: number;
+}
+export interface SoftQuorumReport {
+    coverage: number;
+    degraded: boolean;
+    done: number;
+    expected: number;
+    failed: number;
+    usable: boolean;
+}
+export interface RegisteredToolExecutionResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: {
+        branches?: BranchReport[];
+        code: number;
+        command: string;
+        fullOutputPath?: string;
+        killed: boolean;
+        nonCriticalFailures?: Array<{
+            code: number;
+            command: string;
+            killed: boolean;
+        }>;
+        softQuorum?: SoftQuorumReport;
+        template: CommandTemplates.CommandTemplateValue;
+        templateWarnings?: string[];
+        tool: string;
+        truncated: boolean;
+    };
+}
+export type RegisteredToolExec = (command: string, args: string[], options?: ToolExecOptions) => Promise<ToolExecResult>;
+export declare function executeRegisteredTool(cfg: RegisteredTool, params: Record<string, unknown>, exec: RegisteredToolExec, cwd: string, signal?: AbortSignal): Promise<RegisteredToolExecutionResult>;