larkin 0.5.3 → 0.5.5

package/dist/platform/config.mjs

@@ -8,11 +8,16 @@ import { CURRENT_RUNTIME_MODELS } from "../runtime/runtime-model-catalog.mjs";
 import { fromUserRuntime, isAdapterRuntime, isUserRuntime, toUserRuntime } from "../runtime/user-runtime.mjs";
 import processInspect from "./process-inspect.cjs";
 export { RUNTIME_OPTIONS, fromUserRuntime, isAdapterRuntime, isUserRuntime, runtimeOptionOf, runtimeOptionTarget, toUserRuntime, } from "../runtime/user-runtime.mjs";
+export const DEFAULT_INBOX_AUDIT_INTERVAL_MS = 15 * 60_000;
+export const MIN_INBOX_AUDIT_INTERVAL_MS = 60_000;
+export const MAX_INBOX_AUDIT_INTERVAL_MS = 24 * 60 * 60_000;
 const TOP_FIELDS_V3 = new Set(["version", "serverId", "activeAgent", "agents"]);
 const TOP_FIELDS_V4 = new Set(["version", "serverId", "mentionPolicy", "activeAgent", "agents"]);
+const OPTIONAL_TOP_FIELDS_V4 = new Set(["inboxAudit"]);
 const AGENT_FIELDS_V3 = new Set(["runtime", "model", "effort", "noMentionChats", "createdAt"]);
-const AGENT_FIELDS_V4 = new Set(["runtime", "model", "effort", "mentionPolicy", "chatMentionPolicies", "createdAt"]);
+const AGENT_FIELDS_V4 = new Set(["runtime", "model", "effort", "mentionPolicy", "chatMentionPolicies", "inboxAudit", "createdAt"]);
 const LEGACY_AGENT_FIELDS = new Set(["piDistribution", "runtimeOption"]);
+const INBOX_AUDIT_FIELDS = new Set(["enabled", "intervalMs"]);
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
 const CHAT_ID = /^oc_[A-Za-z0-9_-]+$/;
 const PI_EFFORTS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
@@ -76,6 +81,85 @@ function assertPolicy(value, label) {
     if (value !== "require" && value !== "free")
         throw new Error(`${label} 只允许 require/free`);
 }
+export function assertInboxAuditInterval(value, label = "inbox-audit interval") {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < MIN_INBOX_AUDIT_INTERVAL_MS || value > MAX_INBOX_AUDIT_INTERVAL_MS) {
+        throw new Error(`${label} 必须是 ${MIN_INBOX_AUDIT_INTERVAL_MS}–${MAX_INBOX_AUDIT_INTERVAL_MS} 毫秒`);
+    }
+}
+export function parseInboxAuditInterval(value) {
+    if (typeof value !== "string" || !value)
+        throw new Error("inbox-audit interval 不能为空");
+    let milliseconds;
+    if (/^[1-9]\d*$/.test(value))
+        milliseconds = Number(value);
+    else {
+        const match = /^([1-9]\d*)(m|h)$/.exec(value);
+        if (!match)
+            throw new Error("inbox-audit interval 只允许 15m/1h 或 60000–86400000 毫秒");
+        milliseconds = Number(match[1]) * (match[2] === "h" ? 3_600_000 : 60_000);
+    }
+    assertInboxAuditInterval(milliseconds);
+    return milliseconds;
+}
+export function formatInboxAuditInterval(intervalMs) {
+    if (intervalMs % 3_600_000 === 0)
+        return `${intervalMs / 3_600_000}h`;
+    if (intervalMs % 60_000 === 0)
+        return `${intervalMs / 60_000}m`;
+    return `${intervalMs}ms`;
+}
+function parseStoredInboxAudit(value, label) {
+    if (!isPlainObject(value))
+        throw new Error(`${label} 必须是普通 object`);
+    assertAllowedFields(value, INBOX_AUDIT_FIELDS, label);
+    const settings = {};
+    if (Object.hasOwn(value, "enabled")) {
+        if (typeof value.enabled !== "boolean")
+            throw new Error(`${label}.enabled 必须是 boolean`);
+        settings.enabled = value.enabled;
+    }
+    if (Object.hasOwn(value, "intervalMs")) {
+        assertInboxAuditInterval(value.intervalMs, `${label}.intervalMs`);
+        settings.intervalMs = value.intervalMs;
+    }
+    return settings;
+}
+function resolvedInboxAudit(settings) {
+    return {
+        enabled: settings?.enabled ?? false,
+        intervalMs: settings?.intervalMs ?? DEFAULT_INBOX_AUDIT_INTERVAL_MS,
+    };
+}
+export function inboxAuditMutationFromCli(input) {
+    if (input.scope === "global") {
+        if (input.enabled !== "on" && input.enabled !== "off") {
+            throw new Error("用法: larkin config inbox-audit global <on|off> [--interval <15m|1h>]");
+        }
+        const mutation = {
+            kind: "set-global-inbox-audit", enabled: input.enabled === "on",
+        };
+        if (input.interval !== undefined) {
+            if (input.interval === "inherit")
+                throw new Error("全局 inbox-audit 不支持 interval=inherit");
+            mutation.intervalMs = parseInboxAuditInterval(input.interval);
+        }
+        return mutation;
+    }
+    if (input.scope === "agent") {
+        if (input.enabled !== "on" && input.enabled !== "off" && input.enabled !== "inherit") {
+            throw new Error("用法: larkin config inbox-audit agent <inherit|on|off> [--agent <App ID>] [--interval <15m|inherit>]");
+        }
+        const mutation = {
+            kind: "set-agent-inbox-audit", agentId: input.agentId,
+            enabled: input.enabled === "inherit" ? "inherit" : input.enabled === "on",
+        };
+        if (input.interval !== undefined) {
+            mutation.intervalMs = input.interval === "inherit" ? "inherit" : parseInboxAuditInterval(input.interval);
+        }
+        return mutation;
+    }
+    throw new Error("inbox-audit scope 只支持 global/agent");
+}
 function assertModel(runtime, model) {
     if (model === "default")
         return;
@@ -143,6 +227,8 @@ function validateStoredAgent(key, agent, version) {
     }
     if (version === 4 && Object.hasOwn(agent, "mentionPolicy"))
         assertPolicy(agent.mentionPolicy, `Agent ${key}.mentionPolicy`);
+    if (version === 4 && Object.hasOwn(agent, "inboxAudit"))
+        parseStoredInboxAudit(agent.inboxAudit, `Agent ${key}.inboxAudit`);
     if (version === 4 && Object.hasOwn(agent, "chatMentionPolicies")) {
         if (!isPlainObject(agent.chatMentionPolicies))
             throw new Error(`Agent ${key}.chatMentionPolicies 必须是普通 object`);
@@ -171,6 +257,7 @@ function hydratedStoredAgent(key, agent, version) {
         model: agent.model,
         ...(typeof agent.effort === "string" ? { effort: agent.effort } : {}),
         ...(version === 4 && (agent.mentionPolicy === "require" || agent.mentionPolicy === "free") ? { mentionPolicy: agent.mentionPolicy } : {}),
+        ...(version === 4 && Object.hasOwn(agent, "inboxAudit") ? { inboxAudit: parseStoredInboxAudit(agent.inboxAudit, `Agent ${key}.inboxAudit`) } : {}),
         ...(Object.keys(chatMentionPolicies).length ? { chatMentionPolicies, noMentionChats: Object.entries(chatMentionPolicies).filter(([, policy]) => policy === "free").map(([chatId]) => chatId) } : {}),
         ...(typeof agent.createdAt === "string" ? { createdAt: agent.createdAt } : {}),
     };
@@ -184,6 +271,7 @@ export function hydrateAgent(key, agent, configDir) {
         larkConfigDir: path.join(layout.agentStateDir(key), "lark-cli-config"),
         ...(agent.effort ? { effort: agent.effort } : {}),
         ...(agent.mentionPolicy ? { mentionPolicy: agent.mentionPolicy } : {}),
+        ...(agent.inboxAudit ? { inboxAudit: { ...agent.inboxAudit } } : {}),
         ...(agent.chatMentionPolicies ? { chatMentionPolicies: { ...agent.chatMentionPolicies } } : {}),
         ...(agent.noMentionChats ? { noMentionChats: [...agent.noMentionChats] } : {}),
         ...(agent.createdAt ? { createdAt: agent.createdAt } : {}),
@@ -202,7 +290,7 @@ export function normalizeConfig(raw, configDir, { mint } = {}) {
     if (version !== 3 && version !== 4)
         throw new Error("不支持该配置格式：larkin 只接受 version=3/4");
     const topFields = version === 3 ? TOP_FIELDS_V3 : TOP_FIELDS_V4;
-    assertAllowedFields(raw, topFields, "config");
+    assertAllowedFields(raw, version === 4 ? new Set([...TOP_FIELDS_V4, ...OPTIONAL_TOP_FIELDS_V4]) : topFields, "config");
     for (const field of topFields)
         if (!Object.hasOwn(raw, field))
             throw new Error(`config 缺少必需字段 ${field}`);
@@ -221,8 +309,12 @@ export function normalizeConfig(raw, configDir, { mint } = {}) {
     const agents = {};
     for (const [key, agent] of Object.entries(raw.agents))
         agents[key] = hydrateAgent(key, hydratedStoredAgent(key, agent, version), layout.root);
+    const inboxAudit = version === 4 && Object.hasOwn(raw, "inboxAudit")
+        ? resolvedInboxAudit(parseStoredInboxAudit(raw.inboxAudit, "config.inboxAudit"))
+        : undefined;
     return {
         version: 4, serverId: raw.serverId, mentionPolicy: version === 4 ? raw.mentionPolicy : "require",
+        ...(inboxAudit ? { inboxAudit } : {}),
         configDir: layout.configDir, larkinHome: layout.larkinHome, larkConfigDir: resolveLarkConfigDir({}, layout.root), activeAgent: raw.activeAgent, agents,
     };
 }
@@ -448,7 +540,11 @@ export function selectAgent(config, env = process.env) {
     return agents[config.activeAgent];
 }
 export function toStored(config) {
-    const out = { version: 4, serverId: config.serverId, mentionPolicy: config.mentionPolicy, activeAgent: config.activeAgent, agents: {} };
+    const out = {
+        version: 4, serverId: config.serverId, mentionPolicy: config.mentionPolicy, activeAgent: config.activeAgent, agents: {},
+    };
+    if (config.inboxAudit)
+        out.inboxAudit = { enabled: config.inboxAudit.enabled, intervalMs: config.inboxAudit.intervalMs };
     for (const [key, agent] of Object.entries(config.agents || {})) {
         const stored = { runtime: agent.runtime, model: agent.model };
         if (typeof agent.effort === "string" && agent.effort)
@@ -457,6 +553,9 @@ export function toStored(config) {
             stored.mentionPolicy = agent.mentionPolicy;
         if (agent.chatMentionPolicies && Object.keys(agent.chatMentionPolicies).length)
             stored.chatMentionPolicies = { ...agent.chatMentionPolicies };
+        if (agent.inboxAudit && (agent.inboxAudit.enabled !== undefined || agent.inboxAudit.intervalMs !== undefined)) {
+            stored.inboxAudit = { ...agent.inboxAudit };
+        }
         if (typeof agent.createdAt === "string" && agent.createdAt)
             stored.createdAt = agent.createdAt;
         out.agents[key] = stored;
@@ -483,6 +582,20 @@ export function resolveAgentGlobalMentionPolicy(config, agentId) {
         return { effective: agent.mentionPolicy, source: "agent" };
     return { effective: config.mentionPolicy, source: "global" };
 }
+export function resolveInboxAuditSchedule(config, agentId) {
+    const agent = config.agents[agentId];
+    if (!agent)
+        throw new Error(`Agent 不存在：${agentId}`);
+    const enabled = agent.inboxAudit?.enabled ?? config.inboxAudit?.enabled ?? false;
+    const intervalMs = agent.inboxAudit?.intervalMs ?? config.inboxAudit?.intervalMs ?? DEFAULT_INBOX_AUDIT_INTERVAL_MS;
+    assertInboxAuditInterval(intervalMs);
+    return {
+        enabled,
+        intervalMs,
+        enabledSource: agent.inboxAudit?.enabled !== undefined ? "agent" : config.inboxAudit ? "global" : "default",
+        intervalSource: agent.inboxAudit?.intervalMs !== undefined ? "agent" : config.inboxAudit?.intervalMs !== undefined ? "global" : "default",
+    };
+}
 function revision(bytes) {
     return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
 }
@@ -495,6 +608,7 @@ function agentSignature(config, agentId) {
         schema: 2,
         runtime: agent.runtime, model: agent.model, effort: agent.effort ?? null,
         globalMentionPolicy: config.mentionPolicy, agentMentionPolicy: agent.mentionPolicy ?? null, chatMentionPolicies: chats,
+        globalInboxAudit: config.inboxAudit ?? null, agentInboxAudit: agent.inboxAudit ?? null,
     }));
 }
 export function runtimeConfigSignature(config, agentId) {
@@ -632,6 +746,19 @@ function applyMutation(config, mutation) {
         config.mentionPolicy = mutation.value;
         return { scope: "global", runtimeChange: false, affectedAgentIds: Object.keys(config.agents) };
     }
+    if (mutation.kind === "set-global-inbox-audit") {
+        if (mutation.enabled === undefined && mutation.intervalMs === undefined)
+            throw new Error("inbox-audit 全局变更必须包含 enabled 或 interval");
+        const current = resolvedInboxAudit(config.inboxAudit);
+        if (mutation.enabled !== undefined)
+            current.enabled = mutation.enabled;
+        if (mutation.intervalMs !== undefined) {
+            assertInboxAuditInterval(mutation.intervalMs, "全局 inbox-audit interval");
+            current.intervalMs = mutation.intervalMs;
+        }
+        config.inboxAudit = current;
+        return { scope: "global", runtimeChange: false, affectedAgentIds: Object.keys(config.agents) };
+    }
     if (!APP_ID.test(mutation.agentId) || !config.agents[mutation.agentId])
         throw new Error(`Agent 不存在：${mutation.agentId}`);
     const agent = config.agents[mutation.agentId];
@@ -644,6 +771,26 @@ function applyMutation(config, mutation) {
         }
         return { scope: "agent", agentId: mutation.agentId, runtimeChange: false, affectedAgentIds: [mutation.agentId] };
     }
+    if (mutation.kind === "set-agent-inbox-audit") {
+        if (mutation.enabled === undefined && mutation.intervalMs === undefined)
+            throw new Error("inbox-audit Agent 变更必须包含 enabled 或 interval");
+        const current = { ...(agent.inboxAudit || {}) };
+        if (mutation.enabled === "inherit")
+            delete current.enabled;
+        else if (mutation.enabled !== undefined)
+            current.enabled = mutation.enabled;
+        if (mutation.intervalMs === "inherit")
+            delete current.intervalMs;
+        else if (mutation.intervalMs !== undefined) {
+            assertInboxAuditInterval(mutation.intervalMs, "Agent inbox-audit interval");
+            current.intervalMs = mutation.intervalMs;
+        }
+        if (current.enabled === undefined && current.intervalMs === undefined)
+            delete agent.inboxAudit;
+        else
+            agent.inboxAudit = current;
+        return { scope: "agent", agentId: mutation.agentId, runtimeChange: false, affectedAgentIds: [mutation.agentId] };
+    }
     if (mutation.kind === "set-chat-mention") {
         if (!CHAT_ID.test(mutation.chatId))
             throw new Error(`群 ID 格式无效：${mutation.chatId}`);
@@ -1130,8 +1277,24 @@ export function safeConfigView(config, onlyAgentId, chatId, applyState) {
             source: agent.mentionPolicy ? "agent" : "global",
             ...(chatId ? { chat: { chatId, override: agent.chatMentionPolicies?.[chatId] ?? "inherit", ...resolveMentionPolicy(config, agentId, chatId) } } : {}),
         },
+        inboxAudit: (() => {
+            const resolved = resolveInboxAuditSchedule(config, agentId);
+            return {
+                override: {
+                    enabled: agent.inboxAudit?.enabled === undefined ? "inherit" : agent.inboxAudit.enabled ? "on" : "off",
+                    intervalMs: agent.inboxAudit?.intervalMs ?? "inherit",
+                },
+                effective: { enabled: resolved.enabled, intervalMs: resolved.intervalMs },
+                source: { enabled: resolved.enabledSource, intervalMs: resolved.intervalSource },
+            };
+        })(),
         chatMentionPolicies: { ...(agent.chatMentionPolicies || {}) },
         apply: applyState?.agents?.[agentId] ?? { applyState: "unknown" },
     }));
-    return { version: 4, mentionPolicy: config.mentionPolicy, persistedRevision: applyState?.persistedRevision ?? "unknown", agents };
+    const inboxAudit = resolvedInboxAudit(config.inboxAudit);
+    return {
+        version: 4, mentionPolicy: config.mentionPolicy,
+        inboxAudit: { enabled: inboxAudit.enabled, intervalMs: inboxAudit.intervalMs },
+        persistedRevision: applyState?.persistedRevision ?? "unknown", agents,
+    };
 }

package/dist/runtime/pi-state-dir.cjs

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectivePiStateDir = effectivePiStateDir;
+exports.ensureOwnedTree = ensureOwnedTree;
+exports.ensurePrivateDirectory = ensurePrivateDirectory;
+exports.mkdirPrivateExclusive = mkdirPrivateExclusive;
+exports.writePrivateExclusive = writePrivateExclusive;
+exports.writePrivateAtomic = writePrivateAtomic;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Same implicit root the Pi adapter uses when `stateDir` is omitted. */
+function effectivePiStateDir(input) {
+    return input.stateDir ?? node_path_1.default.join(input.workspaceDir, ".larkin");
+}
+/**
+ * 从 root 起逐层建 0700 子树。root 可以位于 /var、/tmp 等合法祖先 link 之后；
+ * 任一层 owned 组件自身是 symlink 则拒绝，不顺着 link 往外写。
+ */
+function ensureOwnedTree(root, parts = [], create = true) {
+    const resolved = node_path_1.default.resolve(root);
+    if (node_fs_1.default.existsSync(resolved)) {
+        const stat = node_fs_1.default.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    else if (create) {
+        node_fs_1.default.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+        if (node_fs_1.default.lstatSync(resolved).isSymbolicLink() || !node_fs_1.default.lstatSync(resolved).isDirectory()) {
+            throw new Error(`unsafe private directory: ${resolved}`);
+        }
+    }
+    else {
+        throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    let dir = resolved;
+    for (const part of parts) {
+        if (!part || part === "." || part === ".." || /[\\/]/.test(part))
+            throw new Error(`unsafe owned path component: ${part}`);
+        dir = node_path_1.default.join(dir, part);
+        try {
+            const existing = node_fs_1.default.lstatSync(dir);
+            if (existing.isSymbolicLink() || !existing.isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (!create)
+                throw new Error(`unsafe private directory: ${dir}`);
+            node_fs_1.default.mkdirSync(dir, { mode: 0o700 });
+            if (node_fs_1.default.lstatSync(dir).isSymbolicLink() || !node_fs_1.default.lstatSync(dir).isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        if (process.platform !== "win32")
+            node_fs_1.default.chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+function ensurePrivateDirectory(directory) {
+    ensureOwnedTree(directory);
+}
+/** 独占新建 0700 目录；已存在或变成 symlink 都拒绝。 */
+function mkdirPrivateExclusive(directory) {
+    node_fs_1.default.mkdirSync(directory, { mode: 0o700 });
+    const created = node_fs_1.default.lstatSync(directory);
+    if (created.isSymbolicLink() || !created.isDirectory())
+        throw new Error(`unsafe private directory: ${directory}`);
+    if (process.platform !== "win32")
+        node_fs_1.default.chmodSync(directory, 0o700);
+}
+/** 独占新建 0600 文件；已存在（含 symlink）时失败，不跟随写出。 */
+function writePrivateExclusive(file, content) {
+    node_fs_1.default.writeFileSync(file, content, { mode: 0o600, flag: "wx" });
+    if (process.platform !== "win32")
+        node_fs_1.default.chmodSync(file, 0o600);
+}
+/** 原子写 0600 文件；目标或父目录已是 symlink 时拒绝，避免落到目录外。 */
+function writePrivateAtomic(file, content) {
+    try {
+        if (node_fs_1.default.lstatSync(node_path_1.default.dirname(file)).isSymbolicLink())
+            throw new Error(`unsafe private directory: ${node_path_1.default.dirname(file)}`);
+        if (node_fs_1.default.lstatSync(file).isSymbolicLink())
+            throw new Error(`${node_path_1.default.basename(file)} must not be a symlink`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temporary = node_path_1.default.join(node_path_1.default.dirname(file), `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
+    try {
+        node_fs_1.default.writeFileSync(temporary, content, { mode: 0o600, flag: "wx" });
+        node_fs_1.default.renameSync(temporary, file);
+        node_fs_1.default.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            node_fs_1.default.unlinkSync(temporary);
+        }
+        catch { /* renamed or absent */ }
+    }
+}

package/dist/runtime/pi-state-dir.mjs

@@ -0,0 +1,94 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** Same implicit root the Pi adapter uses when `stateDir` is omitted. */
+export function effectivePiStateDir(input) {
+    return input.stateDir ?? path.join(input.workspaceDir, ".larkin");
+}
+/**
+ * 从 root 起逐层建 0700 子树。root 可以位于 /var、/tmp 等合法祖先 link 之后；
+ * 任一层 owned 组件自身是 symlink 则拒绝，不顺着 link 往外写。
+ */
+export function ensureOwnedTree(root, parts = [], create = true) {
+    const resolved = path.resolve(root);
+    if (fs.existsSync(resolved)) {
+        const stat = fs.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    else if (create) {
+        fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+        if (fs.lstatSync(resolved).isSymbolicLink() || !fs.lstatSync(resolved).isDirectory()) {
+            throw new Error(`unsafe private directory: ${resolved}`);
+        }
+    }
+    else {
+        throw new Error(`unsafe private directory: ${resolved}`);
+    }
+    let dir = resolved;
+    for (const part of parts) {
+        if (!part || part === "." || part === ".." || /[\\/]/.test(part))
+            throw new Error(`unsafe owned path component: ${part}`);
+        dir = path.join(dir, part);
+        try {
+            const existing = fs.lstatSync(dir);
+            if (existing.isSymbolicLink() || !existing.isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (!create)
+                throw new Error(`unsafe private directory: ${dir}`);
+            fs.mkdirSync(dir, { mode: 0o700 });
+            if (fs.lstatSync(dir).isSymbolicLink() || !fs.lstatSync(dir).isDirectory())
+                throw new Error(`unsafe private directory: ${dir}`);
+        }
+        if (process.platform !== "win32")
+            fs.chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+export function ensurePrivateDirectory(directory) {
+    ensureOwnedTree(directory);
+}
+/** 独占新建 0700 目录；已存在或变成 symlink 都拒绝。 */
+export function mkdirPrivateExclusive(directory) {
+    fs.mkdirSync(directory, { mode: 0o700 });
+    const created = fs.lstatSync(directory);
+    if (created.isSymbolicLink() || !created.isDirectory())
+        throw new Error(`unsafe private directory: ${directory}`);
+    if (process.platform !== "win32")
+        fs.chmodSync(directory, 0o700);
+}
+/** 独占新建 0600 文件；已存在（含 symlink）时失败，不跟随写出。 */
+export function writePrivateExclusive(file, content) {
+    fs.writeFileSync(file, content, { mode: 0o600, flag: "wx" });
+    if (process.platform !== "win32")
+        fs.chmodSync(file, 0o600);
+}
+/** 原子写 0600 文件；目标或父目录已是 symlink 时拒绝，避免落到目录外。 */
+export function writePrivateAtomic(file, content) {
+    try {
+        if (fs.lstatSync(path.dirname(file)).isSymbolicLink())
+            throw new Error(`unsafe private directory: ${path.dirname(file)}`);
+        if (fs.lstatSync(file).isSymbolicLink())
+            throw new Error(`${path.basename(file)} must not be a symlink`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, content, { mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* renamed or absent */ }
+    }
+}

package/dist/runtime/pi-tmux-extension.mjs

@@ -0,0 +1,137 @@
+import crypto from "node:crypto";
+import { Type } from "typebox";
+import { createLarkinTmux, DEFAULT_BASH_WAIT_SECONDS, ForeignTmuxTaskError, formatTmuxTaskText, LARKIN_TMUX_COMPLETION_TYPE, tmuxAvailable, } from "./pi-tmux.mjs";
+function resultOf(snapshot) {
+    return {
+        content: [{ type: "text", text: formatTmuxTaskText(snapshot) }],
+        details: {
+            taskId: snapshot.taskId,
+            status: snapshot.status,
+            exitCode: snapshot.exitCode,
+            output: snapshot.output,
+        },
+    };
+}
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        details: { taskId: "", status: "failed", exitCode: null, output: message },
+    };
+}
+export function registerLarkinTmuxExtension(pi) {
+    if (!tmuxAvailable())
+        return false;
+    const stateDir = process.env.LARKIN_STATE_DIR || `${process.cwd()}/.larkin`;
+    const agentId = process.env.LARKIN_AGENT_ID || "agent";
+    const instanceId = process.env.LARKIN_TMUX_INSTANCE_ID
+        || process.env.LARKIN_RUNTIME_OBSERVATION_GENERATION
+        || crypto.randomUUID();
+    const tmux = createLarkinTmux({ stateDir, agentId, instanceId, env: process.env });
+    const watchers = new Map();
+    const notified = new Set();
+    const stopWatchers = () => {
+        for (const timer of watchers.values())
+            clearInterval(timer);
+        watchers.clear();
+    };
+    const notifyOnce = (snapshot) => {
+        if (snapshot.status === "running" || notified.has(snapshot.taskId))
+            return;
+        notified.add(snapshot.taskId);
+        pi.sendMessage({
+            customType: LARKIN_TMUX_COMPLETION_TYPE,
+            content: formatTmuxTaskText(snapshot),
+            display: true,
+            details: {
+                taskId: snapshot.taskId,
+                exitCode: snapshot.exitCode,
+                output: snapshot.output,
+            },
+        }, { triggerTurn: true, deliverAs: "followUp" });
+    };
+    const watch = (taskId) => {
+        if (watchers.has(taskId) || notified.has(taskId))
+            return;
+        const timer = setInterval(() => {
+            try {
+                const snapshot = tmux.peek(taskId);
+                if (snapshot.status === "running")
+                    return;
+                clearInterval(timer);
+                watchers.delete(taskId);
+                notifyOnce(snapshot);
+            }
+            catch {
+                clearInterval(timer);
+                watchers.delete(taskId);
+            }
+        }, 250);
+        watchers.set(taskId, timer);
+    };
+    pi.on("session_shutdown", () => {
+        stopWatchers();
+    });
+    pi.registerTool({
+        name: "bash",
+        label: "bash",
+        description: "Run a command in a detached tmux window. timeout is a wait window only and never hard-kills. background:true returns immediately.",
+        parameters: Type.Object({
+            command: Type.String(),
+            timeout: Type.Optional(Type.Number()),
+            background: Type.Optional(Type.Boolean()),
+        }),
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const snapshot = tmux.start(params.command, ctx.cwd);
+            if (params.background === true) {
+                watch(snapshot.taskId);
+                return resultOf(tmux.peek(snapshot.taskId));
+            }
+            const timeout = typeof params.timeout === "number" && params.timeout >= 0 ? params.timeout : DEFAULT_BASH_WAIT_SECONDS;
+            const waited = await tmux.wait(snapshot.taskId, timeout, signal);
+            if (waited.status === "running")
+                watch(waited.taskId);
+            return resultOf(waited);
+        },
+    });
+    pi.registerTool({
+        name: "tmux",
+        label: "tmux",
+        description: "List, peek, or kill Larkin-owned tmux tasks for this Agent. Foreign task IDs are rejected.",
+        parameters: Type.Object({
+            action: Type.Union([Type.Literal("list"), Type.Literal("peek"), Type.Literal("kill")]),
+            taskId: Type.Optional(Type.String()),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                if (params.action === "list") {
+                    const tasks = tmux.list();
+                    return {
+                        content: [{ type: "text", text: tasks.map(formatTmuxTaskText).join("\n---\n") || "no owned tmux tasks" }],
+                        details: { taskId: "", status: "completed", exitCode: 0, output: "" },
+                    };
+                }
+                if (!params.taskId)
+                    return errorResult("taskId is required for peek and kill");
+                if (params.action === "peek")
+                    return resultOf(tmux.peek(params.taskId));
+                const killed = tmux.kill(params.taskId);
+                notified.add(params.taskId);
+                const timer = watchers.get(params.taskId);
+                if (timer) {
+                    clearInterval(timer);
+                    watchers.delete(params.taskId);
+                }
+                return resultOf(killed);
+            }
+            catch (error) {
+                if (error instanceof ForeignTmuxTaskError)
+                    return errorResult(error.message);
+                throw error;
+            }
+        },
+    });
+    return true;
+}
+export default function larkinTmuxExtension(pi) {
+    registerLarkinTmuxExtension(pi);
+}

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

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureOwnedTree, writePrivateAtomic } from "./pi-state-dir.mjs";
+import { tmuxAvailable } from "./pi-tmux.mjs";
+const BUNDLE_NAME = "pi-tmux.bundle.js";
+export function materializeEmbeddedPiTmuxBundle(configDir) {
+    const embedded = globalThis.__LARKIN_EMBEDDED_PI_TMUX_BUNDLE__;
+    if (!embedded || !configDir)
+        return null;
+    try {
+        const dir = ensureOwnedTree(path.resolve(configDir), ["providers", "pi", "extensions"]);
+        const target = path.join(dir, BUNDLE_NAME);
+        try {
+            if (fs.lstatSync(target).isSymbolicLink())
+                throw new Error("pi-tmux bundle must not be a symlink");
+            if (fs.readFileSync(target, "utf8") === embedded)
+                return target;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        writePrivateAtomic(target, embedded);
+        return target;
+    }
+    catch (error) {
+        throw new Error("Could not materialize the Larkin tmux extension", { cause: error });
+    }
+}
+export function bundledPiTmuxExtensionPath(configDir) {
+    try {
+        const resolved = fileURLToPath(new URL(`./${BUNDLE_NAME}`, import.meta.url));
+        if (fs.existsSync(resolved))
+            return resolved;
+    }
+    catch {
+        /* fall through to embedded */
+    }
+    return materializeEmbeddedPiTmuxBundle(configDir);
+}
+export function resolvePiTmuxExtensionArg(input, resolveBundle = () => bundledPiTmuxExtensionPath(input.env.LARKIN_CONFIG_DIR), available = tmuxAvailable) {
+    if (input.platform === "win32" || !available(input.env, input.platform))
+        return null;
+    const bundle = resolveBundle();
+    if (!bundle)
+        throw new Error("Larkin tmux extension bundle is missing; rebuild or reinstall Larkin");
+    return bundle;
+}