@llblab/pi-actors 0.19.11 → 0.20.1

package/dist/lib/recipe-references.js

@@ -0,0 +1,542 @@
+/**
+ * Template recipe reference helpers
+ * Zones: registry config, async runs, path resolution
+ * Owns detection, loading, and recipe-layer expansion for template recipe files
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import * as CommandTemplates from "./command-templates.js";
+import * as Paths from "./paths.js";
+const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
+const MAX_RECIPE_IMPORT_DEPTH = 32;
+function hasWhitespace(value) {
+    return /\s/.test(value);
+}
+export function resolveRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
+    const trimmed = value.trim();
+    const repoRoot = resolve(recipeRoot, "..");
+    const expanded = trimmed
+        .replaceAll("{repo}", repoRoot)
+        .replaceAll("{agent}", Paths.getAgentDir());
+    if (expanded.startsWith("~/"))
+        return resolve(homedir(), expanded.slice(2));
+    if (expanded.includes("/"))
+        return resolve(expanded);
+    return resolve(recipeRoot, expanded.endsWith(".json") ? expanded : `${expanded}.json`);
+}
+function isBareRecipeName(value) {
+    const trimmed = value.trim();
+    return Boolean(trimmed) && !trimmed.includes("/") && !trimmed.startsWith("~") && !trimmed.includes("{");
+}
+function recipeNameFile(value) {
+    const trimmed = value.trim();
+    return trimmed.endsWith(".json") ? trimmed : `${trimmed}.json`;
+}
+function resolveRecipeImportPath(value, currentRecipeRoot) {
+    if (!isBareRecipeName(value))
+        return resolveRecipePath(value, currentRecipeRoot);
+    const file = recipeNameFile(value);
+    const roots = [
+        Paths.getRecipeRoot(),
+        currentRecipeRoot,
+        Paths.getPackagedRecipeRoot(),
+    ];
+    const candidates = [...new Set(roots.map((root) => resolve(root, file)))];
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+export function getRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || hasWhitespace(trimmed))
+        return undefined;
+    if (trimmed.endsWith(".json"))
+        return resolveRecipePath(trimmed, recipeRoot);
+    const path = resolveRecipePath(trimmed, recipeRoot);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
+            ? path
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isImportNode(value) {
+    if (!isRecord(value) || Object.hasOwn(value, "template"))
+        return false;
+    return typeof value.name === "string";
+}
+function isValidRecipeTemplateNode(value) {
+    if (isImportNode(value))
+        return true;
+    if (isRecord(value)) {
+        if (isImportNode(value.template))
+            return true;
+        if (Array.isArray(value.template))
+            return isValidRecipeTemplateArray(value.template);
+    }
+    return (CommandTemplates.expandCommandTemplateConfigs(value).length > 0);
+}
+function isValidRecipeTemplateArray(value) {
+    return (value.length > 0 && value.every((item) => isValidRecipeTemplateNode(item)));
+}
+function normalizeRecipeTemplate(value) {
+    if (typeof value === "string")
+        return value.trim() || undefined;
+    if (Array.isArray(value)) {
+        const template = value;
+        return isValidRecipeTemplateArray(template) ? template : undefined;
+    }
+    if (isImportNode(value))
+        return value;
+    if (value && typeof value === "object") {
+        const template = value;
+        if (Array.isArray(template.template) &&
+            isValidRecipeTemplateArray(template.template))
+            return template;
+        if (isImportNode(template.template))
+            return template;
+        return CommandTemplates.expandCommandTemplateConfigs(template).length > 0
+            ? template
+            : undefined;
+    }
+    return undefined;
+}
+function getRecipeCommandTemplate(raw) {
+    const template = raw.template;
+    const envelope = {};
+    for (const key of [
+        "args",
+        "defaults",
+        "parallel",
+        "label",
+        "when",
+        "timeout",
+        "delay",
+        "output",
+        "retry",
+        "failure",
+        "recover",
+        "repeat",
+    ]) {
+        if (raw[key] !== undefined)
+            envelope[key] = raw[key];
+    }
+    if (Object.keys(envelope).length === 0)
+        return normalizeRecipeTemplate(template);
+    if (template && typeof template === "object" && !Array.isArray(template)) {
+        return normalizeRecipeTemplate({
+            ...envelope,
+            ...template,
+        });
+    }
+    return normalizeRecipeTemplate({ ...envelope, template });
+}
+export function readRawRecipeConfig(path) {
+    if (!existsSync(path))
+        return undefined;
+    const size = statSync(path).size;
+    if (size > MAX_RECIPE_FILE_BYTES) {
+        throw new Error(`Recipe file exceeds size limit ${MAX_RECIPE_FILE_BYTES} bytes: ${path}`);
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return raw && typeof raw === "object" ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getRecipeIdFromPath(file) {
+    return basename(file, ".json");
+}
+function readRecipeConfig(value) {
+    const path = getRecipePath(value);
+    return path ? readResolvedRecipeConfig(path) : undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function getRecipeImports(raw) {
+    if (!isRecord(raw.imports))
+        return {};
+    const result = {};
+    for (const [alias, value] of Object.entries(raw.imports)) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(alias))
+            throw new Error(`Invalid recipe import alias: ${alias}`);
+        if (typeof value === "string") {
+            result[alias] = value;
+            continue;
+        }
+        if (!isRecord(value))
+            throw new Error(`Recipe import must be a string or object: ${alias}`);
+        const from = typeof value.from === "string" ? value.from.trim() : "";
+        if (!from)
+            throw new Error(`Recipe import must define from: ${alias}`);
+        result[alias] = {
+            from,
+            ...(isRecord(value.defaults) ? { defaults: value.defaults } : {}),
+            ...(isRecord(value.values) ? { values: value.values } : {}),
+        };
+    }
+    return result;
+}
+function getImportFrom(value) {
+    return typeof value === "string" ? value : (value.from ?? "");
+}
+function getPathValue(source, path) {
+    if (!path)
+        return source;
+    let current = source;
+    for (const key of path.split(".")) {
+        if (!key)
+            continue;
+        if (!isRecord(current) || !Object.hasOwn(current, key))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function resolveImportRef(ref, imports, allowMissing = false) {
+    for (const [alias, imported] of Object.entries(imports)) {
+        const prefix = `${alias}.`;
+        if (!ref.startsWith(prefix))
+            continue;
+        const rest = ref.slice(prefix.length);
+        const match = /^(name|file|defaults|values)(?:\.(.+))?$/.exec(rest);
+        if (!match)
+            return { matched: false, value: undefined };
+        const section = match[1];
+        if (section === "name")
+            return { matched: true, value: imported.name };
+        if (section === "file")
+            return { matched: true, value: imported.file };
+        const value = section === "defaults" ? imported.defaults : imported.values;
+        const resolved = getPathValue(value, match[2]);
+        if (resolved === undefined && !allowMissing)
+            throw new Error(`Unknown recipe import reference: ${ref}`);
+        return { matched: true, value: resolved };
+    }
+    return { matched: false, value: undefined };
+}
+function isFalsyImportValue(value) {
+    return (value === undefined ||
+        value === null ||
+        value === false ||
+        value === 0 ||
+        value === "");
+}
+function parseImportLiteral(value, imports) {
+    const trimmed = value.trim();
+    const quoted = trimmed.match(/^(["'])(.*)\1$/);
+    if (quoted)
+        return quoted[2];
+    const resolved = resolveImportRef(trimmed, imports, true);
+    return resolved.matched ? resolved.value : trimmed;
+}
+function evaluateImportExpression(content, imports) {
+    const trimmed = content.trim();
+    const ternary = trimmed.match(/^(.+?)\?([^:]*):(.*)$/);
+    if (ternary) {
+        const condition = resolveImportRef(ternary[1].trim(), imports, true);
+        if (!condition.matched)
+            return { matched: false, value: undefined };
+        return {
+            matched: true,
+            value: parseImportLiteral(isFalsyImportValue(condition.value) ? ternary[3] : ternary[2], imports),
+        };
+    }
+    const fallback = trimmed.match(/^([^=]+)=(.*)$/);
+    if (fallback) {
+        const resolved = resolveImportRef(fallback[1].trim(), imports, true);
+        if (!resolved.matched)
+            return { matched: false, value: undefined };
+        return {
+            matched: true,
+            value: resolved.value === undefined || resolved.value === null
+                ? parseImportLiteral(fallback[2], imports)
+                : resolved.value,
+        };
+    }
+    return resolveImportRef(trimmed, imports);
+}
+function substituteImportRefs(value, imports) {
+    if (typeof value === "string") {
+        const exact = /^\{([^{}]+)\}$/.exec(value);
+        if (exact) {
+            const resolved = evaluateImportExpression(exact[1], imports);
+            if (resolved.matched)
+                return resolved.value;
+        }
+        return value.replaceAll(/\{([^{}]+)\}/g, (token, ref) => {
+            const resolved = evaluateImportExpression(String(ref), imports);
+            return resolved.matched ? String(resolved.value ?? "") : token;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((item) => substituteImportRefs(item, imports));
+    if (isRecord(value)) {
+        const result = {};
+        for (const [key, child] of Object.entries(value))
+            result[key] = substituteImportRefs(child, imports);
+        return result;
+    }
+    return value;
+}
+function mergeDefaults(...items) {
+    const merged = Object.assign({}, ...items.filter(Boolean));
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function applyDefaultsToTemplate(template, defaults, overrides) {
+    const cleanOverrides = { ...overrides };
+    delete cleanOverrides.name;
+    delete cleanOverrides.values;
+    if (typeof template === "object" && !Array.isArray(template)) {
+        return {
+            ...template,
+            ...cleanOverrides,
+            ...(mergeDefaults(template.defaults, defaults, isRecord(cleanOverrides.defaults) ? cleanOverrides.defaults : undefined)
+                ? {
+                    defaults: mergeDefaults(template.defaults, defaults, isRecord(cleanOverrides.defaults)
+                        ? cleanOverrides.defaults
+                        : undefined),
+                }
+                : {}),
+        };
+    }
+    return {
+        ...cleanOverrides,
+        ...(defaults ? { defaults } : {}),
+        template,
+    };
+}
+function withActorRecipeContext(value, context) {
+    if (typeof value === "object" && !Array.isArray(value)) {
+        return { ...value, actorRecipeContext: context };
+    }
+    return { actorRecipeContext: context, template: value };
+}
+function expandImportNodes(value, imports, options = {}) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => expandImportNodes(item, imports, options));
+    }
+    const record = value;
+    const importAlias = !Object.hasOwn(record, "template") && typeof record.name === "string"
+        ? record.name
+        : undefined;
+    if (importAlias) {
+        const imported = imports[importAlias];
+        if (!imported)
+            throw new Error(`Unknown recipe import: ${importAlias}`);
+        const nodeDefaults = isRecord(record.defaults)
+            ? record.defaults
+            : undefined;
+        const nodeValues = isRecord(record.values) ? record.values : undefined;
+        const defaults = mergeDefaults(imported.defaults, imported.values, nodeDefaults, nodeValues);
+        const expanded = applyDefaultsToTemplate(imported.config.template, defaults, record);
+        return options.includeActorRecipeContext
+            ? withActorRecipeContext(expanded, {
+                alias: imported.alias,
+                file: imported.file,
+                name: imported.name,
+                path: imported.alias,
+                role: "import",
+            })
+            : expanded;
+    }
+    if (Array.isArray(record.template)) {
+        return {
+            ...record,
+            template: record.template.map((item) => expandImportNodes(item, imports, options)),
+        };
+    }
+    if (record.template && typeof record.template === "object") {
+        return {
+            ...record,
+            template: expandImportNodes(record.template, imports, options),
+        };
+    }
+    return value;
+}
+export function readResolvedRecipeConfig(file, stack = [], options = {}) {
+    const path = resolveRecipePath(file, stack.length > 0 ? dirname(stack.at(-1)) : Paths.getRecipeRoot());
+    if (stack.includes(path)) {
+        throw new Error(`Cyclic recipe import: ${[...stack, path].join(" -> ")}`);
+    }
+    if (stack.length >= MAX_RECIPE_IMPORT_DEPTH) {
+        throw new Error(`Recipe import depth exceeds limit ${MAX_RECIPE_IMPORT_DEPTH}: ${[...stack, path].join(" -> ")}`);
+    }
+    const raw = readRawRecipeConfig(path);
+    if (!raw || !Object.hasOwn(raw, "template"))
+        return undefined;
+    const imports = {};
+    for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
+        const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
+        const config = readResolvedRecipeConfig(importPath, [...stack, path], options);
+        if (!config)
+            throw new Error(`Recipe import not found: ${alias}`);
+        const bindingDefaults = typeof binding === "string" ? undefined : binding.defaults;
+        const bindingValues = typeof binding === "string" ? undefined : binding.values;
+        imports[alias] = {
+            alias,
+            file: importPath,
+            name: config.name ?? alias,
+            config,
+            defaults: { ...(config.defaults ?? {}), ...(bindingDefaults ?? {}) },
+            values: { ...(bindingValues ?? {}) },
+        };
+    }
+    const substituted = substituteImportRefs(raw, imports);
+    const template = getRecipeCommandTemplate(substituted);
+    if (!template)
+        return undefined;
+    const expandedTemplate = expandImportNodes(template, imports, options);
+    const recipeName = getRecipeIdFromPath(path);
+    const templateWithContext = options.includeActorRecipeContext
+        ? withActorRecipeContext(expandedTemplate, {
+            file: path,
+            name: recipeName,
+            path: recipeName,
+            role: stack.length > 0 ? "import" : "entry",
+        })
+        : expandedTemplate;
+    return {
+        name: recipeName,
+        ...(typeof substituted.description === "string" &&
+            substituted.description.trim()
+            ? { description: substituted.description.trim() }
+            : {}),
+        ...(typeof substituted.disabled === "boolean"
+            ? { disabled: substituted.disabled }
+            : {}),
+        ...(substituted.async === true
+            ? { async: true }
+            : substituted.async === false
+                ? { async: false }
+                : {}),
+        ...(typeof substituted.state_dir === "string"
+            ? { state_dir: substituted.state_dir }
+            : {}),
+        ...(Object.keys(imports).length > 0
+            ? { imports: getRecipeImports(raw) }
+            : {}),
+        template: templateWithContext,
+        ...(Array.isArray(substituted.args)
+            ? { args: substituted.args }
+            : {}),
+        ...(isRecord(substituted.defaults)
+            ? { defaults: substituted.defaults }
+            : {}),
+        ...(typeof substituted.parallel === "boolean"
+            ? { parallel: substituted.parallel }
+            : {}),
+        ...(typeof substituted.label === "string"
+            ? { label: substituted.label }
+            : {}),
+        ...(typeof substituted.when === "string" ||
+            typeof substituted.when === "boolean"
+            ? { when: substituted.when }
+            : {}),
+        ...(typeof substituted.timeout === "number" ||
+            typeof substituted.timeout === "string"
+            ? { timeout: substituted.timeout }
+            : {}),
+        ...(typeof substituted.delay === "number" ||
+            typeof substituted.delay === "string"
+            ? { delay: substituted.delay }
+            : {}),
+        ...(typeof substituted.output === "string"
+            ? { output: substituted.output }
+            : {}),
+        ...(isRecord(substituted.artifacts)
+            ? {
+                artifacts: Object.fromEntries(Object.entries(substituted.artifacts).filter((entry) => typeof entry[1] === "string")),
+            }
+            : {}),
+        ...(isRecord(substituted.mailbox)
+            ? {
+                mailbox: {
+                    ...(Array.isArray(substituted.mailbox.accepts)
+                        ? {
+                            accepts: substituted.mailbox.accepts.filter((value) => typeof value === "string"),
+                        }
+                        : {}),
+                    ...(Array.isArray(substituted.mailbox.emits)
+                        ? {
+                            emits: substituted.mailbox.emits.filter((value) => typeof value === "string"),
+                        }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(substituted.retire_when === "children_terminal"
+            ? { retire_when: "children_terminal" }
+            : {}),
+        ...(typeof substituted.retry === "number" ||
+            typeof substituted.retry === "string"
+            ? { retry: substituted.retry }
+            : {}),
+        ...(substituted.failure === "continue" ||
+            substituted.failure === "branch" ||
+            substituted.failure === "root"
+            ? { failure: substituted.failure }
+            : {}),
+        ...(substituted.recover !== undefined
+            ? { recover: substituted.recover }
+            : {}),
+        ...(typeof substituted.repeat === "number"
+            ? { repeat: substituted.repeat }
+            : {}),
+        ...(isRecord(substituted.values) ? { values: substituted.values } : {}),
+        ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
+    };
+}
+function collectRecipeContextRecords(file, stack, importPath, alias) {
+    const path = resolveRecipePath(file, stack.length > 0 ? dirname(stack.at(-1)) : Paths.getRecipeRoot());
+    if (stack.includes(path)) {
+        throw new Error(`Cyclic recipe import: ${[...stack, path].join(" -> ")}`);
+    }
+    if (stack.length >= MAX_RECIPE_IMPORT_DEPTH) {
+        throw new Error(`Recipe import depth exceeds limit ${MAX_RECIPE_IMPORT_DEPTH}: ${[...stack, path].join(" -> ")}`);
+    }
+    const raw = readRawRecipeConfig(path);
+    if (!raw || !Object.hasOwn(raw, "template"))
+        return [];
+    const record = {
+        ...(alias ? { alias } : {}),
+        depth: stack.length,
+        file: path,
+        import_path: importPath,
+        name: getRecipeIdFromPath(path),
+        recipe: raw,
+        role: stack.length === 0 ? "entry" : "import",
+    };
+    const imports = getRecipeImports(raw);
+    const children = Object.entries(imports).flatMap(([childAlias, binding]) => {
+        const importFile = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
+        return collectRecipeContextRecords(importFile, [...stack, path], [...importPath, childAlias], childAlias);
+    });
+    return [record, ...children];
+}
+export function buildRecipeContextRecords(file) {
+    return collectRecipeContextRecords(file, [], []);
+}
+export function getRecipeTemplate(value) {
+    return readRecipeConfig(value)?.template;
+}
+export function isRecipeReference(value) {
+    return getRecipePath(value) !== undefined;
+}
+export function isAsyncRecipeReference(value) {
+    return readRecipeConfig(value)?.async === true;
+}
+export function isRecipeTool(template, recipe) {
+    return recipe !== undefined || isRecipeReference(template);
+}

package/dist/lib/recipe-usage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Recipe usage metadata helpers
+ * Zones: recipe telemetry, muscle-memory cleanup evidence
+ * Owns lightweight launch counters for user-owned recipe files
+ */
+export declare function recordRecipeLaunch(path: string, now?: Date): boolean;

package/dist/lib/recipe-usage.js

@@ -0,0 +1,57 @@
+/**
+ * Recipe usage metadata helpers
+ * Zones: recipe telemetry, muscle-memory cleanup evidence
+ * Owns lightweight launch counters for user-owned recipe files
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { writeJsonAtomic } from "./file-state.js";
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function normalizeCalls(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : 0;
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (!isRecord(value))
+        return JSON.stringify(value);
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+        .join(",")}}`;
+}
+function getRecipeFingerprint(raw) {
+    const { usage: _usage, ...content } = raw;
+    return createHash("sha256").update(stableStringify(content)).digest("hex");
+}
+export function recordRecipeLaunch(path, now = new Date()) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (!isRecord(raw))
+            return false;
+        const usage = isRecord(raw.usage) ? raw.usage : {};
+        const fingerprint = getRecipeFingerprint(raw);
+        const changed = typeof usage.fingerprint === "string" && usage.fingerprint !== fingerprint;
+        const nowIso = now.toISOString();
+        writeJsonAtomic(path, {
+            ...raw,
+            usage: {
+                ...usage,
+                calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
+                last_called: nowIso,
+                fingerprint,
+                ...(changed ? { reset_at: nowIso } : {}),
+            },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Registry mutation use-cases
+ * Zones: registry mutations, persistence, runtime activation
+ * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
+ */
+import * as Config from "./config.ts";
+import * as CommandTemplates from "./command-templates.ts";
+export interface RegisterToolInput {
+    name?: string;
+    description?: string;
+    async?: boolean;
+    state_dir?: string;
+    template?: CommandTemplates.CommandTemplateValue | null;
+    args?: string;
+    update?: boolean;
+    values?: Record<string, unknown>;
+}
+export interface RegisterToolResultDetails {
+    args?: string[];
+    async?: boolean;
+    config?: string;
+    defaults?: Record<string, string>;
+    recipeName?: string;
+    state_dir?: string;
+    template?: CommandTemplates.CommandTemplateValue;
+    templateWarnings?: string[];
+    tool: string;
+}
+export interface RegisterToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: RegisterToolResultDetails;
+}
+export interface RegisterToolRuntimeDeps<TContext> {
+    configPath: string;
+    recipeRoot?: string;
+    getExternalToolConflict: (name: string) => string | undefined;
+    getTools: () => Map<string, Config.RegisteredTool>;
+    getActiveTools: () => string[];
+    notify: (ctx: TContext, message: string, type: "info" | "warning" | "error") => void;
+    registerRuntimeTool: (cfg: Config.RegisteredTool) => void;
+    reservedToolNames: Set<string>;
+    setActiveTools: (toolNames: string[]) => void;
+}
+export declare function executeRegisterTool<TContext>(params: unknown, ctx: TContext, deps: RegisterToolRuntimeDeps<TContext>): Promise<RegisterToolResult>;