larkin 0.5.4 → 0.5.6

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

@@ -1,60 +0,0 @@
-import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
-/**
- * pi bash 工具超时护栏扩展。
- *
- * 通过用户安装的 Pi 的 `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 RPC 子进程内部；build.mjs 把 `@earendil-works/pi-*`
- * 标为 external，由 host Pi 的 loader 在运行时提供模块。
- */
-/** 前台 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();
-    // Host 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

@@ -1,54 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { 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），运行时仅向 external
- * （用户 pi CLI）通过 `pi --extension/-e` 显式注入，不碰用户 ~/.pi 配置。
- * Builtin Pi 直接接收静态 factory。与 pi-subagents 共享同一个 external 版本门槛。
- */
-/** 把 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);
-}
-/** External Pi 需满足 >= 0.80.0；返回 bundle 路径或 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;
-    return piVersionSupportsSubagents(probeVersion()) ? bundle : null;
-}

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

@@ -1,43 +0,0 @@
-// @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-extension-api.mjs

@@ -1 +0,0 @@
-export {};

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

@@ -1,290 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-/**
- * pi-subagents 扩展注入。
- *
- * 分发：构建期把 @tintinweb/pi-subagents bundle 成单文件
- * `dist/runtime/pi-subagents.bundle.js`（pi-* 包 external），运行时仅向 external
- * （用户 pi CLI）通过 `pi --extension/-e` 显式注入。可只读用户 ~/.pi/agent
- * 的非密钥设置/扩展元数据以避免重复注册 FATAL；不得读、复制或写 auth.json，
- * 也不得写入 ~/.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。
- */
-function rejectSymlinkPath(target) {
-    let current = path.resolve(target);
-    for (;;) {
-        if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
-            throw new Error("bundle path must not contain a symlink");
-        }
-        const parent = path.dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-}
-function backupRegularFile(target) {
-    if (!fs.existsSync(target))
-        return null;
-    const stat = fs.lstatSync(target);
-    if (stat.isSymbolicLink())
-        throw new Error("bundle target must not be a symlink");
-    return { content: fs.readFileSync(target), mode: stat.mode & 0o777 };
-}
-function restoreRegularFile(target, backup) {
-    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) {
-        throw new Error("bundle target must not be a symlink");
-    }
-    if (!backup) {
-        if (fs.existsSync(target))
-            fs.unlinkSync(target);
-        return;
-    }
-    fs.writeFileSync(target, backup.content, { mode: backup.mode });
-    fs.chmodSync(target, backup.mode);
-}
-export function materializeEmbeddedPiSubagentBundle(configDir) {
-    const embedded = globalThis.__LARKIN_EMBEDDED_PI_SUBAGENTS_BUNDLE__;
-    const supervised = globalThis.__LARKIN_EMBEDDED_PI_SUPERVISED_COMMAND_BUNDLE__;
-    if (!embedded || !configDir)
-        return null;
-    if (!supervised)
-        throw new Error("supervised command bundle is missing");
-    const resolvedConfig = path.resolve(configDir);
-    fs.mkdirSync(resolvedConfig, { recursive: true, mode: 0o700 });
-    const canonical = fs.realpathSync(resolvedConfig);
-    const dir = path.join(canonical, "providers", "pi", "extensions");
-    const subTarget = path.join(dir, "pi-subagents.bundle.js");
-    const supTarget = path.join(dir, "pi-supervised-command.bundle.js");
-    const lockPath = path.join(dir, ".materialize.lock");
-    let lock;
-    try {
-        rejectSymlinkPath(dir);
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-        rejectSymlinkPath(dir);
-        fs.chmodSync(dir, 0o700);
-        lock = fs.openSync(lockPath, "wx", 0o600);
-        const oldSub = backupRegularFile(subTarget);
-        const oldSup = backupRegularFile(supTarget);
-        try {
-            writePrivateBundle(dir, "pi-subagents.bundle.js", embedded);
-            writePrivateBundle(dir, "pi-supervised-command.bundle.js", supervised);
-            return subTarget;
-        }
-        catch (error) {
-            restoreRegularFile(subTarget, oldSub);
-            restoreRegularFile(supTarget, oldSup);
-            throw error;
-        }
-    }
-    catch (error) {
-        if (error instanceof Error && error.message.includes("supervised command bundle is missing"))
-            throw error;
-        return null;
-    }
-    finally {
-        if (lock !== undefined) {
-            try {
-                fs.closeSync(lock);
-            }
-            catch { /* ignore */ }
-            try {
-                fs.unlinkSync(lockPath);
-            }
-            catch { /* ignore */ }
-        }
-    }
-}
-function writePrivateBundle(dir, name, embedded) {
-    const target = path.join(dir, name);
-    rejectSymlinkPath(target);
-    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) {
-        throw new Error("bundle target must not be a symlink");
-    }
-    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;
-}
-export function materializeEmbeddedPiSupervisedCommandBundle(dirOrConfig) {
-    const embedded = globalThis.__LARKIN_EMBEDDED_PI_SUPERVISED_COMMAND_BUNDLE__;
-    if (!embedded || !dirOrConfig)
-        return null;
-    const dir = dirOrConfig.endsWith("extensions") ? dirOrConfig : path.join(path.resolve(dirOrConfig), "providers", "pi", "extensions");
-    try {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-        fs.chmodSync(dir, 0o700);
-        return writePrivateBundle(dir, "pi-supervised-command.bundle.js", embedded);
-    }
-    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);
-}
-const externalPiVersionProbeCache = new Map();
-function externalPiVersionProbeKey(piCommand, env) {
-    return JSON.stringify([piCommand, env.PATH ?? ""]);
-}
-/** 测试用：清空进程内 `pi --version` 探测缓存。 */
-export function resetExternalPiVersionProbeCache() {
-    externalPiVersionProbeCache.clear();
-}
-/** 解析 external `pi --version`；无法确认版本时视为不支持，不注入。按 piCommand+PATH 缓存。 */
-export function probeExternalPiVersion(piCommand, env) {
-    const key = externalPiVersionProbeKey(piCommand, env);
-    if (externalPiVersionProbeCache.has(key))
-        return externalPiVersionProbeCache.get(key) ?? null;
-    const result = spawnSync(piCommand, ["--version"], { env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024 });
-    const version = result.error || result.status !== 0
-        ? null
-        : parsePiVersion(String(result.stdout || result.stderr || ""));
-    externalPiVersionProbeCache.set(key, version);
-    return version;
-}
-/**
- * 用户 pi 是否已自行安装 pi-subagents（settings.json packages 或包目录）。
- * 已装时 Larkin 不再 -e 注入，避免同名工具（Agent/get_subagent_result/steer_subagent）
- * 重复注册导致 pi 扩展加载 FATAL（pi 对 duplicate tool registration 是硬失败）。
- *
- * Owner 边界：只读非密钥兼容信息（settings.json / package 清单 / 扩展源码标记）。
- * 不得打开或写入用户 Pi home 里的 auth.json，也不得往 ~/.pi 写任何文件。
- */
-const BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
-const SUPERVISED_COMMAND_CAPABILITY = "larkin-pi-supervised-command-v1";
-function assertRegularFile(file) {
-    const stat = fs.lstatSync(file);
-    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
-        throw new Error("user Pi path is not a regular file");
-    }
-}
-function readRegularFile(file) {
-    assertRegularFile(file);
-    return fs.readFileSync(file, "utf8");
-}
-function isRealpathInside(root, candidate) {
-    const rootReal = fs.realpathSync(root);
-    const candidateReal = fs.realpathSync(candidate);
-    const prefix = rootReal.endsWith(path.sep) ? rootReal : `${rootReal}${path.sep}`;
-    return candidateReal.startsWith(prefix);
-}
-/** 只读包根内的单链接常规文件；绝对路径、逃逸、符号链接、硬链接一律视为不可验证。 */
-function readContainedPackageEntry(packageRoot, entry) {
-    if (path.isAbsolute(entry))
-        throw new Error("absolute Pi extension entry");
-    const root = path.resolve(packageRoot);
-    const resolved = path.resolve(root, entry);
-    const lexicalPrefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
-    if (resolved !== root && !resolved.startsWith(lexicalPrefix))
-        throw new Error("Pi extension entry escaped package root");
-    assertRegularFile(resolved);
-    if (!isRealpathInside(root, resolved))
-        throw new Error("Pi extension entry escaped package root");
-    return fs.readFileSync(resolved, "utf8");
-}
-function userPiSubagentsWaitCapability(env) {
-    const agentDir = env.PI_CODING_AGENT_DIR || path.join(env.HOME || process.env.HOME || "", ".pi", "agent");
-    try {
-        let configured = false;
-        const settingsFile = path.join(agentDir, "settings.json");
-        if (fs.existsSync(settingsFile)) {
-            const settings = JSON.parse(readRegularFile(settingsFile));
-            const packages = settings?.packages;
-            if (Array.isArray(packages)) {
-                configured = packages.some((entry) => typeof entry === "string" && /pi-subagents/i.test(entry));
-            }
-        }
-        // settings.json 可能未登记但包目录已存在（残留/手动安装）。
-        // Split token: repo contract forbids the literal package-manager word in sources.
-        const packageRoots = [
-            path.join(agentDir, "n" + "pm", "node_modules", "@tintinweb", "pi-subagents"),
-            path.join(agentDir, "node_modules", "@tintinweb", "pi-subagents"),
-        ];
-        const installedRoot = packageRoots.find((root) => fs.existsSync(root));
-        if (!configured && !installedRoot)
-            return "absent";
-        if (!installedRoot)
-            return "unbounded";
-        const packageManifest = JSON.parse(readRegularFile(path.join(installedRoot, "package.json")));
-        const extensions = packageManifest.pi?.extensions;
-        if (!Array.isArray(extensions) || extensions.length === 0
-            || !extensions.every((entry) => typeof entry === "string" && entry.length > 0)) {
-            return "unbounded";
-        }
-        // Pi executes the entries declared by the package manifest. Do not trust a
-        // marker in a build artifact when the manifest points Pi at another file.
-        const hasCapability = extensions.every((entry) => {
-            const source = readContainedPackageEntry(installedRoot, entry);
-            return source.includes(BOUNDED_WAIT_CAPABILITY) && source.includes(SUPERVISED_COMMAND_CAPABILITY);
-        });
-        return hasCapability ? "bounded" : "unbounded";
-    }
-    catch {
-        // Unreadable or escaped user extension state is not safe to treat as bounded.
-        return "unbounded";
-    }
-}
-export function userPiAlreadyHasSubagentsExtension(env) {
-    return userPiSubagentsWaitCapability(env) !== "absent";
-}
-export function userPiSubagentsHasBoundedWaitCapability(env) {
-    return userPiSubagentsWaitCapability(env) === "bounded";
-}
-export function resolvePiSubagentExtensionArg(input, probeVersion = () => probeExternalPiVersion(input.piCommand, input.env), resolveBundle = () => bundledPiSubagentExtensionPath(input.env.LARKIN_CONFIG_DIR)) {
-    // A user-installed extension wins only when it advertises the exact bounded
-    // wait capability. Check this before the bundle path so a missing Larkin
-    // asset cannot silently leave an unbounded user extension active.
-    if (userPiAlreadyHasSubagentsExtension(input.env)) {
-        if (!userPiSubagentsHasBoundedWaitCapability(input.env)) {
-            throw new Error("[larkin] WARNING: refusing external Pi because the user-installed " +
-                "pi-subagents extension is unbounded or unverifiable; remove it or install " +
-                "a version advertising larkin-pi-subagents-bounded-wait-v1 and larkin-pi-supervised-command-v1.");
-        }
-        return null;
-    }
-    // resolveBundle is injectable so unit tests stay environment-independent
-    // (no dependency on build artifacts or the filesystem).
-    const bundle = resolveBundle();
-    if (!bundle)
-        return null;
-    return piVersionSupportsSubagents(probeVersion()) ? bundle : null;
-}