@introspection-ai/recipes 0.13.0

package/dist/interactions.js

@@ -0,0 +1,358 @@
+/**
+ * Interaction mechanics for recipe tools: ask the user a question or request
+ * approval with one contract that works on every pi host.
+ *
+ * This module registers no tools. Recipes own their interaction tools and call
+ * `askUserQuestion()` or `askUserApproval()` from the tool's `execute()`;
+ * raw `askUser()` is the lower-level escape hatch. The module resolves the
+ * best available interaction channel and always returns a finished tool result:
+ *
+ *   1. `PI_ASK_USER_AUTO_APPROVE` — headless/CI: confirmations approve,
+ *      questions decline. Deterministic, never blocks.
+ *   2. `ctx.hasUI` (TUI and RPC modes) — walk the built-in dialogs, or the
+ *      caller's `interactive` override.
+ *   3. `PI_INTERRUPT_RESUME` (host capability flag) — return an "Awaiting
+ *      user response." result carrying a `details.interrupt` pause
+ *      descriptor; the host pauses the run and later resumes it by rewriting
+ *      this tool result with the user's response envelope.
+ *   4. Otherwise — report that interaction is unavailable so the model asks
+ *      in its plain chat reply instead. An unrendered question is never
+ *      treated as declined.
+ *
+ * The response envelopes are a frozen wire contract shared with interrupt-
+ * capable hosts (see `docs/interactions.md`): both sides must synthesize
+ * byte-identical text for the same outcome so recipes cannot tell whether an
+ * answer arrived through a local dialog or a remote resume.
+ *
+ * A `details.interrupt` with `outcome.type === "awaiting_user"` is the pause
+ * signal. Runtime hosts may adapt it to their own pause/resume state.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Well-known `reason` for a question the model needs answered. */
+export const ASK_USER_REASON_INPUT_REQUIRED = "input_required";
+/** Well-known `reason` for an approve/request-changes decision. */
+export const ASK_USER_REASON_CONFIRMATION = "confirmation";
+/** Well-known `reason` for a decision bound to a specific tool call. */
+export const ASK_USER_REASON_TOOL_CALL = "tool_call";
+/**
+ * Default dialog timeout applied in RPC mode only. RPC clients may never
+ * render a dialog, so an unanswered one must not wedge the session; the TUI
+ * gets no default timeout (a visible dialog can wait for the user).
+ */
+export const DEFAULT_RPC_DIALOG_TIMEOUT_MS = 120_000;
+const APPROVE_OPTION = "Approve";
+const REQUEST_CHANGES_OPTION = "Request changes";
+const CUSTOM_ANSWER_OPTION = "Other";
+// Frozen envelope literals — the interaction wire contract. Interrupt-capable
+// hosts synthesize the same literals when resuming a paused run, so recipes
+// see identical tool results in every mode. Do not reword without a
+// coordinated protocol change (see docs/interactions.md).
+const DECLINED_ENVELOPE = "User declined to answer. Proceed with your best judgment.";
+const AWAITING_USER_ENVELOPE = "Awaiting user response.";
+const UNAVAILABLE_ENVELOPE = "User interaction is unavailable in this session; nothing was shown to the user. " +
+    "Ask the user in your normal assistant reply instead, and continue after they respond.";
+// Recipe extensions and their host may resolve separate physical copies of
+// Recipes (for example, one under the recipe and one under runtime-worker).
+// Keep the async context process-global so either copy can establish the child
+// boundary and every current copy observes it. Retain the pre-rename symbol
+// key so old and new package versions interoperate in the same process.
+const INTERACTION_AUTO_RESOLUTION_KEY = Symbol.for("@introspection-ai/pi-recipes/interaction-auto-resolution");
+const interactionGlobals = globalThis;
+const interactionAutoResolution = interactionGlobals[INTERACTION_AUTO_RESOLUTION_KEY] ??
+    new AsyncLocalStorage();
+interactionGlobals[INTERACTION_AUTO_RESOLUTION_KEY] = interactionAutoResolution;
+/**
+ * Run `fn` with interaction requests resolved without prompting the user.
+ *
+ * Child sessions cannot own the root session's user interaction lifecycle.
+ * Approval requests are approved and questions are declined so the child can
+ * make progress without surfacing a UI dialog or an interrupt.
+ */
+export function autoResolveInteractions(fn) {
+    return interactionAutoResolution.run(true, fn);
+}
+/** @deprecated Use `autoResolveInteractions()` for the explicit behavior. */
+export function suppressInterruptResume(fn) {
+    return autoResolveInteractions(fn);
+}
+/** Ask the user, resolving the best available interaction channel. */
+export async function askUser(request, opts) {
+    const env = opts.env ?? process.env;
+    if (interactionAutoResolution.getStore() === true) {
+        return finishedResult(request, isApprovalReason(request.reason)
+            ? { type: "approved" }
+            : { type: "declined" });
+    }
+    if (flagEnabled(env.PI_ASK_USER_AUTO_APPROVE)) {
+        return finishedResult(request, isApprovalReason(request.reason)
+            ? { type: "approved" }
+            : { type: "declined" });
+    }
+    if (opts.ctx.hasUI) {
+        const timeout = opts.timeoutMs ??
+            (opts.ctx.mode === "rpc" ? DEFAULT_RPC_DIALOG_TIMEOUT_MS : undefined);
+        const dialog = {
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(timeout !== undefined ? { timeout } : {}),
+        };
+        const custom = opts.interactive
+            ? await opts.interactive(opts.ctx.ui, dialog)
+            : undefined;
+        throwIfAborted(opts.signal);
+        const outcome = custom ?? (await dialogWalk(request, opts.ctx.ui, dialog, opts.signal));
+        return finishedResult(request, outcome);
+    }
+    if (flagEnabled(env.PI_INTERRUPT_RESUME)) {
+        return awaitingUserResult(request, opts.toolCallId);
+    }
+    return finishedResult(request, { type: "unavailable" });
+}
+/** Ask a blocking clarification question without hand-authoring interrupt details. */
+export async function askUserQuestion(request, opts) {
+    const metadata = compactRecord({
+        kind: "ask_user_question",
+        ...(request.header ? { header: request.header } : {}),
+        question: request.question,
+        ...(request.metadata ?? {}),
+    });
+    return askUser({
+        reason: ASK_USER_REASON_INPUT_REQUIRED,
+        message: request.question,
+        options: request.options,
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+        ...(request.display ? { display: request.display } : {}),
+        ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
+    }, opts);
+}
+/** Request approval without hand-authoring interrupt details or display data. */
+export async function askUserApproval(request, opts) {
+    const kind = request.kind?.trim() || "approval";
+    const title = request.title?.trim();
+    const body = request.body?.trim();
+    const message = request.message?.trim() || (title ? `Approve ${title}?` : "Approve?");
+    const display = compactDisplay({
+        kind,
+        ...(title ? { title } : {}),
+        ...(body ? { body } : {}),
+        ...(request.sections?.length ? { sections: request.sections } : {}),
+    });
+    const metadata = compactRecord({
+        kind,
+        ...(title ? { title } : {}),
+        ...(body ? { body } : {}),
+        ...(display?.sections?.length ? { sections: display.sections } : {}),
+        ...(request.metadata ?? {}),
+    });
+    return askUser({
+        reason: ASK_USER_REASON_CONFIRMATION,
+        message,
+        ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+        ...(display ? { display } : {}),
+        ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
+    }, opts);
+}
+function flagEnabled(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+function isApprovalReason(reason) {
+    return (reason === ASK_USER_REASON_CONFIRMATION ||
+        reason === ASK_USER_REASON_TOOL_CALL);
+}
+function throwIfAborted(signal) {
+    // Dialogs resolve undefined for both a user dismissal and a turn abort;
+    // only the signal distinguishes them. A dismissal is a decline, an abort
+    // must not fabricate an outcome.
+    if (signal?.aborted) {
+        throw new Error("User interaction aborted");
+    }
+}
+function compactRecord(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined &&
+        value !== null &&
+        (!Array.isArray(value) || value.length > 0)));
+}
+function compactDisplay(display) {
+    const title = display.title?.trim();
+    const body = display.body?.trim();
+    const sections = (display.sections ?? [])
+        .map((section) => {
+        const sectionTitle = section.title.trim();
+        const sectionBody = section.body?.trim();
+        const items = section.items?.map((item) => item.trim()).filter(Boolean);
+        if (!sectionTitle && !sectionBody && (!items || items.length === 0)) {
+            return null;
+        }
+        return {
+            title: sectionTitle,
+            ...(sectionBody ? { body: sectionBody } : {}),
+            ...(items && items.length > 0 ? { items } : {}),
+        };
+    })
+        .filter((section) => Boolean(section));
+    if (!title && !body && sections.length === 0)
+        return undefined;
+    return {
+        kind: display.kind,
+        ...(title ? { title } : {}),
+        ...(body ? { body } : {}),
+        ...(sections.length > 0 ? { sections } : {}),
+    };
+}
+/**
+ * Built-in dialog walk. Deliberately minimal: a select for fixed choices or
+ * approvals, a text input otherwise. Empty and dismissed answers decline —
+ * the user saw the question and chose not to answer it.
+ */
+async function dialogWalk(request, ui, dialog, signal) {
+    if (isApprovalReason(request.reason)) {
+        // ui.confirm() cannot carry per-option labels, so approvals use a select.
+        const choice = await ui.select(localDialogMessage(request), [APPROVE_OPTION, REQUEST_CHANGES_OPTION], dialog);
+        throwIfAborted(signal);
+        if (choice === undefined)
+            return { type: "declined" };
+        if (choice === APPROVE_OPTION)
+            return { type: "approved" };
+        const feedback = await ui.input("Feedback", "Describe the changes you want (optional)", dialog);
+        throwIfAborted(signal);
+        const trimmed = feedback?.trim();
+        return trimmed
+            ? { type: "revision_requested", feedback: trimmed }
+            : { type: "revision_requested" };
+    }
+    if (request.options && request.options.length > 0) {
+        const options = normalizeOptions(request.options);
+        const selectOptions = [...options.map((option) => option.label)];
+        if (!selectOptions.includes(CUSTOM_ANSWER_OPTION)) {
+            selectOptions.push(CUSTOM_ANSWER_OPTION);
+        }
+        const choice = await ui.select(localDialogMessage(request), selectOptions, dialog);
+        throwIfAborted(signal);
+        if (choice === undefined)
+            return { type: "declined" };
+        if (choice === CUSTOM_ANSWER_OPTION) {
+            const text = await ui.input("Answer", "Type your own answer", dialog);
+            throwIfAborted(signal);
+            const trimmed = text?.trim();
+            return trimmed
+                ? { type: "answered", answer: trimmed }
+                : { type: "declined" };
+        }
+        const selected = options.find((option) => option.label === choice);
+        return {
+            type: "answered",
+            answer: selected?.value?.trim() || selected?.label || choice,
+        };
+    }
+    const text = await ui.input(localDialogMessage(request), undefined, dialog);
+    throwIfAborted(signal);
+    const trimmed = text?.trim();
+    return trimmed
+        ? { type: "answered", answer: trimmed }
+        : { type: "declined" };
+}
+function localDialogMessage(request) {
+    const display = request.display;
+    if (!display)
+        return request.message;
+    const lines = [];
+    const title = display.title?.trim();
+    if (title) {
+        lines.push(title);
+    }
+    else {
+        lines.push(request.message);
+    }
+    const body = display.body?.trim();
+    if (body) {
+        lines.push("", body);
+    }
+    for (const section of display.sections ?? []) {
+        const sectionTitle = section.title.trim();
+        const sectionBody = section.body?.trim();
+        const items = section.items?.map((item) => item.trim()).filter(Boolean) ?? [];
+        if (!sectionTitle && !sectionBody && items.length === 0)
+            continue;
+        lines.push("");
+        if (sectionTitle)
+            lines.push(`${sectionTitle}:`);
+        if (sectionBody)
+            lines.push(sectionBody);
+        for (const item of items) {
+            lines.push(`- ${item}`);
+        }
+    }
+    return lines.join("\n");
+}
+function envelopeText(outcome) {
+    switch (outcome.type) {
+        case "answered":
+            return `Answer: ${outcome.answer}`;
+        case "approved":
+            return outcome.feedback
+                ? `Approved. Feedback: ${outcome.feedback}`
+                : "Approved.";
+        case "revision_requested":
+            return outcome.feedback
+                ? `Revision requested. Feedback: ${outcome.feedback}`
+                : "Revision requested.";
+        case "declined":
+            return DECLINED_ENVELOPE;
+        case "awaiting_user":
+            return AWAITING_USER_ENVELOPE;
+        case "unavailable":
+            return UNAVAILABLE_ENVELOPE;
+    }
+}
+function normalizeOptions(options) {
+    return (options ?? []).flatMap((option) => {
+        if (typeof option === "string") {
+            const label = option.trim();
+            return label ? [{ label }] : [];
+        }
+        const label = option.label.trim();
+        if (!label)
+            return [];
+        const value = option.value?.trim();
+        const description = option.description?.trim();
+        return [
+            {
+                label,
+                ...(value ? { value } : {}),
+                ...(description ? { description } : {}),
+            },
+        ];
+    });
+}
+function interruptDetails(request, outcome) {
+    const options = normalizeOptions(request.options);
+    return {
+        interrupt: {
+            reason: request.reason,
+            message: request.message,
+            ...(options.length > 0 ? { options } : {}),
+            ...(request.metadata ? { metadata: request.metadata } : {}),
+            ...(request.display ? { display: request.display } : {}),
+            ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
+            outcome,
+        },
+    };
+}
+function finishedResult(request, outcome) {
+    return {
+        outcome,
+        content: [{ type: "text", text: envelopeText(outcome) }],
+        details: interruptDetails(request, outcome),
+    };
+}
+function awaitingUserResult(request, _toolCallId) {
+    const outcome = { type: "awaiting_user" };
+    return {
+        outcome,
+        content: [{ type: "text", text: envelopeText(outcome) }],
+        details: interruptDetails(request, outcome),
+    };
+}
+//# sourceMappingURL=interactions.js.map

package/dist/interactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions.js","sourceRoot":"","sources":["../src/interactions.ts"],"names":[],"mappings":"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"}

package/dist/mcp-catalog.d.ts

@@ -0,0 +1,8 @@
+import type { McpCatalogServer } from "./mcp-daemon-protocol.js";
+export declare function preloadMcpCatalogs(options?: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}): Promise<McpCatalogServer[]>;
+export declare function clearMcpCatalogPreload(env?: NodeJS.ProcessEnv): void;
+export type { McpCatalogServer } from "./mcp-daemon-protocol.js";
+//# sourceMappingURL=mcp-catalog.d.ts.map

package/dist/mcp-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-catalog.d.ts","sourceRoot":"","sources":["../src/mcp-catalog.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAUjE,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA4CnC;AAED,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAMjF;AAED,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/mcp-catalog.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { ensureMcpDaemon, exchangeMcpDaemon, mcpDaemonEnvironment, } from "./mcp-daemon-client.js";
+const DEFAULT_CATALOG_ATTEMPT_TIMEOUT_MS = 5_000;
+const catalogPreloads = new Map();
+function preloadKey(env) {
+    const { socketPath, fingerprint } = mcpDaemonEnvironment(env);
+    return `${socketPath}\0${fingerprint}`;
+}
+export function preloadMcpCatalogs(options = {}) {
+    const env = options.env ?? process.env;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CATALOG_ATTEMPT_TIMEOUT_MS;
+    const key = preloadKey(env);
+    const existing = catalogPreloads.get(key);
+    if (existing)
+        return existing;
+    const requestCatalogs = async () => {
+        await ensureMcpDaemon(env);
+        const { token, fingerprint } = mcpDaemonEnvironment(env);
+        const id = randomUUID();
+        let catalogs;
+        let daemonError;
+        await exchangeMcpDaemon({ type: "catalog", id, token, fingerprint, timeoutMs }, (envelope, socket) => {
+            if ("catalogs" in envelope) {
+                catalogs = envelope.catalogs;
+                socket.end();
+            }
+            else if ("error" in envelope) {
+                daemonError = envelope.error;
+                socket.end();
+            }
+        }, env);
+        if (daemonError)
+            throw new Error(`MCP daemon: ${daemonError}`);
+        if (!catalogs)
+            throw new Error("MCP daemon returned no catalog result.");
+        const failures = catalogs.filter((server) => server.error);
+        if (failures.length > 0) {
+            throw new Error(`MCP catalog preload failed for ${failures
+                .map((server) => `${server.id}: ${server.error}`)
+                .join("; ")}`);
+        }
+        return catalogs;
+    };
+    const preload = requestCatalogs();
+    catalogPreloads.set(key, preload);
+    void preload.catch(() => {
+        if (catalogPreloads.get(key) === preload)
+            catalogPreloads.delete(key);
+    });
+    return preload;
+}
+export function clearMcpCatalogPreload(env = process.env) {
+    try {
+        catalogPreloads.delete(preloadKey(env));
+    }
+    catch {
+        // An incomplete daemon environment has no preload state to clear.
+    }
+}
+//# sourceMappingURL=mcp-catalog.js.map

package/dist/mcp-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-catalog.js","sourceRoot":"","sources":["../src/mcp-catalog.ts"],"names":[],"mappings":"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"}

package/dist/mcp-cli-core.d.ts

@@ -0,0 +1,79 @@
+import type { Readable, Writable } from "node:stream";
+import { type McpRuntime } from "./mcp-command-context.js";
+import { type McpSessionConfig } from "./mcp.js";
+import type { McpCatalogServer } from "./mcp-daemon-protocol.js";
+export interface ToolSearchMatch {
+    ref: string;
+    server: string;
+    tool: string;
+    description: string;
+    required: string[];
+    score: number;
+    inspect: string;
+    call: string;
+    annotations?: Record<string, unknown>;
+}
+export declare class McpRunUsageError extends Error {
+}
+export declare class McpRunTimeoutError extends Error {
+    readonly outcome = "unknown";
+    constructor(message: string);
+}
+export interface McpRunRemoteErrorDetails extends Record<string, unknown> {
+    code?: string;
+    message: string;
+    retryable?: boolean;
+    action?: string;
+    outcome?: string;
+}
+export declare class McpRunToolError extends Error {
+    readonly server: string;
+    readonly tool: string;
+    readonly kind = "tool_execution";
+    readonly details?: McpRunRemoteErrorDetails;
+    readonly code?: string;
+    readonly retryable?: boolean;
+    readonly action?: string;
+    readonly outcome?: string;
+    constructor(server: string, tool: string, message: string, options?: ErrorOptions & {
+        details?: McpRunRemoteErrorDetails;
+    });
+}
+export declare function mcpListHelpText(): string;
+export declare function mcpCallHelpText(): string;
+export declare function mcpSearchHelpText(): string;
+export declare function mcpRunHelpText(): string;
+export declare function searchMcpTools(session: McpSessionConfig, query: string, opts?: {
+    limit?: number;
+    regex?: boolean;
+}): ToolSearchMatch[];
+export declare function discoverMcpCatalogs(runtime: McpRuntime, timeoutMs: number): Promise<McpCatalogServer[]>;
+export declare function parseListTimeoutMs(args: readonly string[]): number | string;
+export declare function withListTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+export declare function aggregateListExitCode(hadFailure: boolean, args: readonly string[]): number;
+export declare function describeUnknownRunServer(server: string, servers: string[]): string;
+export declare function describeUnavailableRunTool(server: string, tool: string, knownTools: string[]): string;
+export declare function runMcpJavaScript(code: string, opts?: {
+    timeoutMs?: number;
+    callTimeoutMs?: number;
+    maxCalls?: number;
+    maxConcurrentCalls?: number;
+    vars?: Record<string, string>;
+}): Promise<void>;
+export declare function createDelegatedErrorFilter(write: (text: string) => void): {
+    push(chunk: string): void;
+    flush(): void;
+};
+export declare function duplicateCallArgumentKeys(args: string[]): string[];
+export declare function callJsonArgumentError(args: readonly string[]): string | null;
+export declare function malformedCallExpression(args: string[]): string | null;
+export declare function main(args?: string[]): Promise<number>;
+export declare function executeMcpCommand(opts: {
+    args: string[];
+    runtime: McpRuntime;
+    stdin: Readable;
+    stdout: Writable;
+    stderr: Writable;
+    signal: AbortSignal;
+}): Promise<number>;
+//# sourceMappingURL=mcp-cli-core.d.ts.map

package/dist/mcp-cli-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-cli-core.d.ts","sourceRoot":"","sources":["../src/mcp-cli-core.ts"],"names":[],"mappings":"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"}