larkin 0.2.70

package/dist/runtime/codex-model-catalog.cjs

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverCodexModelCatalog = discoverCodexModelCatalog;
+const node_child_process_1 = require("node:child_process");
+const SAFE_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const REASONING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
+function cleanLabel(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    return value.replace(/[\u0000-\u001f\u007f]+/g, "").replace(/\s+/g, " ").trim().slice(0, 120) || fallback;
+}
+async function runCodexAppServer(call) {
+    return await new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(call.command || "codex", call.args, {
+            ...(call.cwd ? { cwd: call.cwd } : {}), env: call.env, stdio: ["pipe", "pipe", "pipe"],
+        });
+        let settled = false;
+        let stdout = "";
+        let bytes = 0;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGTERM");
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => finish(new Error("Codex model catalog timed out")), call.timeout);
+        timer.unref?.();
+        child.on("error", () => finish(new Error("Codex model catalog command failed")));
+        child.on("exit", () => finish(new Error("Codex model catalog app-server exited before response")));
+        child.stderr.resume();
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > call.maxBuffer)
+                return finish(new Error("Codex model catalog response exceeded limit"));
+            stdout += chunk.toString("utf8");
+            for (;;) {
+                const newline = stdout.indexOf("\n");
+                if (newline < 0)
+                    break;
+                const line = stdout.slice(0, newline);
+                stdout = stdout.slice(newline + 1);
+                try {
+                    const message = JSON.parse(line);
+                    if (message.id === call.request.id) {
+                        if (message.error)
+                            return finish(new Error("Codex model catalog request failed"));
+                        return finish(undefined, message.result);
+                    }
+                }
+                catch { /* app-server protocol is newline-delimited JSON; ignore non-response noise */ }
+            }
+        });
+        child.stdin.write(`${JSON.stringify({ id: "larkin-initialize", method: "initialize", params: { clientInfo: { name: "larkin", title: "Larkin", version: "0" } } })}\n`);
+        child.stdin.write(`${JSON.stringify({ method: "initialized", params: {} })}\n`);
+        child.stdin.write(`${JSON.stringify(call.request)}\n`);
+    });
+}
+function parseCatalog(value) {
+    const rows = value?.data;
+    if (!Array.isArray(rows) || rows.length === 0 || rows.length > 512)
+        throw new Error("Codex model catalog has an invalid model list");
+    const seen = new Set();
+    let effectiveModel = "";
+    const models = rows.flatMap((row) => {
+        if (!row || typeof row !== "object" || Array.isArray(row))
+            return [];
+        const item = row;
+        const id = typeof item.id === "string" ? item.id : "";
+        if (item.hidden === true || !SAFE_MODEL_ID.test(id) || seen.has(id))
+            return [];
+        seen.add(id);
+        if (item.isDefault === true)
+            effectiveModel = typeof item.model === "string" && SAFE_MODEL_ID.test(item.model) ? item.model : id;
+        const levels = Array.isArray(item.supportedReasoningEfforts)
+            ? [...new Set(item.supportedReasoningEfforts.flatMap((level) => {
+                    const effort = level?.reasoningEffort
+                        ?? level?.effort;
+                    return typeof effort === "string" && REASONING_LEVELS.has(effort) ? [effort] : [];
+                }))]
+            : [];
+        const defaultReasoningEffort = typeof item.defaultReasoningEffort === "string" && levels.includes(item.defaultReasoningEffort)
+            ? item.defaultReasoningEffort : undefined;
+        return [{ id, label: cleanLabel(item.displayName, id), supportedReasoningEfforts: levels,
+                ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}), verified: "codex-cli-visible" }];
+    });
+    if (!models.length || !effectiveModel)
+        throw new Error("Codex model catalog has no visible local default");
+    return { models, effectiveModel };
+}
+async function discoverCodexModelCatalog(options = {}) {
+    const execute = options.runCodexAppServer ?? runCodexAppServer;
+    const request = { id: "larkin-model-list", method: "model/list", params: { limit: 100, includeHidden: false } };
+    try {
+        return parseCatalog(await execute({ args: ["app-server", "--stdio"], ...(options.command ? { command: options.command } : {}), ...(options.cwd ? { cwd: options.cwd } : {}),
+            env: { ...process.env, ...options.env, NO_COLOR: "1" }, maxBuffer: 1024 * 1024, request, timeout: 15_000 }));
+    }
+    catch (error) {
+        if (error instanceof Error && /Codex model catalog/.test(error.message))
+            throw error;
+        throw new Error("Codex model catalog unavailable");
+    }
+}

package/dist/runtime/codex-model-catalog.mjs

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+const SAFE_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const REASONING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
+function cleanLabel(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    return value.replace(/[\u0000-\u001f\u007f]+/g, "").replace(/\s+/g, " ").trim().slice(0, 120) || fallback;
+}
+async function runCodexAppServer(call) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(call.command || "codex", call.args, {
+            ...(call.cwd ? { cwd: call.cwd } : {}), env: call.env, stdio: ["pipe", "pipe", "pipe"],
+        });
+        let settled = false;
+        let stdout = "";
+        let bytes = 0;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGTERM");
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => finish(new Error("Codex model catalog timed out")), call.timeout);
+        timer.unref?.();
+        child.on("error", () => finish(new Error("Codex model catalog command failed")));
+        child.on("exit", () => finish(new Error("Codex model catalog app-server exited before response")));
+        child.stderr.resume();
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > call.maxBuffer)
+                return finish(new Error("Codex model catalog response exceeded limit"));
+            stdout += chunk.toString("utf8");
+            for (;;) {
+                const newline = stdout.indexOf("\n");
+                if (newline < 0)
+                    break;
+                const line = stdout.slice(0, newline);
+                stdout = stdout.slice(newline + 1);
+                try {
+                    const message = JSON.parse(line);
+                    if (message.id === call.request.id) {
+                        if (message.error)
+                            return finish(new Error("Codex model catalog request failed"));
+                        return finish(undefined, message.result);
+                    }
+                }
+                catch { /* app-server protocol is newline-delimited JSON; ignore non-response noise */ }
+            }
+        });
+        child.stdin.write(`${JSON.stringify({ id: "larkin-initialize", method: "initialize", params: { clientInfo: { name: "larkin", title: "Larkin", version: "0" } } })}\n`);
+        child.stdin.write(`${JSON.stringify({ method: "initialized", params: {} })}\n`);
+        child.stdin.write(`${JSON.stringify(call.request)}\n`);
+    });
+}
+function parseCatalog(value) {
+    const rows = value?.data;
+    if (!Array.isArray(rows) || rows.length === 0 || rows.length > 512)
+        throw new Error("Codex model catalog has an invalid model list");
+    const seen = new Set();
+    let effectiveModel = "";
+    const models = rows.flatMap((row) => {
+        if (!row || typeof row !== "object" || Array.isArray(row))
+            return [];
+        const item = row;
+        const id = typeof item.id === "string" ? item.id : "";
+        if (item.hidden === true || !SAFE_MODEL_ID.test(id) || seen.has(id))
+            return [];
+        seen.add(id);
+        if (item.isDefault === true)
+            effectiveModel = typeof item.model === "string" && SAFE_MODEL_ID.test(item.model) ? item.model : id;
+        const levels = Array.isArray(item.supportedReasoningEfforts)
+            ? [...new Set(item.supportedReasoningEfforts.flatMap((level) => {
+                    const effort = level?.reasoningEffort
+                        ?? level?.effort;
+                    return typeof effort === "string" && REASONING_LEVELS.has(effort) ? [effort] : [];
+                }))]
+            : [];
+        const defaultReasoningEffort = typeof item.defaultReasoningEffort === "string" && levels.includes(item.defaultReasoningEffort)
+            ? item.defaultReasoningEffort : undefined;
+        return [{ id, label: cleanLabel(item.displayName, id), supportedReasoningEfforts: levels,
+                ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}), verified: "codex-cli-visible" }];
+    });
+    if (!models.length || !effectiveModel)
+        throw new Error("Codex model catalog has no visible local default");
+    return { models, effectiveModel };
+}
+export async function discoverCodexModelCatalog(options = {}) {
+    const execute = options.runCodexAppServer ?? runCodexAppServer;
+    const request = { id: "larkin-model-list", method: "model/list", params: { limit: 100, includeHidden: false } };
+    try {
+        return parseCatalog(await execute({ args: ["app-server", "--stdio"], ...(options.command ? { command: options.command } : {}), ...(options.cwd ? { cwd: options.cwd } : {}),
+            env: { ...process.env, ...options.env, NO_COLOR: "1" }, maxBuffer: 1024 * 1024, request, timeout: 15_000 }));
+    }
+    catch (error) {
+        if (error instanceof Error && /Codex model catalog/.test(error.message))
+            throw error;
+        throw new Error("Codex model catalog unavailable");
+    }
+}

package/dist/runtime/pi-bash-timeout-extension.mjs

@@ -0,0 +1,60 @@
+import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
+/**
+ * pi bash 工具超时护栏扩展。
+ *
+ * 由 larkin 通过 `pi --extension/-e <bundle>` 注入，覆盖内置 `bash` 工具：
+ * - 无论模型是否传 `timeout`，都强制收窄到 <= MAX_BASH_SECONDS（默认 60s），
+ *   避免单个 bash 调用无限期占住整个 agent 回合（issue #55）。
+ * - 超时时 pi 会杀掉整个进程树（不残留卡死子进程，issue #56 的进程堆积），
+ *   并在返回的错误里明确提示：长任务必须改用后台 subagent
+ *   （Agent(run_in_background: true)，来自 pi-subagents 扩展）。
+ *
+ * 这是 pi 扩展，运行在 pi 进程内部；larkin 主进程不加载本模块（只通过
+ * build.mjs 单独 bundle 成单文件后注入）。pi-* 保持 external。
+ */
+/** 前台 bash 的硬性上限（秒）。issue #55 建议默认 60s。 */
+const MAX_BASH_SECONDS = 60;
+/** 解析生效超时：默认 60，允许用 LARKIN_PI_BASH_TIMEOUT_SECONDS 调低（用于快速 eval），硬上限 60。 */
+function effectiveBashTimeout() {
+    const raw = Number.parseInt(process.env.LARKIN_PI_BASH_TIMEOUT_SECONDS || "", 10);
+    if (Number.isInteger(raw) && raw > 0)
+        return Math.min(raw, MAX_BASH_SECONDS);
+    return MAX_BASH_SECONDS;
+}
+export default function (pi) {
+    const cwd = process.cwd();
+    // Built-in bash tool definition (keeps renderCall/renderResult/system-prompt metadata).
+    const builtin = createBashToolDefinition(cwd);
+    const MAX = effectiveBashTimeout();
+    const SUBAGENT_GUIDANCE = `This command exceeded the ${MAX}s foreground hard limit. ` +
+        "Long-running or deploy-style work MUST run in a background subagent instead: " +
+        "call Agent({ prompt, description, run_in_background: true }), report the returned agent id, and end the turn; " +
+        "a completion notification arrives automatically. " +
+        "Do NOT retry this command in the foreground, and do not use nohup / '&' / disown shell background jobs " +
+        "(they bypass subagent isolation and die with this run).";
+    pi.registerTool({
+        ...builtin,
+        name: "bash",
+        label: "bash",
+        description: builtin.description,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const requested = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout : MAX;
+            // 模型显式设置 timeout > 上限 → 它已知这是长任务。立即报错引导改用后台 subagent，
+            // 不真的跑（省掉白等 + 避免产生部分副作用）。
+            if (requested > MAX) {
+                throw new Error(`timeout:${requested} exceeds the ${MAX}s foreground hard limit. ${SUBAGENT_GUIDANCE}`);
+            }
+            const timeout = Math.min(requested, MAX);
+            try {
+                return await builtin.execute(toolCallId, { ...params, timeout }, signal, onUpdate, ctx);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/timed out after/i.test(message)) {
+                    throw new Error(`${message}\n\n${SUBAGENT_GUIDANCE}`);
+                }
+                throw error;
+            }
+        },
+    });
+}

package/dist/runtime/pi-bash-timeout-injection.mjs

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_PI_VERSION } from "./pi-provider-config.mjs";
+import { parsePiVersion, piVersionSupportsSubagents, probeExternalPiVersion } from "./pi-subagent-injection.mjs";
+/**
+ * pi-bash-timeout 扩展注入（bash 60s 超时护栏，issue #55/#56）。
+ *
+ * 分发：构建期把 src/runtime/pi-bash-timeout-extension.ts bundle 成单文件
+ * `dist/runtime/pi-bash-timeout.bundle.js`（pi-* 包 external），运行时通过
+ * `pi --extension/-e` 显式注入 —— builtin 与 external（用户 pi CLI）走同一
+ * 路径，不碰用户 ~/.pi 配置。与 pi-subagents 共享同一个 pi 版本门槛。
+ */
+/** 把 embedded bundle 落盘到 <configDir>/providers/pi/extensions/（0700/0600）。无 embedded 资产返回 null。 */
+export function materializeEmbeddedPiBashTimeoutBundle(configDir) {
+    const embedded = globalThis.__LARKIN_EMBEDDED_PI_BASH_TIMEOUT_BUNDLE__;
+    if (!embedded || !configDir)
+        return null;
+    const dir = path.join(path.resolve(configDir), "providers", "pi", "extensions");
+    const target = path.join(dir, "pi-bash-timeout.bundle.js");
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.chmodSync(dir, 0o700);
+        if (!fs.existsSync(target) || fs.readFileSync(target, "utf8") !== embedded) {
+            const temporary = `${target}.${process.pid}.tmp`;
+            fs.writeFileSync(temporary, embedded, { mode: 0o600, flag: "wx" });
+            fs.renameSync(temporary, target);
+            fs.chmodSync(target, 0o600);
+        }
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
+/** 构建产物单文件路径；standalone 二进制回退到 embedded 资产落盘。 */
+export function bundledPiBashTimeoutExtensionPath(configDir) {
+    try {
+        const url = new URL("./pi-bash-timeout.bundle.js", import.meta.url);
+        const resolved = fileURLToPath(url);
+        if (fs.existsSync(resolved))
+            return resolved;
+    }
+    catch {
+        /* fall through to embedded */
+    }
+    return materializeEmbeddedPiBashTimeoutBundle(configDir);
+}
+/**
+ * 注入决策：builtin 恒注入（内嵌 pi 版本固定）；external 需探测版本（与
+ * pi-subagents 同门槛 >= 0.80.0，保证 createBashToolDefinition 可用）。
+ * 返回 `-e` 参数值，或 null（产物缺失或版本不达标）。
+ */
+export function resolvePiBashTimeoutExtensionArg(input, probeVersion = () => probeExternalPiVersion(input.piCommand, input.env), resolveBundle = () => bundledPiBashTimeoutExtensionPath(input.env.LARKIN_CONFIG_DIR)) {
+    const bundle = resolveBundle();
+    if (!bundle)
+        return null;
+    const version = input.distribution === "builtin" ? parsePiVersion(BUNDLED_PI_VERSION) : probeVersion();
+    return piVersionSupportsSubagents(version) ? bundle : null;
+}

package/dist/runtime/pi-bash-timeout.bundle.js

@@ -0,0 +1,43 @@
+// @bun
+// src/runtime/pi-bash-timeout-extension.ts
+import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
+var MAX_BASH_SECONDS = 60;
+function effectiveBashTimeout() {
+  const raw = Number.parseInt(process.env.LARKIN_PI_BASH_TIMEOUT_SECONDS || "", 10);
+  if (Number.isInteger(raw) && raw > 0)
+    return Math.min(raw, MAX_BASH_SECONDS);
+  return MAX_BASH_SECONDS;
+}
+function pi_bash_timeout_extension_default(pi) {
+  const cwd = process.cwd();
+  const builtin = createBashToolDefinition(cwd);
+  const MAX = effectiveBashTimeout();
+  const SUBAGENT_GUIDANCE = `This command exceeded the ${MAX}s foreground hard limit. ` + "Long-running or deploy-style work MUST run in a background subagent instead: " + "call Agent({ prompt, description, run_in_background: true }), report the returned agent id, and end the turn; " + "a completion notification arrives automatically. " + "Do NOT retry this command in the foreground, and do not use nohup / '&' / disown shell background jobs " + "(they bypass subagent isolation and die with this run).";
+  pi.registerTool({
+    ...builtin,
+    name: "bash",
+    label: "bash",
+    description: builtin.description,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const requested = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout : MAX;
+      if (requested > MAX) {
+        throw new Error(`timeout:${requested} exceeds the ${MAX}s foreground hard limit. ${SUBAGENT_GUIDANCE}`);
+      }
+      const timeout = Math.min(requested, MAX);
+      try {
+        return await builtin.execute(toolCallId, { ...params, timeout }, signal, onUpdate, ctx);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/timed out after/i.test(message)) {
+          throw new Error(`${message}
+
+${SUBAGENT_GUIDANCE}`);
+        }
+        throw error;
+      }
+    }
+  });
+}
+export {
+  pi_bash_timeout_extension_default as default
+};

package/dist/runtime/pi-model-catalog.cjs

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PI_THINKING_LEVELS = void 0;
+exports.piModelId = piModelId;
+exports.supportedPiThinkingLevels = supportedPiThinkingLevels;
+exports.isPiThinkingLevel = isPiThinkingLevel;
+exports.findExactPiModel = findExactPiModel;
+exports.discoverPiModelCatalog = discoverPiModelCatalog;
+const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
+const pi_rpc_client_js_1 = require("./pi-rpc-client.cjs");
+const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
+exports.PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+function piModelId(model) { return `${model.provider}/${model.id}`; }
+function supportedPiThinkingLevels(model) {
+    if (!model.reasoning)
+        return ["off"];
+    return exports.PI_THINKING_LEVELS.filter((level) => {
+        const mapped = model.thinkingLevelMap?.[level];
+        if (mapped === null)
+            return false;
+        return level !== "xhigh" && level !== "max" ? true : mapped !== undefined;
+    });
+}
+function isPiThinkingLevel(value) {
+    return typeof value === "string" && exports.PI_THINKING_LEVELS.includes(value);
+}
+function findExactPiModel(reference, models) {
+    if (!reference || reference === "default" || !reference.includes("/"))
+        return undefined;
+    return models.find((model) => piModelId(model) === reference);
+}
+/** Discover only through Pi's structured RPC protocol; no table parsing or static fallback. */
+async function discoverPiModelCatalog(options) {
+    const spawn = options.spawn ?? ((command, args, spawnOptions) => (0, node_child_process_1.spawn)(command, [...args], spawnOptions));
+    const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
+    const child = spawn(command, ["--mode", "rpc", "--no-session"], {
+        cwd: options.cwd,
+        env: { ...process.env, ...options.env, ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}), NO_COLOR: "1" },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const client = new pi_rpc_client_js_1.PiRpcClient(child, { requestTimeoutMs: options.timeoutMs ?? 10_000 });
+    try {
+        const [availableResponse, state] = await Promise.all([
+            client.request("get_available_models"),
+            client.request("get_state"),
+        ]);
+        const available = [...(availableResponse?.models ?? [])].sort((left, right) => piModelId(left).localeCompare(piModelId(right)));
+        if (!available.length)
+            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
+        const effectiveModel = state.model ? piModelId(state.model) : null;
+        if (!effectiveModel || !available.some((model) => piModelId(model) === effectiveModel)) {
+            throw new Error(`Pi official default resolution returned an unavailable model (${effectiveModel || "none"}); refusing implicit fallback`);
+        }
+        const effectiveThinkingLevel = isPiThinkingLevel(state.thinkingLevel) ? state.thinkingLevel : "off";
+        return {
+            models: available.map((model) => {
+                const supportedReasoningEfforts = supportedPiThinkingLevels(model);
+                return {
+                    id: piModelId(model),
+                    label: `${model.name || model.id} · ${model.provider}`,
+                    ...(Number.isFinite(model.contextWindow) && Number(model.contextWindow) > 0 ? { contextWindow: Number(model.contextWindow) } : {}),
+                    supportedReasoningEfforts,
+                    ...(piModelId(model) === effectiveModel && supportedReasoningEfforts.includes(effectiveThinkingLevel)
+                        ? { defaultReasoningEffort: effectiveThinkingLevel } : {}),
+                    verified: "launchable",
+                };
+            }),
+            effectiveModel,
+            effectiveThinkingLevel,
+            defaultSource: "settings",
+            diagnostics: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof runtime_readiness_js_1.RuntimePrerequisiteError)
+            throw error;
+        throw new runtime_readiness_js_1.RuntimePrerequisiteError((0, runtime_readiness_js_1.classifyRuntimePrerequisite)("pi", error, command));
+    }
+    finally {
+        await client.close();
+    }
+}

package/dist/runtime/pi-model-catalog.mjs

@@ -0,0 +1,75 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import * as path from "node:path";
+import { PiRpcClient } from "./pi-rpc-client.mjs";
+import { classifyRuntimePrerequisite, RuntimePrerequisiteError } from "./runtime-readiness.mjs";
+export const PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export function piModelId(model) { return `${model.provider}/${model.id}`; }
+export function supportedPiThinkingLevels(model) {
+    if (!model.reasoning)
+        return ["off"];
+    return PI_THINKING_LEVELS.filter((level) => {
+        const mapped = model.thinkingLevelMap?.[level];
+        if (mapped === null)
+            return false;
+        return level !== "xhigh" && level !== "max" ? true : mapped !== undefined;
+    });
+}
+export function isPiThinkingLevel(value) {
+    return typeof value === "string" && PI_THINKING_LEVELS.includes(value);
+}
+export function findExactPiModel(reference, models) {
+    if (!reference || reference === "default" || !reference.includes("/"))
+        return undefined;
+    return models.find((model) => piModelId(model) === reference);
+}
+/** Discover only through Pi's structured RPC protocol; no table parsing or static fallback. */
+export async function discoverPiModelCatalog(options) {
+    const spawn = options.spawn ?? ((command, args, spawnOptions) => nodeSpawn(command, [...args], spawnOptions));
+    const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
+    const child = spawn(command, ["--mode", "rpc", "--no-session"], {
+        cwd: options.cwd,
+        env: { ...process.env, ...options.env, ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}), NO_COLOR: "1" },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const client = new PiRpcClient(child, { requestTimeoutMs: options.timeoutMs ?? 10_000 });
+    try {
+        const [availableResponse, state] = await Promise.all([
+            client.request("get_available_models"),
+            client.request("get_state"),
+        ]);
+        const available = [...(availableResponse?.models ?? [])].sort((left, right) => piModelId(left).localeCompare(piModelId(right)));
+        if (!available.length)
+            throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
+        const effectiveModel = state.model ? piModelId(state.model) : null;
+        if (!effectiveModel || !available.some((model) => piModelId(model) === effectiveModel)) {
+            throw new Error(`Pi official default resolution returned an unavailable model (${effectiveModel || "none"}); refusing implicit fallback`);
+        }
+        const effectiveThinkingLevel = isPiThinkingLevel(state.thinkingLevel) ? state.thinkingLevel : "off";
+        return {
+            models: available.map((model) => {
+                const supportedReasoningEfforts = supportedPiThinkingLevels(model);
+                return {
+                    id: piModelId(model),
+                    label: `${model.name || model.id} · ${model.provider}`,
+                    ...(Number.isFinite(model.contextWindow) && Number(model.contextWindow) > 0 ? { contextWindow: Number(model.contextWindow) } : {}),
+                    supportedReasoningEfforts,
+                    ...(piModelId(model) === effectiveModel && supportedReasoningEfforts.includes(effectiveThinkingLevel)
+                        ? { defaultReasoningEffort: effectiveThinkingLevel } : {}),
+                    verified: "launchable",
+                };
+            }),
+            effectiveModel,
+            effectiveThinkingLevel,
+            defaultSource: "settings",
+            diagnostics: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof RuntimePrerequisiteError)
+            throw error;
+        throw new RuntimePrerequisiteError(classifyRuntimePrerequisite("pi", error, command));
+    }
+    finally {
+        await client.close();
+    }
+}