@llblab/pi-actors 0.19.11 → 0.20.1

package/dist/lib/registry.js

@@ -0,0 +1,222 @@
+/**
+ * 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, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import * as Identity from "./identity.js";
+import * as Output from "./output.js";
+import * as CommandTemplates from "./command-templates.js";
+import { writeJsonAtomic } from "./file-state.js";
+import * as Paths from "./paths.js";
+import * as RecipeReferences from "./recipe-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(Output.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 persistToolRecipe(deps, cfg) {
+    const path = getToolRecipePath(deps, cfg.name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonAtomic(path, {
+        description: cfg.description,
+        tool: true,
+        ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
+        ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
+        ...(cfg.storedArgs ? { args: cfg.storedArgs } : {}),
+        ...(cfg.storedDefaults ? { defaults: cfg.storedDefaults } : {}),
+        ...(cfg.recipe?.values ? { values: cfg.recipe.values } : {}),
+        template: cfg.template,
+    });
+    return path;
+}
+function deleteTool(name, ctx, deps) {
+    const tools = deps.getTools();
+    if (!tools.has(name)) {
+        return {
+            content: [
+                textContent(Output.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(Output.formatToolText(`Deleted tool "${name}". Reload to remove it from the complete registry.`)),
+        ],
+        details: { config: recipePath, tool: name },
+    };
+}
+function getInputTemplate(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(Output.formatToolText("Tool template sequence is empty."));
+        return value;
+    }
+    throw new Error(Output.formatToolText("Tool template must be a string or sequence."));
+}
+function buildConfig(name, input, existing) {
+    const explicitArgs = input.args === undefined
+        ? undefined
+        : Schema.parseToolArgDeclarations(input.args);
+    if (explicitArgs?.error)
+        throw new Error(Output.formatToolText(explicitArgs.error));
+    const description = (input.description ?? existing?.description ?? "").trim();
+    if (!description) {
+        throw new Error(Output.formatToolText("Tool description is required unless deleting."));
+    }
+    const template = getInputTemplate(input.template);
+    if (template === null) {
+        throw new Error(Output.formatToolText("Tool template cannot be null here."));
+    }
+    const finalTemplate = template === undefined || template === "" ? existing?.template : template;
+    if (!finalTemplate) {
+        throw new Error(Output.formatToolText("Tool template is required."));
+    }
+    const inputRecipe = typeof input.async === "boolean" ? name : undefined;
+    const recipe = inputRecipe
+        ? {
+            name: inputRecipe,
+            ...(typeof input.async === "boolean" ? { async: input.async } : {}),
+            ...(typeof input.state_dir === "string" && input.state_dir.trim()
+                ? { state_dir: input.state_dir.trim() }
+                : {}),
+            template: finalTemplate,
+            ...(input.values && typeof input.values === "object"
+                ? { values: input.values }
+                : {}),
+        }
+        : template === undefined
+            ? existing?.recipe
+            : undefined;
+    const defaults = explicitArgs?.defaults ?? existing?.storedDefaults ?? {};
+    const storedArgs = explicitArgs
+        ? explicitArgs.declarations
+        : existing?.storedArgs;
+    const storedDefaults = Object.keys(defaults).length > 0 ? defaults : undefined;
+    const recipeTemplate = RecipeReferences.getRecipeTemplate(finalTemplate);
+    const argTemplate = recipeTemplate ?? finalTemplate;
+    const argTemplateConfig = typeof argTemplate === "object" && !Array.isArray(argTemplate)
+        ? {
+            ...argTemplate,
+            ...(storedArgs !== undefined ? { args: storedArgs } : {}),
+            defaults: { ...(argTemplate.defaults ?? {}), ...defaults },
+        }
+        : {
+            args: storedArgs,
+            defaults,
+            template: argTemplate,
+        };
+    const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+    const argTypes = {
+        ...inferredArgTypes,
+        ...(existing?.argTypes ?? {}),
+        ...(explicitArgs?.argTypes ?? {}),
+    };
+    return {
+        name,
+        description,
+        template: finalTemplate,
+        ...(recipe ? { recipe } : {}),
+        args: RecipeReferences.isRecipeTool(finalTemplate, recipe) &&
+            storedArgs !== undefined
+            ? Schema.getExplicitToolArgNames(storedArgs)
+            : RecipeReferences.isRecipeReference(finalTemplate) && !recipeTemplate
+                ? Schema.getExplicitToolArgNames(storedArgs)
+                : Schema.getToolArgNames(argTemplateConfig),
+        defaults,
+        ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
+        ...(storedArgs !== undefined ? { storedArgs } : {}),
+        ...(storedDefaults !== undefined ? { storedDefaults } : {}),
+    };
+}
+export async function executeRegisterTool(params, ctx, deps) {
+    const input = params;
+    if (!input.name)
+        return listTools(deps);
+    const name = Identity.normalizeToolName(input.name);
+    if (!name)
+        throw new Error(Output.formatToolText("Invalid tool name."));
+    if (deps.reservedToolNames.has(name)) {
+        throw new Error(Output.formatToolText(`Reserved tool name: ${name}`));
+    }
+    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 existing = tools.get(name);
+    const conflict = deps.getExternalToolConflict(name);
+    if (conflict)
+        throw new Error(Output.formatToolText(conflict));
+    if (existing && !input.update) {
+        throw new Error(Output.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+    }
+    if (template === undefined && !existing) {
+        throw new Error(Output.formatToolText("Tool template is required for new registrations."));
+    }
+    const cfg = buildConfig(name, input, existing);
+    let recipePath;
+    try {
+        recipePath = persistToolRecipe(deps, cfg);
+    }
+    catch (error) {
+        throw new Error(Output.formatToolText(`Failed to persist tool recipe: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    cfg.sourcePath = recipePath;
+    tools.set(name, cfg);
+    deps.registerRuntimeTool(cfg);
+    deps.notify(ctx, `Tool persisted: ${name}`, "info");
+    const templateWarnings = CommandTemplates.getCommandTemplateWarnings(typeof cfg.template === "object" && !Array.isArray(cfg.template)
+        ? cfg.template
+        : { template: cfg.template });
+    const warningText = templateWarnings.length > 0
+        ? `\nWarnings:\n${templateWarnings.map((warning) => `- ${warning}`).join("\n")}`
+        : "";
+    return {
+        content: [
+            textContent(Output.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`)),
+        ],
+        details: {
+            args: cfg.args,
+            config: recipePath,
+            defaults: cfg.defaults,
+            ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
+            ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),
+            ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
+            ...(cfg.template ? { template: cfg.template } : {}),
+            ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
+            tool: name,
+        },
+    };
+}

package/dist/lib/runtime.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool registry runtime coordinator
+ * Zones: runtime coordination, registry loading, pi tools
+ * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
+ */
+import * as Config from "./config.ts";
+import type { RegisteredToolExec } from "./execution.ts";
+import * as Tools from "./tools.ts";
+export interface RuntimeContext {
+    hasUI: boolean;
+    ui: {
+        notify(message: string, type?: "info" | "warning" | "error"): void;
+    };
+}
+export interface ToolInfoLike {
+    name: string;
+}
+export interface ToolRegistryRuntimeDeps {
+    configPath: string;
+    exec: RegisteredToolExec;
+    packagedRecipeRoot?: string;
+    recipeRoot?: string;
+    getActiveTools?: () => string[];
+    getAllTools: () => ToolInfoLike[];
+    registerTool: (definition: ReturnType<typeof Tools.createRuntimeToolDefinition>) => void;
+    reservedToolNames: Set<string>;
+    setActiveTools?: (toolNames: string[]) => void;
+}
+export interface ToolRegistryRuntime {
+    getExternalToolConflict(name: string): string | undefined;
+    getTools(): Map<string, Config.RegisteredTool>;
+    loadTools(ctx: RuntimeContext): void;
+    notify(ctx: RuntimeContext, message: string, type: "info" | "warning" | "error"): void;
+    registerRuntimeTool(cfg: Config.RegisteredTool): void;
+}
+export declare function createAutoToolsRuntime(deps: ToolRegistryRuntimeDeps): ToolRegistryRuntime;

package/dist/lib/runtime.js

@@ -0,0 +1,126 @@
+/**
+ * Tool registry runtime coordinator
+ * Zones: runtime coordination, registry loading, pi tools
+ * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
+ */
+import * as Paths from "./paths.js";
+import * as RecipeDiscovery from "./recipe-discovery.js";
+import * as RecipeMigration from "./recipe-migration.js";
+import * as Tools from "./tools.js";
+export function createAutoToolsRuntime(deps) {
+    const tools = new Map();
+    const runtimeToolFingerprints = new Map();
+    const runtimeTools = new Set();
+    function notify(ctx, message, type) {
+        if (ctx.hasUI)
+            ctx.ui.notify(message, type);
+    }
+    function getExternalToolConflict(name) {
+        if (runtimeTools.has(name))
+            return undefined;
+        const existing = deps.getAllTools().find((tool) => tool.name === name);
+        return existing
+            ? `Tool "${name}" is already registered outside pi-actors.`
+            : undefined;
+    }
+    function getToolFingerprint(cfg) {
+        return JSON.stringify({
+            args: cfg.args,
+            argTypes: cfg.argTypes,
+            defaults: cfg.defaults,
+            description: cfg.description,
+            recipe: cfg.recipe,
+            template: cfg.template,
+        });
+    }
+    function deactivateMissingRuntimeTools(activeNames) {
+        const stale = [...runtimeTools].filter((name) => !activeNames.has(name));
+        if (stale.length === 0)
+            return;
+        for (const name of stale) {
+            runtimeTools.delete(name);
+            runtimeToolFingerprints.delete(name);
+        }
+        if (!deps.getActiveTools || !deps.setActiveTools)
+            return;
+        const staleSet = new Set(stale);
+        deps.setActiveTools(deps.getActiveTools().filter((name) => !staleSet.has(name)));
+    }
+    function registerRuntimeTool(cfg) {
+        const fingerprint = getToolFingerprint(cfg);
+        if (runtimeToolFingerprints.get(cfg.name) === fingerprint)
+            return;
+        deps.registerTool(Tools.createRuntimeToolDefinition(cfg, deps.exec));
+        runtimeTools.add(cfg.name);
+        runtimeToolFingerprints.set(cfg.name, fingerprint);
+    }
+    function formatRecipeToolWarnings(warnings) {
+        const shadowed = warnings.filter((warning) => warning.includes(" shadows "));
+        const skipped = warnings.filter((warning) => warning.includes(" could not be exposed as a tool:"));
+        const other = warnings.filter((warning) => !shadowed.includes(warning) && !skipped.includes(warning));
+        const lines = ["pi-actors recipe registry warning"];
+        if (shadowed.length > 0) {
+            lines.push("User recipes override packaged recipes:");
+            lines.push(...shadowed.map((warning) => `• ${warning}`));
+        }
+        if (skipped.length > 0) {
+            lines.push("Recipes skipped from tool exposure:");
+            lines.push(...skipped.map((warning) => `• ${warning}`));
+        }
+        if (other.length > 0) {
+            lines.push("Other registry diagnostics:");
+            lines.push(...other.map((warning) => `• ${warning}`));
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    function loadTools(ctx) {
+        const warnings = [];
+        const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+        const packagedRecipeRoot = deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot();
+        const migration = RecipeMigration.migrateLegacyToolRegistry({
+            configPath: deps.configPath,
+            recipeRoot,
+            reservedToolNames: deps.reservedToolNames,
+        });
+        warnings.push(...migration.warnings);
+        if (migration.conflicts.length > 0)
+            warnings.push(`Recipe migration conflicts: ${migration.conflicts.join(", ")}`);
+        if (migration.invalid.length > 0)
+            warnings.push(`Recipe migration invalid entries: ${migration.invalid.join(", ")}`);
+        const discovered = RecipeDiscovery.discoverRecipeSources([
+            { root: recipeRoot, defaultTool: true, mutableUsage: true },
+            { root: packagedRecipeRoot },
+        ]);
+        warnings.push(...discovered.diagnostics);
+        tools.clear();
+        for (const entry of discovered.active.values()) {
+            try {
+                const cfg = RecipeDiscovery.toRegisteredTool(entry);
+                if (cfg)
+                    tools.set(cfg.name, cfg);
+            }
+            catch (error) {
+                warnings.push(`Recipe ${entry.id} could not be exposed as a tool: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        deactivateMissingRuntimeTools(new Set(tools.keys()));
+        for (const cfg of tools.values()) {
+            const conflict = getExternalToolConflict(cfg.name);
+            if (conflict) {
+                warnings.push(conflict);
+                continue;
+            }
+            registerRuntimeTool(cfg);
+        }
+        if (warnings.length > 0) {
+            notify(ctx, formatRecipeToolWarnings(warnings), "warning");
+        }
+    }
+    return {
+        getExternalToolConflict,
+        getTools: () => tools,
+        loadTools,
+        notify,
+        registerRuntimeTool,
+    };
+}

package/dist/lib/schema.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Auto-tools schema helpers
+ * Zones: tool schema, registry args, command-template placeholders
+ * Owns tool argument declarations, placeholder-derived tool schemas, and persisted registry normalization
+ */
+import * as CommandTemplates from "./command-templates.ts";
+export type ToolArgType = {
+    kind: "string";
+} | {
+    kind: "path";
+} | {
+    kind: "int";
+} | {
+    kind: "number";
+} | {
+    kind: "bool";
+} | {
+    kind: "array";
+} | {
+    kind: "enum";
+    values: string[];
+};
+export interface ParsedToolArgToken {
+    arg: string;
+    defaultValue?: string;
+    declaration: string;
+    type: ToolArgType;
+}
+export interface ToolArgSpec {
+    args: string[];
+    argTypes: Record<string, ToolArgType>;
+    declarations: string[];
+    defaults: Record<string, string>;
+    error?: string;
+}
+export declare function parseToolArgToken(value: string): ParsedToolArgToken;
+export declare function parseToolArgDeclarations(value: string): ToolArgSpec;
+export declare function normalizeStoredToolArgDeclarations(argsValue: unknown, defaultsValue: unknown): ToolArgSpec & {
+    changed: boolean;
+    provided: boolean;
+};
+export declare function formatToolArgs(args: string[]): string;
+export declare function getTemplatePlaceholderNames(config: CommandTemplates.CommandTemplateConfig): string[];
+export declare function getTemplateArgTypes(config: CommandTemplates.CommandTemplateConfig): Record<string, ToolArgType>;
+export declare function getExplicitToolArgNames(args: string[] | undefined): string[];
+export declare function getToolArgNames(config: CommandTemplates.CommandTemplateConfig): string[];
+export declare function getRequiredToolArgNames(config: CommandTemplates.CommandTemplateConfig): Set<string>;
+export declare function normalizeRuntimeValues(values: Record<string, unknown>, argTypes: Record<string, ToolArgType> | undefined): Record<string, unknown>;