larkin 0.2.70

package/dist/runtime/pi-rpc-client.cjs

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PiRpcClient = void 0;
+/** A strict, bounded LF-delimited client for Pi's public RPC protocol. */
+class PiRpcClient {
+    process;
+    pending = new Map();
+    eventListeners = new Set();
+    failureListeners = new Set();
+    requestTimeoutMs;
+    inputTimeoutMs;
+    inputProgressTimeoutMs;
+    inputMaxTimeoutMs;
+    maxFrameBytes;
+    maxStderrBytes;
+    shutdownGraceMs;
+    stdoutBuffer = Buffer.alloc(0);
+    stderrBuffer = Buffer.alloc(0);
+    exited = false;
+    nextId = 0;
+    failed = null;
+    shutdownPromise = null;
+    constructor(process, options = {}) {
+        this.process = process;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
+        this.inputTimeoutMs = options.inputTimeoutMs ?? 120_000;
+        this.inputProgressTimeoutMs = options.inputProgressTimeoutMs ?? 300_000;
+        this.inputMaxTimeoutMs = options.inputMaxTimeoutMs ?? 600_000;
+        if (this.requestTimeoutMs <= 0 || this.inputTimeoutMs <= 0 || this.inputProgressTimeoutMs <= 0
+            || this.inputMaxTimeoutMs < this.inputTimeoutMs)
+            throw new Error("Pi RPC timeout options are invalid");
+        this.maxFrameBytes = options.maxFrameBytes ?? 1024 * 1024;
+        this.maxStderrBytes = options.maxStderrBytes ?? 64 * 1024;
+        this.shutdownGraceMs = options.shutdownGraceMs ?? 2_000;
+        process.stdout?.on("data", (chunk) => this.consume(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))));
+        process.stdout?.on("end", () => {
+            if (this.stdoutBuffer.length)
+                this.protocolFailure("unterminated final frame");
+        });
+        process.stderr?.on("data", (chunk) => {
+            if (this.stderrBuffer.length >= this.maxStderrBytes)
+                return;
+            const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            this.stderrBuffer = Buffer.concat([this.stderrBuffer, value.subarray(0, this.maxStderrBytes - this.stderrBuffer.length)]);
+        });
+        process.once("error", (error) => this.fail(new Error(`Pi RPC process failed: ${error.message}`), true));
+        process.once("exit", (code, signal) => {
+            this.exited = true;
+            const stderr = this.stderrBuffer.toString("utf8").trim().slice(0, 2_000);
+            this.fail(new Error(`Pi RPC process exited (${code ?? signal ?? "unknown"})${stderr ? `: ${stderr}` : ""}`), false);
+        });
+    }
+    subscribe(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    subscribeFailure(listener) {
+        this.failureListeners.add(listener);
+        if (this.failed)
+            queueMicrotask(() => listener(this.failed));
+        return () => this.failureListeners.delete(listener);
+    }
+    request(command, fields = {}) {
+        if (this.failed)
+            return Promise.reject(this.failed);
+        const id = `larkin-${++this.nextId}`;
+        return new Promise((resolve, reject) => {
+            const startedAt = Date.now();
+            const input = isInputCommand(command);
+            const pending = {
+                command, startedAt,
+                ...(input ? { absoluteDeadlineAt: startedAt + this.inputMaxTimeoutMs } : {}),
+                resolve: resolve, reject,
+            };
+            this.pending.set(id, pending);
+            this.armTimeout(id, pending, input ? this.inputTimeoutMs : this.requestTimeoutMs);
+            try {
+                if (!this.process.stdin || this.process.stdin.destroyed)
+                    throw new Error("stdin is unavailable");
+                this.process.stdin.write(`${JSON.stringify({ id, type: command, ...fields })}\n`, (error) => {
+                    if (error)
+                        this.fail(new Error(`Pi RPC ${command} write failed: ${error.message}`), true);
+                });
+            }
+            catch (error) {
+                this.fail(new Error(`Pi RPC ${command} write failed: ${error instanceof Error ? error.message : String(error)}`), true);
+            }
+        });
+    }
+    notify(command, fields = {}) {
+        if (this.failed || !this.process.stdin || this.process.stdin.destroyed)
+            return;
+        this.process.stdin.write(`${JSON.stringify({ type: command, ...fields })}\n`);
+    }
+    close() {
+        if (!this.failed)
+            this.fail(new Error("Pi RPC client closed"), true);
+        return this.beginShutdown();
+    }
+    consume(chunk) {
+        if (this.failed)
+            return;
+        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        while (true) {
+            const newline = this.stdoutBuffer.indexOf(0x0a);
+            if (newline < 0) {
+                if (this.stdoutBuffer.length > this.maxFrameBytes)
+                    this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
+                return;
+            }
+            if (newline > this.maxFrameBytes) {
+                this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
+                return;
+            }
+            let frame = this.stdoutBuffer.subarray(0, newline);
+            this.stdoutBuffer = this.stdoutBuffer.subarray(newline + 1);
+            if (frame.at(-1) === 0x0d)
+                frame = frame.subarray(0, -1);
+            if (!frame.length) {
+                this.protocolFailure("empty frame");
+                return;
+            }
+            let message;
+            try {
+                const parsed = JSON.parse(frame.toString("utf8"));
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                    throw new Error("frame is not an object");
+                message = parsed;
+            }
+            catch (error) {
+                this.protocolFailure(`malformed JSON: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+            this.dispatch(message);
+            if (this.failed)
+                return;
+        }
+    }
+    dispatch(message) {
+        if (message.type === "response" && typeof message.id === "string") {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                this.protocolFailure(`unexpected response id ${message.id}`);
+                return;
+            }
+            this.pending.delete(message.id);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            if (message.command !== pending.command) {
+                pending.reject(new Error(`Pi RPC protocol error: response command ${String(message.command)} does not match ${pending.command}`));
+                this.fail(new Error("Pi RPC protocol error: mismatched response command"), true);
+            }
+            else if (message.success === true)
+                pending.resolve(message.data);
+            else
+                pending.reject(new Error(`Pi RPC ${pending.command} failed: ${String(message.error || "unknown error")}`));
+            return;
+        }
+        if (isInputProgress(message))
+            this.refreshInputDeadlines(message.type);
+        for (const listener of this.eventListeners)
+            listener(message);
+    }
+    refreshInputDeadlines(eventType) {
+        const graceMs = eventType === "compaction_start" || eventType.startsWith("summarization_retry_")
+            || eventType === "auto_retry_start" ? this.inputProgressTimeoutMs : this.inputTimeoutMs;
+        for (const [id, pending] of this.pending) {
+            if (!isInputCommand(pending.command))
+                continue;
+            this.armTimeout(id, pending, graceMs);
+        }
+    }
+    armTimeout(id, pending, requestedMs) {
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        const now = Date.now();
+        const absoluteRemaining = pending.absoluteDeadlineAt === undefined ? requestedMs : pending.absoluteDeadlineAt - now;
+        const delay = Math.max(0, Math.min(requestedMs, absoluteRemaining));
+        pending.timer = setTimeout(() => {
+            if (!this.pending.has(id))
+                return;
+            const elapsed = Date.now() - pending.startedAt;
+            const absolute = pending.absoluteDeadlineAt !== undefined && Date.now() >= pending.absoluteDeadlineAt;
+            const error = isInputCommand(pending.command)
+                ? new Error(absolute
+                    ? `Pi RPC ${pending.command} preflight timed out at absolute ${this.inputMaxTimeoutMs}ms limit`
+                    : `Pi RPC ${pending.command} preflight timed out after ${elapsed}ms without progress`)
+                : new Error(`Pi RPC ${pending.command} timed out after ${this.requestTimeoutMs}ms`);
+            this.fail(error, true);
+        }, delay);
+        pending.timer.unref?.();
+    }
+    protocolFailure(detail) {
+        this.fail(new Error(`Pi RPC protocol error: ${detail}`), true);
+    }
+    fail(error, terminate) {
+        if (this.failed)
+            return;
+        this.failed = error;
+        for (const pending of this.pending.values()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        for (const listener of this.failureListeners)
+            listener(error);
+        if (terminate)
+            void this.beginShutdown();
+    }
+    beginShutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        if (this.exited)
+            return Promise.resolve();
+        this.shutdownPromise = new Promise((resolve) => {
+            let settled = false;
+            let forceTimer = null;
+            let hardTimer = null;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (forceTimer)
+                    clearTimeout(forceTimer);
+                if (hardTimer)
+                    clearTimeout(hardTimer);
+                resolve();
+            };
+            this.process.once("exit", finish);
+            this.process.kill("SIGTERM");
+            forceTimer = setTimeout(() => {
+                if (this.exited) {
+                    finish();
+                    return;
+                }
+                this.process.kill("SIGKILL");
+                // A real child emits exit after SIGKILL. Keep a final bound for broken
+                // process doubles/platform failures without creating a second shutdown path.
+                hardTimer = setTimeout(finish, this.shutdownGraceMs);
+                hardTimer.unref?.();
+            }, this.shutdownGraceMs);
+            forceTimer.unref?.();
+        });
+        return this.shutdownPromise;
+    }
+}
+exports.PiRpcClient = PiRpcClient;
+const INPUT_COMMANDS = new Set(["prompt", "steer", "follow_up"]);
+const INPUT_PROGRESS_EVENTS = new Set([
+    "compaction_start", "compaction_end", "auto_retry_start", "auto_retry_end",
+    "summarization_retry_scheduled", "summarization_retry_attempt_start", "summarization_retry_finished",
+]);
+const isInputCommand = (command) => INPUT_COMMANDS.has(command);
+const isInputProgress = (message) => typeof message.type === "string" && INPUT_PROGRESS_EVENTS.has(message.type);

package/dist/runtime/pi-rpc-client.mjs

@@ -0,0 +1,251 @@
+/** A strict, bounded LF-delimited client for Pi's public RPC protocol. */
+export class PiRpcClient {
+    process;
+    pending = new Map();
+    eventListeners = new Set();
+    failureListeners = new Set();
+    requestTimeoutMs;
+    inputTimeoutMs;
+    inputProgressTimeoutMs;
+    inputMaxTimeoutMs;
+    maxFrameBytes;
+    maxStderrBytes;
+    shutdownGraceMs;
+    stdoutBuffer = Buffer.alloc(0);
+    stderrBuffer = Buffer.alloc(0);
+    exited = false;
+    nextId = 0;
+    failed = null;
+    shutdownPromise = null;
+    constructor(process, options = {}) {
+        this.process = process;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
+        this.inputTimeoutMs = options.inputTimeoutMs ?? 120_000;
+        this.inputProgressTimeoutMs = options.inputProgressTimeoutMs ?? 300_000;
+        this.inputMaxTimeoutMs = options.inputMaxTimeoutMs ?? 600_000;
+        if (this.requestTimeoutMs <= 0 || this.inputTimeoutMs <= 0 || this.inputProgressTimeoutMs <= 0
+            || this.inputMaxTimeoutMs < this.inputTimeoutMs)
+            throw new Error("Pi RPC timeout options are invalid");
+        this.maxFrameBytes = options.maxFrameBytes ?? 1024 * 1024;
+        this.maxStderrBytes = options.maxStderrBytes ?? 64 * 1024;
+        this.shutdownGraceMs = options.shutdownGraceMs ?? 2_000;
+        process.stdout?.on("data", (chunk) => this.consume(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))));
+        process.stdout?.on("end", () => {
+            if (this.stdoutBuffer.length)
+                this.protocolFailure("unterminated final frame");
+        });
+        process.stderr?.on("data", (chunk) => {
+            if (this.stderrBuffer.length >= this.maxStderrBytes)
+                return;
+            const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            this.stderrBuffer = Buffer.concat([this.stderrBuffer, value.subarray(0, this.maxStderrBytes - this.stderrBuffer.length)]);
+        });
+        process.once("error", (error) => this.fail(new Error(`Pi RPC process failed: ${error.message}`), true));
+        process.once("exit", (code, signal) => {
+            this.exited = true;
+            const stderr = this.stderrBuffer.toString("utf8").trim().slice(0, 2_000);
+            this.fail(new Error(`Pi RPC process exited (${code ?? signal ?? "unknown"})${stderr ? `: ${stderr}` : ""}`), false);
+        });
+    }
+    subscribe(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    subscribeFailure(listener) {
+        this.failureListeners.add(listener);
+        if (this.failed)
+            queueMicrotask(() => listener(this.failed));
+        return () => this.failureListeners.delete(listener);
+    }
+    request(command, fields = {}) {
+        if (this.failed)
+            return Promise.reject(this.failed);
+        const id = `larkin-${++this.nextId}`;
+        return new Promise((resolve, reject) => {
+            const startedAt = Date.now();
+            const input = isInputCommand(command);
+            const pending = {
+                command, startedAt,
+                ...(input ? { absoluteDeadlineAt: startedAt + this.inputMaxTimeoutMs } : {}),
+                resolve: resolve, reject,
+            };
+            this.pending.set(id, pending);
+            this.armTimeout(id, pending, input ? this.inputTimeoutMs : this.requestTimeoutMs);
+            try {
+                if (!this.process.stdin || this.process.stdin.destroyed)
+                    throw new Error("stdin is unavailable");
+                this.process.stdin.write(`${JSON.stringify({ id, type: command, ...fields })}\n`, (error) => {
+                    if (error)
+                        this.fail(new Error(`Pi RPC ${command} write failed: ${error.message}`), true);
+                });
+            }
+            catch (error) {
+                this.fail(new Error(`Pi RPC ${command} write failed: ${error instanceof Error ? error.message : String(error)}`), true);
+            }
+        });
+    }
+    notify(command, fields = {}) {
+        if (this.failed || !this.process.stdin || this.process.stdin.destroyed)
+            return;
+        this.process.stdin.write(`${JSON.stringify({ type: command, ...fields })}\n`);
+    }
+    close() {
+        if (!this.failed)
+            this.fail(new Error("Pi RPC client closed"), true);
+        return this.beginShutdown();
+    }
+    consume(chunk) {
+        if (this.failed)
+            return;
+        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        while (true) {
+            const newline = this.stdoutBuffer.indexOf(0x0a);
+            if (newline < 0) {
+                if (this.stdoutBuffer.length > this.maxFrameBytes)
+                    this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
+                return;
+            }
+            if (newline > this.maxFrameBytes) {
+                this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
+                return;
+            }
+            let frame = this.stdoutBuffer.subarray(0, newline);
+            this.stdoutBuffer = this.stdoutBuffer.subarray(newline + 1);
+            if (frame.at(-1) === 0x0d)
+                frame = frame.subarray(0, -1);
+            if (!frame.length) {
+                this.protocolFailure("empty frame");
+                return;
+            }
+            let message;
+            try {
+                const parsed = JSON.parse(frame.toString("utf8"));
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                    throw new Error("frame is not an object");
+                message = parsed;
+            }
+            catch (error) {
+                this.protocolFailure(`malformed JSON: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+            this.dispatch(message);
+            if (this.failed)
+                return;
+        }
+    }
+    dispatch(message) {
+        if (message.type === "response" && typeof message.id === "string") {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                this.protocolFailure(`unexpected response id ${message.id}`);
+                return;
+            }
+            this.pending.delete(message.id);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            if (message.command !== pending.command) {
+                pending.reject(new Error(`Pi RPC protocol error: response command ${String(message.command)} does not match ${pending.command}`));
+                this.fail(new Error("Pi RPC protocol error: mismatched response command"), true);
+            }
+            else if (message.success === true)
+                pending.resolve(message.data);
+            else
+                pending.reject(new Error(`Pi RPC ${pending.command} failed: ${String(message.error || "unknown error")}`));
+            return;
+        }
+        if (isInputProgress(message))
+            this.refreshInputDeadlines(message.type);
+        for (const listener of this.eventListeners)
+            listener(message);
+    }
+    refreshInputDeadlines(eventType) {
+        const graceMs = eventType === "compaction_start" || eventType.startsWith("summarization_retry_")
+            || eventType === "auto_retry_start" ? this.inputProgressTimeoutMs : this.inputTimeoutMs;
+        for (const [id, pending] of this.pending) {
+            if (!isInputCommand(pending.command))
+                continue;
+            this.armTimeout(id, pending, graceMs);
+        }
+    }
+    armTimeout(id, pending, requestedMs) {
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        const now = Date.now();
+        const absoluteRemaining = pending.absoluteDeadlineAt === undefined ? requestedMs : pending.absoluteDeadlineAt - now;
+        const delay = Math.max(0, Math.min(requestedMs, absoluteRemaining));
+        pending.timer = setTimeout(() => {
+            if (!this.pending.has(id))
+                return;
+            const elapsed = Date.now() - pending.startedAt;
+            const absolute = pending.absoluteDeadlineAt !== undefined && Date.now() >= pending.absoluteDeadlineAt;
+            const error = isInputCommand(pending.command)
+                ? new Error(absolute
+                    ? `Pi RPC ${pending.command} preflight timed out at absolute ${this.inputMaxTimeoutMs}ms limit`
+                    : `Pi RPC ${pending.command} preflight timed out after ${elapsed}ms without progress`)
+                : new Error(`Pi RPC ${pending.command} timed out after ${this.requestTimeoutMs}ms`);
+            this.fail(error, true);
+        }, delay);
+        pending.timer.unref?.();
+    }
+    protocolFailure(detail) {
+        this.fail(new Error(`Pi RPC protocol error: ${detail}`), true);
+    }
+    fail(error, terminate) {
+        if (this.failed)
+            return;
+        this.failed = error;
+        for (const pending of this.pending.values()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        for (const listener of this.failureListeners)
+            listener(error);
+        if (terminate)
+            void this.beginShutdown();
+    }
+    beginShutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        if (this.exited)
+            return Promise.resolve();
+        this.shutdownPromise = new Promise((resolve) => {
+            let settled = false;
+            let forceTimer = null;
+            let hardTimer = null;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (forceTimer)
+                    clearTimeout(forceTimer);
+                if (hardTimer)
+                    clearTimeout(hardTimer);
+                resolve();
+            };
+            this.process.once("exit", finish);
+            this.process.kill("SIGTERM");
+            forceTimer = setTimeout(() => {
+                if (this.exited) {
+                    finish();
+                    return;
+                }
+                this.process.kill("SIGKILL");
+                // A real child emits exit after SIGKILL. Keep a final bound for broken
+                // process doubles/platform failures without creating a second shutdown path.
+                hardTimer = setTimeout(finish, this.shutdownGraceMs);
+                hardTimer.unref?.();
+            }, this.shutdownGraceMs);
+            forceTimer.unref?.();
+        });
+        return this.shutdownPromise;
+    }
+}
+const INPUT_COMMANDS = new Set(["prompt", "steer", "follow_up"]);
+const INPUT_PROGRESS_EVENTS = new Set([
+    "compaction_start", "compaction_end", "auto_retry_start", "auto_retry_end",
+    "summarization_retry_scheduled", "summarization_retry_attempt_start", "summarization_retry_finished",
+]);
+const isInputCommand = (command) => INPUT_COMMANDS.has(command);
+const isInputProgress = (message) => typeof message.type === "string" && INPUT_PROGRESS_EVENTS.has(message.type);

package/dist/runtime/pi-subagent-injection.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_PI_VERSION } from "./pi-provider-config.mjs";
+/**
+ * pi-subagents 扩展注入。
+ *
+ * 分发：构建期把 @tintinweb/pi-subagents bundle 成单文件
+ * `dist/runtime/pi-subagents.bundle.js`（pi-* 包 external），运行时通过
+ * `pi --extension/-e` 显式注入 —— builtin（binary-entry pi-rpc）与 external
+ * （用户 pi CLI）走同一路径，不碰用户 ~/.pi 配置。
+ *
+ * 版本门槛：pi-subagents peerDependency 要求 @earendil-works/pi-* >= 0.80.0；
+ * external 的 pi 版本低于 0.80 时不注入（降级为无 subagent 能力）。
+ */
+/**
+ * 把 embedded bundle 落盘到 <configDir>/providers/pi/extensions/pi-subagents.bundle.js（0700/0600）。
+ * 无 embedded 资产或 configDir 缺失时返回 null。
+ */
+export function materializeEmbeddedPiSubagentBundle(configDir) {
+    const embedded = globalThis.__LARKIN_EMBEDDED_PI_SUBAGENTS_BUNDLE__;
+    if (!embedded || !configDir)
+        return null;
+    const dir = path.join(path.resolve(configDir), "providers", "pi", "extensions");
+    const target = path.join(dir, "pi-subagents.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;
+    }
+}
+/**
+ * 构建产物单文件路径。优先返回 dist/runtime/pi-subagents.bundle.js（源码/编译形态）；
+ * standalone 二进制没有该文件，回退到 embedded 资产落盘（<configDir>/providers/pi/extensions/）。
+ */
+export function bundledPiSubagentExtensionPath(configDir) {
+    try {
+        const url = new URL("./pi-subagents.bundle.js", import.meta.url);
+        const resolved = fileURLToPath(url);
+        if (fs.existsSync(resolved))
+            return resolved;
+    }
+    catch {
+        /* fall through to embedded */
+    }
+    return materializeEmbeddedPiSubagentBundle(configDir);
+}
+/** 解析 `pi --version` 输出中的主版本号，无法解析返回 null。 */
+export function parsePiVersion(output) {
+    if (!output)
+        return null;
+    const match = output.match(/(\d+)\.(\d+)\.\d+/);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]) };
+}
+/** 是否满足 pi-subagents 的 pi 版本门槛（>= 0.80.0）。 */
+export function piVersionSupportsSubagents(version) {
+    if (!version)
+        return false;
+    return version.major > 0 || (version.major === 0 && version.minor >= 80);
+}
+/**
+ * 解析 `pi --version`（external 专用；builtin 用 BUNDLED_PI_VERSION 常量，无需探测）。
+ * 返回 null 表示无法确认版本（视为不支持，不注入）。
+ */
+export function probeExternalPiVersion(piCommand, env) {
+    const result = spawnSync(piCommand, ["--version"], { env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
+    if (result.error || result.status !== 0)
+        return null;
+    return parsePiVersion(String(result.stdout || result.stderr || ""));
+}
+/**
+ * 注入决策：builtin 恒注入（内嵌 pi 版本固定 BUNDLED_PI_VERSION）；external 需探测版本。
+ * 返回 `-e` 参数值（扩展 bundle 路径），或 null（不注入：产物缺失或版本不达标）。
+ * `probeVersion` 仅供测试注入；缺省时 external 用 probeExternalPiVersion 探测。
+ */
+/**
+ * 用户 pi 是否已自行安装 pi-subagents（settings.json packages 或包目录）。
+ * 已装时 Larkin 不再 -e 注入，避免同名工具（Agent/get_subagent_result/steer_subagent）
+ * 重复注册导致 pi 扩展加载 FATAL（pi 对 duplicate tool registration 是硬失败）。
+ */
+export function userPiAlreadyHasSubagentsExtension(env) {
+    const agentDir = env.PI_CODING_AGENT_DIR || path.join(env.HOME || process.env.HOME || "", ".pi", "agent");
+    try {
+        const settingsFile = path.join(agentDir, "settings.json");
+        if (fs.existsSync(settingsFile)) {
+            const settings = JSON.parse(fs.readFileSync(settingsFile, "utf8"));
+            const packages = settings?.packages;
+            if (Array.isArray(packages)) {
+                for (const entry of packages) {
+                    if (typeof entry === "string" && /pi-subagents/i.test(entry))
+                        return true;
+                }
+            }
+        }
+        // settings.json 可能未登记但包目录已存在（残留/手动安装）。
+        // Split token: repo contract forbids the literal package-manager word in sources.
+        const npmDir = path.join(agentDir, "n" + "pm", "node_modules", "@tintinweb");
+        if (fs.existsSync(npmDir) && fs.readdirSync(npmDir).some((name) => /pi-subagents/i.test(name)))
+            return true;
+    }
+    catch {
+        /* unreadable config: assume not installed, injection stays safe */
+    }
+    return false;
+}
+export function resolvePiSubagentExtensionArg(input, probeVersion = () => probeExternalPiVersion(input.piCommand, input.env), resolveBundle = () => bundledPiSubagentExtensionPath(input.env.LARKIN_CONFIG_DIR)) {
+    // resolveBundle is injectable so unit tests stay environment-independent
+    // (no dependency on build artifacts or the filesystem).
+    const bundle = resolveBundle();
+    if (!bundle)
+        return null;
+    // 用户已自行安装同款扩展时跳过注入，避免工具名重复注册冲突。
+    if (input.distribution === "external" && userPiAlreadyHasSubagentsExtension(input.env))
+        return null;
+    const version = input.distribution === "builtin" ? parsePiVersion(BUNDLED_PI_VERSION) : probeVersion();
+    return piVersionSupportsSubagents(version) ? bundle : null;
+}