pi-extensible-workflows 1.0.0 → 2.0.0

package/dist/src/cli.js

@@ -1,9 +1,506 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
-import { pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+import { chmodSync, linkSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources } from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
-import { runSessionInspector } from "./session-inspector.js";
+import workflowExtension, { formatWorkflowProgress, workflowCatalog } from "./index.js";
+import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
+function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function has(value, key) { return Object.prototype.hasOwnProperty.call(value, key); }
+function clone(value) { return structuredClone(value); }
+function kebabCase(value) { return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase(); }
+function scalarType(schema) {
+    if (!object(schema) || typeof schema.type !== "string")
+        return undefined;
+    return ["string", "integer", "number", "boolean"].includes(schema.type) ? schema.type : undefined;
+}
+function schemaPlan(schema) {
+    if (!object(schema) || schema.type !== "object")
+        return { fields: [] };
+    const properties = object(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : []);
+    const fields = [];
+    for (const [name, property] of Object.entries(properties)) {
+        if (!object(property))
+            continue;
+        const directType = scalarType(property);
+        const itemType = object(property.items) ? scalarType(property.items) : undefined;
+        const type = directType ?? itemType ? directType ?? "array" : undefined;
+        if (!type)
+            continue;
+        fields.push({ name, option: `--${kebabCase(name)}`, schema: property, type, ...(itemType ? { itemType } : {}), required: required.has(name) });
+    }
+    const requiredScalars = fields.filter((field) => field.required && field.type !== "array");
+    return { fields, ...(requiredScalars.length === 1 ? { positional: requiredScalars[0] } : {}) };
+}
+function scalarLabel(type) { return type === "integer" ? "integer" : type; }
+function scalarFieldType(field) { return field.type === "array" ? field.itemType : field.type; }
+function fieldLabel(field) { return field.type === "array" ? `${field.option} <${scalarLabel(field.itemType)}>` : `${field.option}${field.type === "boolean" ? "" : ` <${scalarLabel(field.type)}>`}`; }
+function fieldDescription(field) {
+    const description = typeof field.schema.description === "string" ? field.schema.description.trim() : "";
+    const required = field.required ? "required" : "optional";
+    const defaultValue = has(field.schema, "default") ? ` default=${JSON.stringify(field.schema.default)}` : "";
+    const enumSchema = field.type === "array" && object(field.schema.items) ? field.schema.items : field.schema;
+    const enumValue = Array.isArray(enumSchema.enum) ? ` enum=${enumSchema.enum.map((value) => JSON.stringify(value)).join(",")}` : "";
+    return [description, required, defaultValue, enumValue].filter(Boolean).join("; ");
+}
+export function formatWorkflowCliHelp(fn, command = "pi-extensible-workflows") {
+    const plan = schemaPlan(fn.input);
+    const lines = [`Usage: ${command} run ${fn.name}${plan.positional ? ` <${plan.positional.name}>` : ""} [options]`, "", fn.description];
+    if (plan.positional) {
+        lines.push("", "Arguments:", `  <${plan.positional.name}>  ${scalarLabel(scalarFieldType(plan.positional))}; ${fieldDescription(plan.positional)}`);
+    }
+    lines.push("", "Options:");
+    for (const field of plan.fields) {
+        const label = field === plan.positional ? `${field.option} <${scalarLabel(scalarFieldType(field))}>` : fieldLabel(field);
+        lines.push(`  ${label.padEnd(24)}${fieldDescription(field)}`);
+    }
+    lines.push("  --input <json>".padEnd(28) + "JSON input escape hatch for complex schemas", ...launcherHelpLines(), "  -h, --help".padEnd(28) + "Show this help");
+    return `${lines.join("\n")}\n`;
+}
+function enumAllows(schema, value) {
+    return !Array.isArray(schema.enum) || schema.enum.some((candidate) => JSON.stringify(candidate) === JSON.stringify(value));
+}
+function coerce(raw, type, schema) {
+    let value;
+    if (type === "string")
+        value = raw;
+    else if (type === "integer") {
+        if (!/^-?(?:0|[1-9]\d*)$/.test(raw))
+            throw new Error(`Invalid integer: ${raw}`);
+        value = Number(raw);
+        if (!Number.isSafeInteger(value))
+            throw new Error(`Invalid integer: ${raw}`);
+    }
+    else if (type === "number") {
+        value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new Error(`Invalid number: ${raw}`);
+    }
+    else {
+        if (raw !== "true" && raw !== "false")
+            throw new Error(`Invalid boolean: ${raw}`);
+        value = raw === "true";
+    }
+    if (!enumAllows(schema, value))
+        throw new Error(`Invalid value for enum: ${raw}`);
+    return value;
+}
+function parseJsonInput(value) {
+    try {
+        return clone(JSON.parse(value));
+    }
+    catch {
+        throw new Error("Invalid JSON passed to --input");
+    }
+}
+export function parseWorkflowCliArgs(schema, rawArgs) {
+    const plan = schemaPlan(schema);
+    const fields = new Map(plan.fields.map((field) => [field.option, field]));
+    const result = {};
+    let input;
+    let positionalUsed = false;
+    let endOptions = false;
+    const assign = (field, raw) => {
+        if (field.type === "array") {
+            const values = Array.isArray(result[field.name]) ? result[field.name] : [];
+            values.push(coerce(raw, field.itemType, field.schema.items));
+            result[field.name] = values;
+        }
+        else
+            result[field.name] = coerce(raw, field.type, field.schema);
+    };
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = rawArgs[index];
+        if (token === "--") {
+            endOptions = true;
+            continue;
+        }
+        if (!endOptions && (token === "--input" || token.startsWith("--input="))) {
+            if (input !== undefined)
+                throw new Error("--input may only be provided once");
+            const raw = token.startsWith("--input=") ? token.slice("--input=".length) : rawArgs[++index];
+            if (raw === undefined)
+                throw new Error("Missing value for --input");
+            input = parseJsonInput(raw);
+            continue;
+        }
+        if (!endOptions && token.startsWith("--")) {
+            const equals = token.indexOf("=");
+            const option = equals >= 0 ? token.slice(0, equals) : token;
+            const negated = equals < 0 && option.startsWith("--no-");
+            const field = fields.get(negated ? `--${option.slice("--no-".length)}` : option);
+            if (!field)
+                throw new Error(`Unknown option: ${option}`);
+            if (negated) {
+                if (field.type !== "boolean")
+                    throw new Error(`Invalid boolean option: ${option}`);
+                result[field.name] = false;
+            }
+            else if (field.type === "boolean") {
+                if (equals >= 0)
+                    assign(field, token.slice(equals + 1));
+                else if (rawArgs[index + 1] === "true" || rawArgs[index + 1] === "false")
+                    assign(field, rawArgs[++index]);
+                else
+                    result[field.name] = true;
+            }
+            else {
+                const raw = equals >= 0 ? token.slice(equals + 1) : rawArgs[++index];
+                if (raw === undefined || raw.startsWith("--"))
+                    throw new Error(`Missing value for ${option}`);
+                assign(field, raw);
+            }
+            continue;
+        }
+        const positional = plan.positional;
+        const numericNegative = positional && (positional.type === "integer" || positional.type === "number") && /^-\d/.test(token);
+        if (!endOptions && token.startsWith("-") && !numericNegative)
+            throw new Error(`Unknown option: ${token}`);
+        if (!positional || positionalUsed)
+            throw new Error(`Unexpected argument: ${token}`);
+        assign(positional, token);
+        positionalUsed = true;
+    }
+    if (input !== undefined) {
+        if (Object.keys(result).length || positionalUsed)
+            throw new Error("--input cannot be combined with CLI arguments");
+        if (!object(input))
+            throw new Error("Workflow input must be a JSON object");
+        for (const field of plan.fields)
+            if (!has(input, field.name) && has(field.schema, "default"))
+                input[field.name] = clone(field.schema.default);
+        return input;
+    }
+    for (const field of plan.fields)
+        if (!has(result, field.name) && has(field.schema, "default"))
+            result[field.name] = clone(field.schema.default);
+    for (const field of plan.fields)
+        if (field.required && !has(result, field.name))
+            throw new Error(`Missing required argument: ${field.name}`);
+    return result;
+}
+function launcherHelpLines() {
+    return [
+        "  --approve".padEnd(28) + "Trust project resources for this launch",
+        "  --no-approve".padEnd(28) + "Do not trust project resources for this launch",
+        "  --".padEnd(28) + "End launcher option parsing; pass later tokens to workflow input",
+    ];
+}
+function workflowUsage() { return [`Usage: pi-extensible-workflows run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+function exportUsage() { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+function stripTrustOptions(rawArgs) {
+    const args = [];
+    let trustOverride;
+    let endOptions = false;
+    for (const arg of rawArgs) {
+        if (arg === "--") {
+            endOptions = true;
+            args.push(arg);
+            continue;
+        }
+        if (!endOptions && (arg === "--approve" || arg === "--no-approve")) {
+            const next = arg === "--approve";
+            if (trustOverride !== undefined && trustOverride !== next)
+                throw new Error("--approve and --no-approve cannot be combined");
+            trustOverride = next;
+        }
+        else
+            args.push(arg);
+    }
+    return { args, ...(trustOverride !== undefined ? { trustOverride } : {}) };
+}
+async function createWorkflowRuntime(options, shutdownHandlers = []) {
+    const cwd = options.cwd ?? process.cwd();
+    const agentDir = options.agentDir ?? getAgentDir();
+    const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+    const requiredTrust = hasTrustRequiringProjectResources(cwd);
+    const trustStore = new ProjectTrustStore(agentDir);
+    const defaultProjectTrust = settingsManager.getDefaultProjectTrust();
+    const resolveProjectTrust = async ({ extensionsResult }) => {
+        if (options.trustOverride !== undefined)
+            return options.trustOverride;
+        if (!requiredTrust)
+            return true;
+        const projectTrustContext = {
+            cwd,
+            mode: "print",
+            hasUI: false,
+            ui: { select: async () => undefined, confirm: async () => false, input: async () => undefined, notify: () => { } },
+        };
+        for (const extension of extensionsResult.extensions) {
+            for (const handler of extension.handlers.get("project_trust") ?? []) {
+                try {
+                    const result = await handler({ type: "project_trust", cwd }, projectTrustContext);
+                    if (result.trusted === "undecided")
+                        continue;
+                    if (result.trusted !== "yes" && result.trusted !== "no")
+                        continue;
+                    const trusted = result.trusted === "yes";
+                    if (result.remember === true)
+                        trustStore.set(cwd, trusted);
+                    return trusted;
+                }
+                catch { /* Project trust extensions are best effort, as in Pi. */ }
+            }
+        }
+        const savedTrust = trustStore.get(cwd);
+        if (savedTrust !== null)
+            return savedTrust;
+        return defaultProjectTrust === "always";
+    };
+    const services = await createAgentSessionServices({
+        cwd,
+        agentDir,
+        settingsManager,
+        resourceLoaderOptions: {},
+        resourceLoaderReloadOptions: { resolveProjectTrust },
+    });
+    const extensions = services.resourceLoader.getExtensions();
+    const tools = [];
+    const activeTools = [...new Set(["read", "bash", "edit", "write"].concat(extensions.extensions.flatMap((extension) => [...extension.tools.keys()]), ["workflow"]))];
+    const headlessPi = {
+        registerTool(tool) { tools.push(tool); },
+        registerCommand() { },
+        getThinkingLevel: () => services.settingsManager.getDefaultThinkingLevel() ?? "medium",
+        getActiveTools: () => activeTools,
+        on(name, handler) { if (name === "session_shutdown" && typeof handler === "function")
+            shutdownHandlers.push(handler); },
+        appendEntry() { },
+        sendMessage() { },
+        events: { emit() { } },
+    };
+    workflowExtension(headlessPi, homedir(), undefined, undefined, agentDir);
+    const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow");
+    if (!workflowTool)
+        throw new Error("The workflow runtime could not be initialized");
+    return { catalog: workflowCatalog(), services, workflowTool, shutdownHandlers };
+}
+function availableModelInfo(services, available = false) {
+    const models = available ? services.modelRuntime.getAvailableSnapshot() : services.modelRuntime.getModels();
+    return models.map(({ provider, id }) => ({ provider, id }));
+}
+async function selectedModel(services) {
+    const { session } = await createAgentSessionFromServices({ services, sessionManager: SessionManager.inMemory(), noTools: "all" });
+    try {
+        const model = session.model;
+        return model ? { provider: model.provider, id: model.id } : undefined;
+    }
+    finally {
+        session.dispose();
+    }
+}
+function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
+function commandName(value) { return value.trim() && !value.includes("/") && !value.includes("\\") ? value.trim() : ""; }
+function writeLauncher(destination, workflowName, force) {
+    const parent = dirname(destination);
+    mkdirSync(parent, { recursive: true });
+    const tempDir = mkdtempSync(join(parent, ".pi-extensible-workflows-"));
+    const tempPath = join(tempDir, "launcher");
+    try {
+        writeFileSync(tempPath, `#!/bin/sh\nexec node ${shellQuote(fileURLToPath(import.meta.url))} run ${shellQuote(workflowName)} "$@"\n`, { mode: 0o755 });
+        chmodSync(tempPath, 0o755);
+        if (force)
+            renameSync(tempPath, destination);
+        else {
+            try {
+                linkSync(tempPath, destination);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw new Error(`Destination already exists: ${destination}; use --force to replace it`, { cause: error });
+                throw error;
+            }
+        }
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+class CliProgress {
+    stderr;
+    tty;
+    #lastStable = "";
+    #lines = 0;
+    #frame = 0;
+    #run;
+    #timer;
+    constructor(stderr, tty) {
+        this.stderr = stderr;
+        this.tty = tty;
+    }
+    update(run) {
+        const stable = formatWorkflowProgress(run, "◇");
+        if (!this.tty) {
+            if (stable !== this.#lastStable) {
+                this.#lastStable = stable;
+                this.stderr(`${stable}\n`);
+            }
+            return;
+        }
+        this.#run = run;
+        this.#timer ??= setInterval(() => { this.render(); }, 80);
+        this.#timer.unref();
+        this.render();
+    }
+    render() {
+        if (!this.#run)
+            return;
+        const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"][this.#frame++ % 10] ?? "◇";
+        const width = process.stderr.columns || 80;
+        const text = formatWorkflowProgress(this.#run, spinner).split("\n").map((line) => line.length <= width ? line : `${line.slice(0, Math.max(0, width - 1))}…`).join("\n");
+        this.stderr(`${this.#lines ? `\x1b[${String(this.#lines)}A` : ""}${this.#lines ? "" : "\x1b[?25l"}\x1b[0J${text}\n`);
+        this.#lines = text.split("\n").length;
+    }
+    finish() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = undefined;
+        }
+        if (this.tty && this.#lines) {
+            this.stderr(`\x1b[${String(this.#lines)}A\x1b[0J\x1b[?25h`);
+            this.#lines = 0;
+        }
+        this.#run = undefined;
+    }
+}
+async function invokeWorkflow(fn, args, runtime, options, context) {
+    if (!Value.Check(fn.input, args))
+        throw new Error(`Invalid input for ${fn.name}`);
+    const progress = new CliProgress(options.stderr, options.isTTY ?? process.stderr.isTTY);
+    try {
+        const result = await runtime.workflowTool.execute(randomUUID(), { workflow: fn.name, args, foreground: true }, options.signal, (update) => { if (object(update) && object(update.details) && object(update.details.run))
+            progress.update(update.details.run); }, context);
+        const details = object(result.details) ? result.details : {};
+        if (has(details, "value"))
+            return details.value;
+        const first = result.content[0];
+        if (!first || first.type !== "text")
+            throw new Error("Workflow returned no result");
+        try {
+            return parseJsonInput(first.text);
+        }
+        catch {
+            throw new Error("Workflow returned invalid JSON");
+        }
+    }
+    finally {
+        progress.finish();
+    }
+}
+async function createWorkflowContext(runtime, options) {
+    const model = await selectedModel(runtime.services);
+    const sessionManager = SessionManager.inMemory();
+    const modelRegistry = { getAll: () => availableModelInfo(runtime.services), getAvailable: () => availableModelInfo(runtime.services, true) };
+    return { cwd: options.cwd ?? process.cwd(), mode: "print", hasUI: false, ...(model ? { model } : {}), modelRegistry, sessionManager, isProjectTrusted: () => runtime.services.settingsManager.isProjectTrusted(), ui: { select: async () => undefined, confirm: async () => false, input: async () => undefined, notify: () => { }, onTerminalInput: () => () => { }, setStatus: () => { }, setWorkingMessage: () => { }, setWorkingVisible: () => { }, setWorkingIndicator: () => { }, setHiddenThinkingLabel: () => { }, setWidget: () => { }, setFooter: () => { }, setHeader: () => { }, setTitle: () => { }, custom: async () => undefined, pasteToEditor: () => { }, setEditorText: () => { }, getEditorText: () => "", editor: async () => undefined, addAutocompleteProvider: () => { } }, headless: true };
+}
+async function shutdownWorkflowRuntime(handlers, context) {
+    for (const handler of handlers) {
+        try {
+            await handler({ type: "session_shutdown", reason: "quit" }, context);
+        }
+        catch { /* Shutdown is best effort. */ }
+    }
+}
+async function withWorkflowRuntime(options, action) {
+    const shutdownHandlers = [];
+    let context = { cwd: options.cwd ?? process.cwd(), mode: "print", hasUI: false, headless: true };
+    try {
+        const runtime = await createWorkflowRuntime(options, shutdownHandlers);
+        context = await createWorkflowContext(runtime, options);
+        return await action(runtime, context);
+    }
+    finally {
+        await shutdownWorkflowRuntime(shutdownHandlers, context);
+    }
+}
+async function runWorkflowCli(rawArgs, options) {
+    const parsed = stripTrustOptions(rawArgs);
+    const args = parsed.args;
+    if (!args.length || args[0] === "--help" || args[0] === "-h") {
+        options.write(workflowUsage());
+        return args.length ? 0 : 1;
+    }
+    const name = args[0];
+    return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime, context) => {
+        const help = args.slice(1).some((arg) => arg === "--help" || arg === "-h");
+        const fn = runtime.catalog.functions.find((candidate) => candidate.name === name);
+        if (!fn)
+            throw new Error(`Unknown workflow function: ${name}`);
+        if (help) {
+            options.write(formatWorkflowCliHelp(fn));
+            return 0;
+        }
+        const input = parseWorkflowCliArgs(fn.input, args.slice(1));
+        const value = await invokeWorkflow(fn, input, runtime, options, context);
+        options.write(`${JSON.stringify(value)}\n`);
+        return 0;
+    });
+}
+async function exportWorkflowCli(rawArgs, options) {
+    const parsed = stripTrustOptions(rawArgs);
+    const args = parsed.args;
+    if (!args.length || args[0] === "--help" || args[0] === "-h") {
+        options.write(exportUsage());
+        return args.length ? 0 : 1;
+    }
+    const workflowName = args[0];
+    return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime) => {
+        let name;
+        let output;
+        let force = false;
+        for (let index = 1; index < args.length; index += 1) {
+            const arg = args[index];
+            if (arg === "--force") {
+                force = true;
+                continue;
+            }
+            const equals = arg.indexOf("=");
+            const option = equals >= 0 ? arg.slice(0, equals) : arg;
+            if (option === "--name" || option === "--output") {
+                const value = equals >= 0 ? arg.slice(equals + 1) : args[++index];
+                if (!value)
+                    throw new Error(`Missing value for ${option}`);
+                if (option === "--name")
+                    name = value;
+                else
+                    output = value;
+                continue;
+            }
+            if (arg === "--help" || arg === "-h") {
+                options.write(exportUsage());
+                return 0;
+            }
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        if (!runtime.catalog.functions.some((candidate) => candidate.name === workflowName))
+            throw new Error(`Unknown workflow function: ${workflowName}`);
+        const command = commandName(name ?? kebabCase(workflowName));
+        if (!command)
+            throw new Error("Command name must be a non-empty name without path separators");
+        const destination = output ? output : join(homedir(), ".local", "bin", command);
+        writeLauncher(destination, workflowName, force);
+        if (!output) {
+            const binDir = join(homedir(), ".local", "bin");
+            const pathEntries = (process.env.PATH ?? "").split(":").filter(Boolean).map((entry) => { try {
+                return realpathSync(entry);
+            }
+            catch {
+                return entry;
+            } });
+            if (!pathEntries.includes(binDir))
+                options.stderr(`Warning: ${binDir} is not in PATH\n`);
+        }
+        options.write(`Exported ${destination}\n`);
+        return 0;
+    });
+}
 export async function runCli(args, options = {}, write = (text) => { process.stdout.write(text); }) {
+    const stderr = options.stderr ?? ((text) => { process.stderr.write(text); });
     if (args[0] === "doctor" && args.length === 1) {
         const report = await doctor(options);
         write(formatDoctorReport(report));
@@ -19,8 +516,35 @@ export async function runCli(args, options = {}, write = (text) => { process.std
             return 1;
         }
     }
-    write("Usage: pi-extensible-workflows doctor | inspect [session-id]\n");
+    if (args[0] === "transcript" && args.length === 2) {
+        try {
+            if (options.transcript)
+                await options.transcript(args[1]);
+            else
+                write(`${transcriptFileLines(args[1]).join("\n")}\n`);
+            return 0;
+        }
+        catch (error) {
+            write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+    if (args[0] === "run" || args[0] === "export") {
+        try {
+            const workflowOptions = { write, stderr, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}), ...(options.agentDir !== undefined ? { agentDir: options.agentDir } : {}), ...(options.signal ? { signal: options.signal } : {}), ...(options.trustOverride !== undefined ? { trustOverride: options.trustOverride } : {}), ...(options.isTTY !== undefined ? { isTTY: options.isTTY } : {}) };
+            return args[0] === "run" ? await runWorkflowCli(args.slice(1), workflowOptions) : await exportWorkflowCli(args.slice(1), workflowOptions);
+        }
+        catch (error) {
+            stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+    write("Usage: pi-extensible-workflows doctor | inspect [session-id] | transcript <session-file> | run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]\n");
     return 1;
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href)
-    process.exitCode = await runCli(process.argv.slice(2));
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    const controller = new AbortController();
+    const onSignal = () => { controller.abort(); };
+    process.once("SIGINT", onSignal);
+    process.exitCode = await runCli(process.argv.slice(2), { signal: controller.signal });
+}

package/dist/src/doctor.d.ts

@@ -1,4 +1,4 @@
-import { type AgentResourcePolicy, type WorkflowScriptDefinition, type WorkflowSettings } from "./index.js";
+import { type AgentResourcePolicy, type WorkflowFunction, type WorkflowSettings } from "./index.js";
 export type DoctorSeverity = "error" | "warning";
 export interface DoctorDiagnostic {
     severity: DoctorSeverity;
@@ -15,7 +15,7 @@ export interface DoctorRole {
     overrides?: string;
     overriddenBy?: string;
 }
-export interface DoctorWorkflow {
+export interface DoctorFunction {
     name: string;
     description: string;
     valid: boolean;
@@ -36,7 +36,7 @@ export interface DoctorPiState {
     }[];
     extensions?: readonly string[];
     skills?: readonly string[];
-    workflows: Readonly<Record<string, WorkflowScriptDefinition>>;
+    functions: Readonly<Record<string, WorkflowFunction>>;
 }
 export interface DoctorReport {
     cwd: string;
@@ -46,7 +46,7 @@ export interface DoctorReport {
     trust: DoctorTrust;
     activeTools: readonly string[];
     roles: readonly DoctorRole[];
-    workflows: readonly DoctorWorkflow[];
+    functions: readonly DoctorFunction[];
     resourcePolicy: AgentResourcePolicy;
     diagnostics: readonly DoctorDiagnostic[];
 }

package/dist/src/doctor.js

@@ -2,7 +2,7 @@ import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { ModelRuntime, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_SETTINGS, loadSettings, parseModelReference, resolveAgentResourcePolicy, resolveModelReference, parseRoleMarkdown, preflight, registeredWorkflowDefinitions, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, WorkflowError, } from "./index.js";
+import { DEFAULT_SETTINGS, loadSettings, resolveAgentResourcePolicy, resolveModelReference, parseRoleMarkdown, registeredWorkflowFunctions, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "./index.js";
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
 function canonical(path) {
     const absolute = resolve(path);
@@ -88,7 +88,7 @@ async function discoverPi(cwd, agentDir) {
                 ...extensions.errors.map(({ path, error }) => ({ path, message: error })),
                 ...services.diagnostics.filter(({ type }) => type === "error").map(({ message }) => ({ message })),
             ],
-            workflows: registeredWorkflowDefinitions(),
+            functions: registeredWorkflowFunctions(),
         };
     }
     finally {
@@ -153,9 +153,6 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
             diagnostics.push(diagnostic("error", "ROLE_TOOL_INACTIVE", `Tool is unknown or inactive: ${tool}`, path, "Use a tool listed under Active tools or enable its Pi extension."));
     return definition;
 }
-class DoctorModelSet extends Set {
-    has(value) { parseModelReference(value); return true; }
-}
 function matchResourcePolicy(policy, pi) {
     const extensions = new Set((pi.extensions ?? []).map(canonical));
     const skills = new Set(pi.skills ?? []);
@@ -182,7 +179,7 @@ export async function doctor(options = {}) {
     }
     catch (error) {
         diagnostics.push(diagnostic("error", "PI_DISCOVERY", `Pi headless discovery failed: ${error.message}`, undefined, "Open and trust the project in Pi, fix extension errors, then rerun doctor."));
-        pi = { trust: { required: false, trusted: false, source: "discovery failed" }, activeTools: [], knownModels: [], availableModels: [], extensionErrors: [], workflows: {} };
+        pi = { trust: { required: false, trusted: false, source: "discovery failed" }, activeTools: [], knownModels: [], availableModels: [], extensionErrors: [], functions: {} };
     }
     if (options.activeTools)
         pi = { ...pi, activeTools: options.activeTools.filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_catalog") };
@@ -240,33 +237,14 @@ export async function doctor(options = {}) {
         else
             definitions.delete(name);
     }
-    const workflows = [];
-    for (const [name, workflow] of Object.entries(pi.workflows).sort(([left], [right]) => left.localeCompare(right))) {
-        let valid = true;
-        try {
-            const checked = preflight(workflow.script, {
-                models: new DoctorModelSet(pi.knownModels),
-                tools: activeTools,
-                agentTypes: new Set(definitions.keys()),
-                modelAliases: aliases,
-                knownModels,
-                settingsPath,
-            }, [], { name, description: workflow.description });
-            for (const model of checked.referenced.models)
-                if (!knownModels.has(model) || !availableModels.has(model))
-                    diagnostics.push(diagnostic("warning", "MODEL_UNAVAILABLE", `Model is valid-shaped but unavailable: ${model}`, name));
-        }
-        catch (error) {
-            valid = false;
-            const typed = error instanceof WorkflowError ? error : new WorkflowError("INTERNAL_ERROR", String(error));
-            diagnostics.push(diagnostic("error", `WORKFLOW_${typed.code}`, typed.message, name, "Fix the registered workflow source or its referenced role/tool/model/extension."));
-        }
-        workflows.push({ name, description: workflow.description, valid });
+    const functions = [];
+    for (const [name, fn] of Object.entries(pi.functions).sort(([left], [right]) => left.localeCompare(right))) {
+        functions.push({ name, description: fn.description, valid: true });
     }
     const severityOrder = { error: 0, warning: 1 };
     diagnostics.sort((left, right) => severityOrder[left.severity] - severityOrder[right.severity] || (left.source ?? "").localeCompare(right.source ?? "") || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
     roles.sort((left, right) => left.name.localeCompare(right.name) || left.scope.localeCompare(right.scope));
-    return { cwd, agentDir, settingsPath, settings, trust: pi.trust, activeTools: [...activeTools].sort(), roles, workflows, resourcePolicy, diagnostics };
+    return { cwd, agentDir, settingsPath, settings, trust: pi.trust, activeTools: [...activeTools].sort(), roles, functions, resourcePolicy, diagnostics };
 }
 function count(report, severity) { return report.diagnostics.filter((item) => item.severity === severity).length; }
 export function doctorExitCode(report) { return count(report, "error") > 0 ? 1 : 0; }
@@ -301,8 +279,8 @@ export function formatDoctorReport(report) {
         "## Roles",
         ...(report.roles.length ? report.roles.map((role) => `- \`${role.name}\` (${role.scope}, ${role.active ? "active" : role.overriddenBy ? `overridden by ${role.overriddenBy}` : "inactive: project untrusted"}) - \`${role.path}\`${role.overrides ? `; overrides \`${role.overrides}\`` : ""}`) : ["- None found"]),
         "",
-        "## Reusable workflows",
-        ...(report.workflows.length ? report.workflows.map((workflow) => `- [${workflow.valid ? "ok" : "error"}] \`${workflow.name}\` - ${workflow.description}`) : ["- None registered"]),
+        "## Reusable functions",
+        ...(report.functions.length ? report.functions.map((fn) => `- [${fn.valid ? "ok" : "error"}] \`${fn.name}\` - ${fn.description}`) : ["- None registered"]),
         "",
         "## Diagnostics",
         ...(report.diagnostics.length ? report.diagnostics.map((item) => `- [${item.severity}] ${item.code}${item.source ? ` \`${item.source}\`` : ""}: ${item.message}${item.hint ? ` Fix: ${item.hint}` : ""}`) : ["- [ok] No diagnostics"]),