larkin 0.5.16 → 0.5.18

package/dist/app/lark-cli.mjs

@@ -190,7 +190,7 @@ export function classifyLarkCliCommand(argv) {
         return { kind: "passthrough" };
     const protectedPaths = protectedOperations(argv);
     if (command === "larkin-draft")
-        return { kind: "denied", reason: "larkin-draft 已移除；freshness conflict 后请重新判断并执行普通写命令" };
+        return { kind: "denied", reason: "larkin-draft 已移除；请使用受 Runtime 身份与目标绑定保护的普通写命令" };
     if (exactPath(parsed.commandArgv, ["im", "+messages-send"]))
         return uniqueProtectedOperation(protectedPaths, "send")
             ? (parsed.flags.has("--thread-id")
@@ -223,21 +223,21 @@ export function classifyLarkCliCommand(argv) {
     if (exactPath(parsed.commandArgv, ["im", "messages", "create"]) || exactPath(parsed.commandArgv, ["im", "messages", "reply"])) {
         const expected = parsed.commandArgv[2] === "create" ? "raw-create" : "raw-reply";
         return uniqueProtectedOperation(protectedPaths, expected)
-            ? { kind: "denied", reason: "该原始 IM 写入口会旁路 target freshness；请使用 +messages-send/+messages-reply" }
+            ? { kind: "denied", reason: "该原始 IM 写入口会旁路 Runtime target binding；请使用 +messages-send/+messages-reply" }
             : noncanonicalProtectedDecision();
     }
     if (["forward", "merge_forward", "urgent_phone", "urgent_sms"]
         .some((operation) => exactPath(parsed.commandArgv, ["im", "messages", operation]))) {
         const expected = `raw-${parsed.commandArgv[2]}`;
         return uniqueProtectedOperation(protectedPaths, expected)
-            ? { kind: "denied", reason: "该 IM 写入口无法建立 target freshness；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
+            ? { kind: "denied", reason: "该 IM 写入口无法建立 Runtime target binding；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
             : noncanonicalProtectedDecision();
     }
     if (["forward", "merge_forward"]
         .some((operation) => exactPath(parsed.commandArgv, ["im", "threads", operation]))) {
         const expected = `thread-${parsed.commandArgv[2]}`;
         return uniqueProtectedOperation(protectedPaths, expected)
-            ? { kind: "denied", reason: "该 IM forwarding 入口无法建立 target freshness；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
+            ? { kind: "denied", reason: "该 IM forwarding 入口无法建立 Runtime target binding；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
             : noncanonicalProtectedDecision();
     }
     if (command === "api")
@@ -347,8 +347,7 @@ function runCommentReply(argv, privateEnv, io, dependencies, store, agentId) {
     const target = targetKey ? parseDocumentCommentTarget(targetKey) : null;
     if (!target)
         throw new Error("comment reply 无法从当前 Agent Inbox 绑定文档评论 locator；先 poll 该消息且不得跨 Agent/评论回复");
-    if (!store.inboxTargetIsFresh(targetKey))
-        throw new Error("comment reply 需要先 poll 当前 document-comment target 的最新 Inbox 消息");
+    const staleCommentTarget = !store.inboxTargetIsFresh(targetKey);
     const digest = createHash("sha256").update(input.text).digest("hex");
     const ledgerKey = `${input.messageId}::${digest}`;
     const claim = store.mutateJson("freshnessState", { version: 1, cursors: {} }, (state) => {
@@ -421,6 +420,13 @@ function runCommentReply(argv, privateEnv, io, dependencies, store, agentId) {
         });
     }
     const committedWrite = !result.error && result.status === 0;
+    if (committedWrite && staleCommentTarget) {
+        io.stderr(`${JSON.stringify({
+            larkin_notice: "freshness",
+            target: targetKey,
+            hint: "Newer Inbox messages exist. Re-read the document comment context with larkin before sending a follow-up. Do not resend the same content.",
+        })}\n`);
+    }
     const currentReminder = committedWrite
         ? store.resolveCurrentReminders().filter((reminder) => reminder.deliveryTarget === targetKey).at(-1) ?? null
         : null;
@@ -464,9 +470,9 @@ function definitiveProviderRejection(result) {
     }
     return false;
 }
-function callNative(argv, env, io, dependencies) {
+function callNative(argv, env, io, dependencies, timeoutMs) {
     const native = dependencies.nativeCommand;
-    const result = (dependencies.spawn ?? spawnSync)(native?.command ?? resolveOfficialLarkCli({ spawn: dependencies.spawn, env }).command, [...(native?.argsPrefix ?? []), ...argv], { encoding: "utf8", env: { ...process.env, ...env } });
+    const result = (dependencies.spawn ?? spawnSync)(native?.command ?? resolveOfficialLarkCli({ spawn: dependencies.spawn, env }).command, [...(native?.argsPrefix ?? []), ...argv], { encoding: "utf8", env: { ...process.env, ...env }, ...(timeoutMs ? { timeout: timeoutMs } : {}) });
     return result;
 }
 function spawnNative(argv, env, io, dependencies) {
@@ -524,7 +530,7 @@ function guardedTarget(decision, argv, store) {
         const chatId = policyFlagValue(argv, "--chat-id");
         const userId = policyFlagValue(argv, "--user-id");
         if (!chatId || userId) {
-            throw new Error("Runtime +messages-send 必须只使用 Inbox 已确认的 --chat-id；--user-id 无法建立 freshness target");
+            throw new Error("Runtime +messages-send 必须使用已确认的 --chat-id；--user-id 无法建立受限 target binding");
         }
         return feishuImTarget(`chat:${chatId}`);
     }
@@ -533,7 +539,7 @@ function guardedTarget(decision, argv, store) {
         throw new Error(`${decision.operation} 写入缺少 --message-id`);
     const target = store.resolveInboxMessageTarget(messageId);
     if (!target)
-        throw new Error(`无法从 Inbox 状态确定 ${messageId} 的 target；先 poll 对应消息，禁止旁路 freshness`);
+        throw new Error(`无法从 Inbox 状态确定 ${messageId} 的 target；先 poll 对应消息，禁止旁路 target binding`);
     return feishuImTarget(target);
 }
 function recallLedgerEntry(store, messageId) {
@@ -889,22 +895,62 @@ function intentId(target, argv) {
         .update(JSON.stringify([target, argv])).digest("hex");
     return `larkin-${fingerprint.slice(0, 32)}`;
 }
-function emitFreshnessError(io, input) {
+function emitFreshnessNotice(io, input) {
     io.stderr(`${JSON.stringify({
-        ok: false,
-        identity: "bot",
-        error: { type: input.subtype === "freshness_conflict" ? "conflict" : "unavailable", subtype: input.subtype,
-            ...(input.reason ? { message: input.reason } : {}) },
+        larkin_notice: "freshness",
         target: input.target,
-        ...(input.current ? { current_cursor: input.current } : {}),
-        ...(input.messages ? { unseen_messages: input.messages } : {}),
-        next: "Reconsider the returned context, then retry the ordinary send/reply/card/recall command; history is probed again before every write.",
+        newer_messages: input.messages.length,
+        latest_message_ids: input.messages.map((message) => message.message_id),
+        hint: "Newer messages exist. Re-read this target with larkin and send a short follow-up only if they change your answer. Do not resend the same content.",
     })}\n`);
 }
 function freshnessGeneration(env) {
     return typeof env.LARKIN_RUNTIME_OBSERVATION_GENERATION === "string" && env.LARKIN_RUNTIME_OBSERVATION_GENERATION
         ? env.LARKIN_RUNTIME_OBSERVATION_GENERATION : "external";
 }
+// The post-write observation is advisory: cap it tightly so success is not
+// held hostage by a slow provider history response.
+const FRESHNESS_PROBE_TIMEOUT_MS = 500;
+function emitSoftFreshnessNotice(target, targetKey, seen, ownMessageId, env, io, dependencies, store) {
+    let timedOut = false;
+    try {
+        const gated = evaluateFreshness({
+            seen,
+            adapter: feishuImFreshnessAdapter,
+            probe: () => {
+                const result = callNative(probeArgv(target), env, io, dependencies, FRESHNESS_PROBE_TIMEOUT_MS);
+                const error = result.error;
+                timedOut = error?.code === "ETIMEDOUT"
+                    || error?.message.includes("ETIMEDOUT") === true
+                    || (result.status === null && result.signal === "SIGTERM");
+                return parseHistory(result, target, true);
+            },
+        });
+        if (gated.status === "unavailable") {
+            if (timedOut)
+                io.stderr(`lark-cli: freshness observation timed out after ${FRESHNESS_PROBE_TIMEOUT_MS}ms; no read position was recorded\n`);
+            return;
+        }
+        if (!seen && gated.status === "fresh" && gated.current) {
+            // A first authoritative observation establishes a quiet baseline from
+            // the provider's latest 20-message window, including messages that
+            // arrived while this write was in flight. This does not claim the Agent
+            // read those messages; it only enables change detection on later writes.
+            store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, freshnessGeneration(env));
+        }
+        if (gated.status !== "conflict")
+            return;
+        store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, freshnessGeneration(env));
+        const newer = gated.context.filter((message) => message.message_id !== ownMessageId);
+        if (newer.length)
+            emitFreshnessNotice(io, { target: targetKey, messages: newer });
+    }
+    catch {
+        // freshness 仅作提示：观察失败绝不能改变已完成写入的结果。
+        if (timedOut)
+            io.stderr(`lark-cli: freshness observation timed out after ${FRESHNESS_PROBE_TIMEOUT_MS}ms; no read position was recorded\n`);
+    }
+}
 function rawFlagValue(argv, flag) {
     const nativeArgv = nativeArgvBeforeBoundary(argv);
     const direct = nativeArgv.indexOf(flag);
@@ -1066,23 +1112,6 @@ function writeResponseMessage(result) {
         return null;
     }
 }
-function observeSuccessfulWrite(result, target, targetKey, store, generation) {
-    if (result.error || result.status !== 0)
-        return false;
-    try {
-        const candidate = writeResponseMessage(result);
-        if (!candidate)
-            return false;
-        const snapshot = parseHistory({ ...result, stdout: JSON.stringify({ ok: true, data: { messages: [candidate] } }) }, target);
-        const cursor = feishuImFreshnessAdapter.cursor(snapshot);
-        if (cursor)
-            store.mergeFreshnessCursor(targetKey, cursor, mergeFeishuImCursor, generation);
-        return cursor !== null;
-    }
-    catch {
-        return false;
-    }
-}
 function emitNativeResult(result, io) {
     if (result.stdout)
         io.stdout(result.stdout);
@@ -1125,35 +1154,6 @@ function emitDuplicatedRecall(io, messageId, target) {
     })}\n`);
     return 0;
 }
-function emitCommittedUnverified(result, io, input) {
-    let providerResponse;
-    try {
-        providerResponse = JSON.parse(result.stdout || "");
-    }
-    catch {
-        providerResponse = { raw_stdout: result.stdout || "" };
-    }
-    const providerDocument = providerResponse && typeof providerResponse === "object" && !Array.isArray(providerResponse)
-        ? providerResponse
-        : { provider_response: providerResponse };
-    io.stdout(`${JSON.stringify({
-        ...providerDocument,
-        ok: true,
-        committed: true,
-        verified: false,
-        cursor_advanced: false,
-        target: input.target,
-        verification: {
-            status: "unverified",
-            subtype: "post_write_unverified",
-            message: input.reason,
-            ...(input.current ? { current_cursor: input.current } : {}),
-            ...(input.messages ? { unseen_messages: input.messages } : {}),
-        },
-        ...(result.stderr ? { provider_stderr_present: true } : {}),
-    })}\n`);
-    return 0;
-}
 export function runLarkCli(argv, env = process.env, dependencies = {}) {
     const io = dependencies.io ?? defaultIo();
     let effectiveArgv = argv;
@@ -1235,20 +1235,6 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
         const targetKey = serializeFeishuImTarget(target);
         const generation = freshnessGeneration(privateEnv);
         const seen = store.readFreshnessCursor(targetKey, generation);
-        const gated = evaluateFreshness({
-            seen,
-            adapter: feishuImFreshnessAdapter,
-            probe: () => parseHistory(callNative(probeArgv(target), privateEnv, io, nativeDependencies), target, true),
-        });
-        if (gated.status === "unavailable") {
-            emitFreshnessError(io, { subtype: "freshness_unavailable", target: targetKey, reason: gated.reason });
-            return 3;
-        }
-        if (gated.status === "conflict") {
-            emitFreshnessError(io, { subtype: "freshness_conflict", target: targetKey, current: gated.current, messages: gated.context });
-            store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, generation);
-            return 3;
-        }
         if (decision.operation === "recall") {
             const claim = claimRecall(store, recallMessageId, targetKey);
             if (claim === "deleted")
@@ -1258,16 +1244,15 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
             }
             const recallWrite = callNative(botArgv(effectiveArgv, "", decision), privateEnv, io, nativeDependencies);
             if (!recallWrite.error && recallWrite.status === 0) {
-                const predictedSnapshot = {
-                    messages: gated.snapshot.messages.filter((message) => message.message_id !== recallMessageId),
-                };
-                const predictedCursor = feishuImFreshnessAdapter.cursor(predictedSnapshot);
-                finalizeSuccessfulRecall(store, recallMessageId, targetKey, predictedCursor, generation);
+                finalizeSuccessfulRecall(store, recallMessageId, targetKey, null, generation);
             }
             else if (definitiveProviderRejection(recallWrite)) {
                 finalizeFailedRecall(store, recallMessageId, targetKey);
             }
-            return emitNativeResult(recallWrite, io);
+            const code = emitNativeResult(recallWrite, io);
+            if (code === 0)
+                emitSoftFreshnessNotice(target, targetKey, seen, undefined, privateEnv, io, nativeDependencies, store);
+            return code;
         }
         if (decision.operation === "urgent-app") {
             const userIds = assertUrgentAppPreconditions(effectiveArgv, urgent.message, target, agent.feishuAppId);
@@ -1291,7 +1276,10 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
                 })}\n`);
                 return 2;
             }
-            return emitNativeResult(write, io);
+            const code = emitNativeResult(write, io);
+            if (code === 0)
+                emitSoftFreshnessNotice(target, targetKey, seen, writeResponseMessage(write)?.message_id, privateEnv, io, nativeDependencies, store);
+            return code;
         }
         const writeMessage = writeResponseMessage(write);
         const deliveryTarget = decision.operation === "send"
@@ -1331,40 +1319,10 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
             io.stderr(`lark-cli: reminder delivery audit failed: ${error instanceof Error ? error.message : String(error)}\n`);
         }
         const duplicate = memo.duplicate;
-        if (duplicate) {
-            observeSuccessfulWrite(write, target, targetKey, store, generation);
-            emitDuplicatedWrite(write, io, { target: targetKey });
-            return 0;
-        }
-        if (!write.error && write.status === 0 && !observeSuccessfulWrite(write, target, targetKey, store, generation)) {
-            const responseMessage = writeResponseMessage(write);
-            try {
-                const postSnapshot = parseHistory(callNative(probeArgv(target), privateEnv, io, nativeDependencies), target, true);
-                const postCursor = feishuImFreshnessAdapter.cursor(postSnapshot);
-                const unseenAfterWrite = feishuImFreshnessAdapter.unseen(gated.current, postSnapshot);
-                const confirmedOwnWrite = responseMessage && postCursor
-                    && unseenAfterWrite.some((message) => message.message_id === responseMessage.message_id)
-                    && unseenAfterWrite.every((message) => message.message_id === responseMessage.message_id);
-                if (!confirmedOwnWrite) {
-                    return emitCommittedUnverified(write, io, {
-                        target: targetKey,
-                        ...(postCursor ? { current: postCursor } : {}),
-                        messages: unseenAfterWrite,
-                        reason: responseMessage
-                            ? "provider write succeeded but bounded post-write probe found an additional concurrent update; cursor was not advanced"
-                            : "provider write succeeded without a message id/revision and bounded post-write probe could not identify the write; cursor was not advanced",
-                    });
-                }
-                store.mergeFreshnessCursor(targetKey, postCursor, mergeFeishuImCursor, generation);
-            }
-            catch {
-                return emitCommittedUnverified(write, io, {
-                    target: targetKey,
-                    reason: "provider write succeeded but bounded post-write confirmation was unavailable; cursor was not advanced",
-                });
-            }
-        }
-        return emitNativeResult(write, io);
+        const code = duplicate ? emitDuplicatedWrite(write, io, { target: targetKey }) : emitNativeResult(write, io);
+        if (code === 0)
+            emitSoftFreshnessNotice(target, targetKey, seen, writeMessage?.message_id, privateEnv, io, nativeDependencies, store);
+        return code;
     }
     catch (error) {
         io.stderr(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/app/lark.mjs

@@ -4,6 +4,20 @@ import { spawn } from "node:child_process";
 import * as larkinConfig from "../platform/config.mjs";
 import { assessPassthrough, PASSTHROUGH_USAGE } from "../feishu/lark-passthrough.mjs";
 import { managedOfficialLarkCli } from "./agent-lark-cli-workspace.mjs";
+import { isLarkinRuntimeContext } from "./runtime-context.mjs";
+const runtimeScopedCommands = new Set(["inbox", "reminder", "interaction", "profile", "comment"]);
+const requestedCommand = process.argv.slice(2).find((argument) => !argument.startsWith("-"));
+const runtimeContext = isLarkinRuntimeContext(process.env);
+if (!process.env.LARKIN_AGENT_ID && runtimeContext) {
+    console.error(`larkin: Runtime Agent authority is missing for "${requestedCommand ?? "lark-cli"}" (LARKIN_AGENT_ID is required). `
+        + "Runtime commands cannot fall back to the active Agent.");
+    process.exit(2);
+}
+if (!process.env.LARKIN_AGENT_ID && requestedCommand && runtimeScopedCommands.has(requestedCommand)) {
+    console.error(`larkin: Runtime Agent authority is missing for "${requestedCommand}" (LARKIN_AGENT_ID is required). `
+        + "Agent-scoped commands cannot fall back to the active Agent.");
+    process.exit(2);
+}
 const decision = assessPassthrough(process.argv.slice(2), process.env);
 if (!decision.ok) {
     console.error(`larkin: ${decision.reason}`);

package/dist/app/runtime-agent-config.mjs

@@ -240,18 +240,29 @@ function runOfficialLarkCliAsync(command, args, env, dependencies) {
         });
     });
 }
-function expectedRuntimeCommandShim() {
+function expectedRuntimeCommandShim(agent) {
     const standalone = process.env.LARKIN_STANDALONE === "1";
     const binaryEntry = fileURLToPath(new URL("./binary-entry.mjs", import.meta.url));
     const argumentsPrefix = standalone ? [] : [binaryEntry];
     const command = [process.execPath, ...argumentsPrefix].map(shellQuote).join(" ");
-    return `#!/bin/sh\nexec ${command} "$@"\n`;
+    const stateDir = path.resolve(agent.stateDir);
+    const configDir = path.resolve(stateDir, "../../..");
+    return [
+        "#!/bin/sh",
+        "export LARKIN_RUNTIME=1",
+        `export LARKIN_AGENT_ID=${shellQuote(agent.agentId)}`,
+        `export LARKIN_STATE_DIR=${shellQuote(stateDir)}`,
+        `export LARKIN_CONFIG_DIR=${shellQuote(configDir)}`,
+        `export LARKIN_HOME=${shellQuote(configDir)}`,
+        `exec ${command} "$@"`,
+        "",
+    ].join("\n");
 }
 export function installRuntimeCommandShims(agent) {
     const stateDir = path.resolve(agent.stateDir);
     const commandDir = path.join(stateDir, "runtime-bin");
     assertSecureRuntimeCommandDirectory(commandDir);
-    const fileContents = expectedRuntimeCommandShim();
+    const fileContents = expectedRuntimeCommandShim(agent);
     for (const name of ["larkin"]) {
         const file = path.join(commandDir, name);
         const temporary = path.join(commandDir, `.${name}.${process.pid}.${crypto.randomUUID()}.tmp`);
@@ -274,7 +285,7 @@ function validateRuntimeCommandShims(agent) {
         || (typeof process.getuid === "function" && stat.uid !== process.getuid())
         || (!exactMode(stat, 0o700) && !exactMode(stat, 0o500)))
         throw new Error("Runtime command shim 不安全");
-    if (fs.readFileSync(file, "utf8") !== expectedRuntimeCommandShim()) {
+    if (fs.readFileSync(file, "utf8") !== expectedRuntimeCommandShim(agent)) {
         throw new Error("Runtime command shim 内容无效");
     }
 }

package/dist/app/runtime-context.mjs

@@ -0,0 +1,17 @@
+function hasRuntimeBin(pathValue) {
+    if (!pathValue)
+        return false;
+    return pathValue.split(process.platform === "win32" ? ";" : ":")
+        .some((entry) => /(?:^|[\\/])runtime-bin$/.test(entry));
+}
+/**
+ * Runtime markers are deliberately independent of LARKIN_AGENT_ID. They keep a
+ * damaged Runtime environment from falling through to a terminal's activeAgent
+ * selection when its per-Agent identity has been stripped.
+ */
+export function isLarkinRuntimeContext(env = process.env) {
+    return env.LARKIN_RUNTIME === "1"
+        || Boolean(env.LARKIN_RUNTIME_OBSERVATION_GENERATION)
+        || Boolean(env.LARKIN_STATE_DIR)
+        || hasRuntimeBin(env.PATH);
+}

package/dist/dashboard/dashboard-config-controller.mjs

@@ -402,11 +402,17 @@ function dashboardMutation(value) {
         "set-chat-mention": ["operation", "agentId", "chatId", "value"], "set-agent-runtime": ["operation", "agentId", "runtime", "model"],
         "set-agent-model": ["operation", "agentId", "model"], "set-agent-effort": ["operation", "agentId", "effort"],
         "set-global-inbox-audit": ["operation", "enabled", "intervalMs"], "set-agent-inbox-audit": ["operation", "agentId", "enabled", "intervalMs"],
+        "set-global-processing-eye": ["operation", "enabled"], "set-agent-processing-eye": ["operation", "agentId", "enabled"],
     };
     if (!allowed[operation] || Object.keys(value).some((key) => !allowed[operation].includes(key)))
         throw new Error("unsupported operation");
     if (operation === "set-global-mention")
         return { kind: operation, value: String(value.value) };
+    if (operation === "set-global-processing-eye") {
+        if (typeof value.enabled !== "boolean")
+            throw new Error("invalid processing-eye enabled");
+        return { kind: operation, enabled: value.enabled };
+    }
     if (operation === "set-global-inbox-audit") {
         if (value.enabled !== undefined && typeof value.enabled !== "boolean")
             throw new Error("invalid inbox-audit enabled");
@@ -422,6 +428,11 @@ function dashboardMutation(value) {
             throw new Error("invalid inbox-audit interval");
         return { kind: operation, agentId, ...(value.enabled !== undefined ? { enabled: value.enabled } : {}), ...(value.intervalMs !== undefined ? { intervalMs: value.intervalMs } : {}) };
     }
+    if (operation === "set-agent-processing-eye") {
+        if (value.enabled !== "inherit" && typeof value.enabled !== "boolean")
+            throw new Error("invalid processing-eye enabled");
+        return { kind: operation, agentId, enabled: value.enabled };
+    }
     if (operation === "set-agent-mention")
         return { kind: operation, agentId, value: String(value.value) };
     if (operation === "set-chat-mention")