@introspection-ai/recipes 0.13.0

package/dist/direct-cli.js

@@ -0,0 +1,22 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * True when the current process was launched with the given module as its
+ * entry script. Compares realpaths: package-manager bin shims and
+ * node_modules symlinks (pnpm) hand us a symlinked argv[1] while
+ * import.meta.url is the real path, so naive equality would silently skip
+ * the CLI main. Callers pass their own `import.meta.url`.
+ */
+export function isDirectEntry(moduleUrl, entry = process.argv[1]) {
+    if (!entry)
+        return false;
+    const modulePath = fileURLToPath(moduleUrl);
+    try {
+        return realpathSync(entry) === realpathSync(modulePath);
+    }
+    catch {
+        return resolve(entry) === modulePath;
+    }
+}
+//# sourceMappingURL=direct-cli.js.map

package/dist/direct-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-cli.js","sourceRoot":"","sources":["../src/direct-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAiB,EACjB,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAEvB,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,UAAU,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC;IACvC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./interactions.js";
+export * from "./agent-tool.js";
+export * from "./inspect.js";
+export * from "./mcp-catalog.js";
+export * from "./mcp.js";
+export * from "./pi-extension.js";
+export * from "./recipe-agent.js";
+export * from "./recipe-model.js";
+export * from "./recipe-package.js";
+export * from "./recipe/resolve.js";
+export * from "./run.js";
+export * from "./run-controller.js";
+export * from "./session.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export * from "./interactions.js";
+export * from "./agent-tool.js";
+export * from "./inspect.js";
+export * from "./mcp-catalog.js";
+export * from "./mcp.js";
+export * from "./pi-extension.js";
+export * from "./recipe-agent.js";
+export * from "./recipe-model.js";
+export * from "./recipe-package.js";
+export * from "./recipe/resolve.js";
+export * from "./run.js";
+export * from "./run-controller.js";
+export * from "./session.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/inspect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a recipe requires before it can run, derived entirely from the
+ * package's existing declarations — no new manifest keys. Hosts and adapters
+ * can use this for preflight checks and configuration UIs.
+ */
+export interface RecipeInspection {
+    name: string;
+    version: string;
+    description?: string;
+    agents: string[];
+    providers: string[];
+    credential_env: string[];
+    mcp: {
+        required: string[];
+        optional: string[];
+    };
+    mcp_env: string[];
+    resources: {
+        agents: number;
+        skills: number;
+        extensions: number;
+        prompts: number;
+    };
+}
+export declare function inspectRecipe(recipeDir: string): RecipeInspection;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../src/inspect.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAiFjE"}

package/dist/inspect.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadRecipeAgentDefinitions } from "./recipe-agent.js";
+import { generatedBindingEnvVars, placeholderEnvVars, recipeMcpLocalConfigPath, recipeMcpLocalExamplePath, } from "./recipe-mcp-config.js";
+import { packageResourcePaths, readPiPackageManifest, } from "./recipe-package.js";
+import { expectedProviderEnvVars } from "./provider-env.js";
+export function inspectRecipe(recipeDir) {
+    const dir = resolve(recipeDir);
+    const manifest = readPiPackageManifest(dir);
+    const definitions = loadRecipeAgentDefinitions(dir);
+    const agents = [...new Set([...definitions.values()].map((a) => a.name))];
+    const providers = [
+        ...new Set([...definitions.values()].flatMap((agent) => {
+            const spec = agent.model?.name;
+            const slash = spec?.indexOf("/") ?? -1;
+            return spec && slash > 0 ? [spec.slice(0, slash)] : [];
+        })),
+    ];
+    const credentialEnv = [
+        ...new Set(providers.flatMap((provider) => expectedProviderEnvVars(provider === "gemini" ? "google" : provider))),
+    ].sort();
+    const required = manifest.mcp.servers
+        .filter((server) => server.required)
+        .map((server) => server.id);
+    const optional = manifest.mcp.servers
+        .filter((server) => !server.required)
+        .map((server) => server.id);
+    // Binding env vars: prefer the recipe's own binding file (or its example)
+    // when present; otherwise the generated-binding convention per server.
+    let mcpEnv;
+    const bindingSource = [
+        recipeMcpLocalConfigPath(dir),
+        recipeMcpLocalExamplePath(dir),
+    ].find((path) => existsSync(path));
+    if (bindingSource) {
+        const content = readFileSync(bindingSource, "utf8");
+        const parsed = JSON.parse(content);
+        mcpEnv = [
+            ...new Set([
+                ...placeholderEnvVars(content),
+                ...(parsed.servers ?? []).flatMap((server) => typeof server.oauthClientSecretEnv === "string" &&
+                    server.oauthClientSecretEnv
+                    ? [server.oauthClientSecretEnv]
+                    : []),
+            ]),
+        ].sort();
+    }
+    else {
+        mcpEnv = [
+            ...new Set(manifest.mcp.servers.flatMap((server) => generatedBindingEnvVars(server.id))),
+        ].sort();
+    }
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        ...(manifest.description ? { description: manifest.description } : {}),
+        agents,
+        providers,
+        credential_env: credentialEnv,
+        mcp: { required, optional },
+        mcp_env: mcpEnv,
+        resources: {
+            agents: agents.length,
+            skills: packageResourcePaths(manifest, "skills").length,
+            extensions: packageResourcePaths(manifest, "extensions").length,
+            prompts: packageResourcePaths(manifest, "prompts").length,
+        },
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/inspect.js.map

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

package/dist/interactions.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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 type { ExtensionContext, ExtensionUIContext, ExtensionUIDialogOptions } from "@earendil-works/pi-coding-agent";
+/** Well-known `reason` for a question the model needs answered. */
+export declare const ASK_USER_REASON_INPUT_REQUIRED = "input_required";
+/** Well-known `reason` for an approve/request-changes decision. */
+export declare const ASK_USER_REASON_CONFIRMATION = "confirmation";
+/** Well-known `reason` for a decision bound to a specific tool call. */
+export declare 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 declare const DEFAULT_RPC_DIALOG_TIMEOUT_MS = 120000;
+/** Optional structured rendering hints for hosts with richer UI. */
+export interface AskUserDisplay {
+    /** Renderer kind, e.g. `search_proposal`. */
+    kind: string;
+    /** Short title for local dialogs and rich cards. */
+    title?: string;
+    /** Main body copy. Plain text or markdown-style text. */
+    body?: string;
+    /** Optional grouped content for clients that render rows or sections. */
+    sections?: Array<{
+        title: string;
+        body?: string;
+        items?: string[];
+    }>;
+}
+/** A selectable answer option. `value` is what the tool receives. */
+export interface AskUserOption {
+    label: string;
+    value?: string;
+    description?: string;
+}
+/** What the recipe tool wants from the user. */
+export interface AskUserRequest {
+    /**
+     * Why the run needs the user. Open string; well-known values are
+     * `input_required` (a question) and `confirmation` (approve / request
+     * changes). Unknown reasons follow the question flow.
+     */
+    reason: string;
+    /** The human-readable prompt shown to the user. */
+    message: string;
+    /** Optional choices for a question. Hosts may also allow a custom answer. */
+    options?: readonly (string | AskUserOption)[];
+    /**
+     * Native renderer or tool hints for hosts that can render richer UI.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Structured display copy. Local pi dialogs format this for readability;
+     * remote hosts can adapt it into their own UI.
+     */
+    display?: AskUserDisplay;
+    /** Optional ISO-8601 instant after which a host may auto-decline. */
+    expiresAt?: string;
+}
+export interface AskUserQuestionRequest {
+    /** The concise question shown to the user. */
+    question: string;
+    /** Optional short UI heading for hosts that render one. */
+    header?: string;
+    /** Optional answer suggestions. Hosts may also allow a custom answer. */
+    options?: readonly (string | AskUserOption)[];
+    /** Additional renderer or tool hints. */
+    metadata?: Record<string, unknown>;
+    /** Optional structured display copy. */
+    display?: AskUserDisplay;
+    /** Optional ISO-8601 instant after which a host may auto-decline. */
+    expiresAt?: string;
+}
+export interface AskUserApprovalRequest {
+    /** Short renderer kind, e.g. `plan_search`; defaults to `approval`. */
+    kind?: string;
+    /** Concise approval prompt. Defaults to `Approve <title>?` when possible. */
+    message?: string;
+    /** Approval card title for local and remote UI. */
+    title?: string;
+    /** Main approval card body. Plain text or markdown-style text. */
+    body?: string;
+    /** Optional grouped content for clients that render rows or sections. */
+    sections?: AskUserDisplay["sections"];
+    /** Additional renderer or tool hints. */
+    metadata?: Record<string, unknown>;
+    /** Optional ISO-8601 instant after which a host may auto-decline. */
+    expiresAt?: string;
+}
+/** Per-call plumbing from the owning tool's `execute()`. */
+export interface AskUserOptions {
+    /** The executing tool call id (first `execute()` argument). */
+    toolCallId: string;
+    /** The extension context (last `execute()` argument). */
+    ctx: ExtensionContext;
+    /**
+     * The tool's own abort signal (third `execute()` argument) — NOT
+     * `ctx.signal`, which may already be undefined while the tool settles.
+     * Threaded into every dialog so an aborted turn dismisses them.
+     */
+    signal: AbortSignal | undefined;
+    /**
+     * Optional custom interactive walk replacing the built-in dialogs (a pure
+     * TUI/RPC enhancement — the contract is unchanged). Return an outcome, or
+     * undefined to fall through to the built-in walk.
+     */
+    interactive?: (ui: ExtensionUIContext, dialog: ExtensionUIDialogOptions) => Promise<AskUserOutcome | undefined>;
+    /** Dialog timeout override in milliseconds (defaults: TUI none, RPC 120s). */
+    timeoutMs?: number;
+    /** Environment override for tests. */
+    env?: NodeJS.ProcessEnv;
+}
+/** How the interaction settled. */
+export type AskUserOutcome = {
+    type: "answered";
+    answer: string;
+} | {
+    type: "approved";
+    feedback?: string;
+} | {
+    type: "revision_requested";
+    feedback?: string;
+} | {
+    type: "declined";
+}
+/** Interrupt emitted — the host pauses the run and rewrites this result. */
+ | {
+    type: "awaiting_user";
+}
+/** No interaction channel — the model should ask in plain chat. */
+ | {
+    type: "unavailable";
+};
+/** The Recipes interrupt request stored in Pi's arbitrary details field. */
+export interface AskUserInterrupt {
+    reason: string;
+    message: string;
+    options?: AskUserOption[];
+    metadata?: Record<string, unknown>;
+    display?: AskUserDisplay;
+    expiresAt?: string;
+    outcome: AskUserOutcome;
+}
+/** Structured details attached to every askUser tool result. */
+export interface AskUserDetails {
+    interrupt: AskUserInterrupt;
+}
+/**
+ * A finished tool result: return it (or spread it) from the owning tool's
+ * `execute()`. The envelope text in `content` is what the model sees.
+ */
+export interface AskUserResult {
+    outcome: AskUserOutcome;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: AskUserDetails;
+}
+/**
+ * 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 declare function autoResolveInteractions<T>(fn: () => Promise<T>): Promise<T>;
+/** @deprecated Use `autoResolveInteractions()` for the explicit behavior. */
+export declare function suppressInterruptResume<T>(fn: () => Promise<T>): Promise<T>;
+/** Ask the user, resolving the best available interaction channel. */
+export declare function askUser(request: AskUserRequest, opts: AskUserOptions): Promise<AskUserResult>;
+/** Ask a blocking clarification question without hand-authoring interrupt details. */
+export declare function askUserQuestion(request: AskUserQuestionRequest, opts: AskUserOptions): Promise<AskUserResult>;
+/** Request approval without hand-authoring interrupt details or display data. */
+export declare function askUserApproval(request: AskUserApprovalRequest, opts: AskUserOptions): Promise<AskUserResult>;
+//# sourceMappingURL=interactions.d.ts.map

package/dist/interactions.d.ts.map

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