@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/runtime/context/skills.js

@@ -0,0 +1,283 @@
+/** 加载技能的内置工具名。 */
+export const SKILL_LOAD = "skill_load";
+/** 目录开头的说明（system 缓存段里的第一份目录）。 */
+export const SKILLS_CATALOG_HEADER = "Skills are available in this conversation. A skill is a set of instructions, sometimes with " +
+    "scripts or other files, for a specific kind of task. When a task matches a skill's description, " +
+    `call ${SKILL_LOAD} with the skill's name to read its instructions before you start; do not guess ` +
+    "what a skill says. Available skills:";
+/** 按码点比较名字（与区域设置无关，结果确定）。 */
+const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+/** 目录里每个技能描述最多的码点数（超出确定地截断；`skill_load` 仍返回完整正文）。 */
+export const CATALOG_DESCRIPTION_MAX_CHARS = 300;
+/** 折叠成一行，按码点截到 {@link CATALOG_DESCRIPTION_MAX_CHARS}。 */
+function shortDescription(d) {
+    const flat = d.replace(/\s+/g, " ").trim();
+    const cps = [...flat];
+    return cps.length <= CATALOG_DESCRIPTION_MAX_CHARS
+        ? flat
+        : `${cps.slice(0, CATALOG_DESCRIPTION_MAX_CHARS - 1).join("")}…`;
+}
+/** 一行：`- <name>: <description>`（描述折叠成一行并截断）。 */
+const line = (s) => `- ${s.name}: ${shortDescription(s.description)}`;
+const lines = (skills) => [...skills].sort(byName).map(line).join("\n");
+/** 第一份目录（进 system 缓存段），按名字排序。 */
+export function skillsCatalogText(skills) {
+    return `${SKILLS_CATALOG_HEADER}\n${lines(skills)}`;
+}
+/** 两份快照是否相同（按 id、版本、名字、描述与来源）。顺序无关。 */
+export function sameSkills(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const byId = new Map(a.map((s) => [s.id, s]));
+    if (byId.size !== a.length)
+        return false;
+    return b.every((s) => {
+        const p = byId.get(s.id);
+        return (p !== undefined &&
+            p.version === s.version &&
+            p.name === s.name &&
+            p.description === s.description &&
+            p.source === s.source);
+    });
+}
+/**
+ * Two pinned lists are the same: id, version and source in order (absent = []). Bodies follow the
+ * source. The order counts, so a reordered `skills.pinned` writes a new snapshot; that snapshot
+ * renders no message ({@link pinnedChangeText} is "" and the catalog part is skipped), and only the
+ * system segment of a new conversation or a compaction restore shows the new order. This is
+ * deliberate and consistent from the log: do not "fix" the missing message.
+ */
+export function samePinned(a, b) {
+    const x = a ?? [];
+    const y = b ?? [];
+    return (x.length === y.length &&
+        x.every((p, i) => {
+            const q = y[i];
+            return q !== undefined && p.id === q.id && p.version === q.version && p.source === q.source;
+        }));
+}
+/**
+ * Two snapshots are the same: {@link sameSkills} (`plugin` is not compared, so a snapshot written
+ * before phase B stays current), {@link samePinned} and the same `toolMap` (absent = undefined).
+ */
+export function sameSnapshot(a, b) {
+    return (sameSkills(a.skills, b.skills) && samePinned(a.pinned, b.pinned) && a.toolMap === b.toolMap);
+}
+/**
+ * The catalog differences between two snapshots. `pinnedIds` (the next snapshot's pinned ids, phase
+ * B) are left out of `updated`: a pinned skill's new body is rendered by {@link pinnedChangeText},
+ * and the pinned header says not to call `skill_load` for it.
+ */
+function catalogChanges(prev, next, pinnedIds) {
+    const before = new Map(prev.map((s) => [s.id, s]));
+    const after = new Map(next.map((s) => [s.id, s]));
+    const added = next.filter((s) => !before.has(s.id));
+    const removed = prev.filter((s) => !after.has(s.id));
+    const updated = next.filter((s) => {
+        const p = before.get(s.id);
+        return (p !== undefined &&
+            !pinnedIds?.has(s.id) &&
+            (p.version !== s.version || p.description !== s.description || p.source !== s.source));
+    });
+    return { added, updated, removed };
+}
+/**
+ * 目录变更提醒（之后的快照在所在位置以 system 消息追加）：新增、移除、更新（同一 id 的版本、描述或来源变了：
+ * 试用草稿被拒绝 / 批准了别人的同号版本时，内容变了而版本号可能不变）。
+ * `prev` 为上一份快照（没有为空）。
+ */
+export function skillsChangeText(prev, next, pinnedIds) {
+    const { added, updated, removed } = catalogChanges(prev, next, pinnedIds);
+    const parts = ["The skills available in this conversation have changed."];
+    if (added.length > 0) {
+        parts.push(`New skills (call ${SKILL_LOAD} with the name to use one):\n${lines(added)}`);
+    }
+    if (updated.length > 0) {
+        parts.push(`Updated skills (call ${SKILL_LOAD} again before relying on earlier instructions):\n${lines(updated)}`);
+    }
+    if (removed.length > 0) {
+        parts.push(`Removed skills (no longer available; do not use them): ${[...removed]
+            .sort(byName)
+            .map((s) => s.name)
+            .join(", ")}`);
+    }
+    if (next.length === 0)
+        parts.push("No skills are available now.");
+    return parts.join("\n\n");
+}
+/** 压缩摘要之后补上的「当前目录」（与 system 里的第一份不同时）：完整列出，替代之前的目录与提醒。 */
+export function skillsCurrentText(skills) {
+    if (skills.length === 0) {
+        return "No skills are available in this conversation now (this replaces any earlier list of skills).";
+    }
+    return ("Skills available in this conversation now (this replaces any earlier list of skills; call " +
+        `${SKILL_LOAD} with a name to read a skill's instructions):\n${lines(skills)}`);
+}
+// ---- Skills a person invoked (phase D spec §4.4; model-visible, English) ----
+/**
+ * The line restored after a compaction summary whose range holds inline skill invocations
+ * (`names`: distinct, code point order); empty for none. Bodies are not re-injected.
+ */
+export function invokedSkillsText(names) {
+    if (names.length === 0)
+        return "";
+    return `Skills the user invoked earlier in this conversation: ${names.join(", ")}. Call ${SKILL_LOAD} with a name to read its instructions again.`;
+}
+/** The distinct names (code point order) of the inline invocations in `events` up to `upToSeq`. */
+export function invokedSkillNames(events, upToSeq) {
+    const names = new Set();
+    for (const e of events) {
+        if (e.seq > upToSeq || e.type !== "user_message")
+            continue;
+        const s = e.payload.skill;
+        if (s?.mode === "inline")
+            names.add(s.name);
+    }
+    return [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * The latest invocation in `events` of the skill `name` (its bare name, or `<plugin>:<name>`),
+ * from the `skill` field of the `user_message`s; undefined when none.
+ */
+export function latestInvocation(events, name) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.type !== "user_message" || e.payload.skill === undefined)
+            continue;
+        const s = e.payload.skill;
+        if (s.name === name || (s.plugin !== undefined && `${s.plugin}:${s.name}` === name)) {
+            return {
+                id: s.id,
+                version: s.version,
+                source: s.source,
+                name: s.name,
+                ...(s.plugin !== undefined && { plugin: s.plugin }),
+            };
+        }
+    }
+    return undefined;
+}
+/** 日志里的全部 `skills_catalog` 事件，按 seq 升序。 */
+export function skillsCatalogEvents(events) {
+    return events
+        .filter((e) => e.type === "skills_catalog")
+        .sort((a, b) => a.seq - b.seq);
+}
+/** 最新一份快照；没有为 null。 */
+export function latestSkillsCatalog(events) {
+    return skillsCatalogEvents(events).at(-1) ?? null;
+}
+/**
+ * 进 system 缓存段的快照：第一份快照，且它之前没有任何 `model_call`（对话已经发过请求之后才有技能时，
+ * 改为在所在位置追加提醒，已发送的前缀不变）。没有为 null。
+ */
+export function systemSkillsCatalog(events) {
+    const first = skillsCatalogEvents(events)[0];
+    if (!first)
+        return null;
+    const earlierCall = events.some((e) => e.type === "model_call" && e.seq < first.seq);
+    return earlierCall ? null : first;
+}
+// ---- Pinned skills and the tool-name map (phase B, spec §9.1, §9.4; model-visible, English) ----
+/** The header of the pinned skills in the system cache segment. */
+export const PINNED_SKILLS_HEADER = "Pinned skills: the owner of this agent pinned these skills, so their instructions apply " +
+    `throughout this conversation. Follow them without calling ${SKILL_LOAD}; call ${SKILL_LOAD} ` +
+    "only to copy a pinned skill's files into the sandbox.";
+/** One pinned skill with its body. */
+export function pinnedBlock(p) {
+    return `<pinned_skill name="${p.name}" version="${p.version}">\n${p.body.trim()}\n</pinned_skill>`;
+}
+/** The pinned skills of the system snapshot (non-empty), after the catalog. */
+export function pinnedSystemText(pinned) {
+    return `${PINNED_SKILLS_HEADER}\n\n${pinned.map(pinnedBlock).join("\n\n")}`;
+}
+/**
+ * The pinned change notice between two snapshots ({@link samePinned} false): each entry that is new
+ * or has another version or source, with its whole body; then the names of the removed ones.
+ * Empty when nothing changed.
+ */
+export function pinnedChangeText(prev, next) {
+    const before = new Map((prev ?? []).map((p) => [p.id, p]));
+    const after = new Set((next ?? []).map((p) => p.id));
+    const parts = [];
+    for (const p of next ?? []) {
+        const was = before.get(p.id);
+        if (was && was.version === p.version && was.source === p.source)
+            continue;
+        parts.push(`Pinned skill "${p.name}" (version ${p.version}) now applies to this conversation and ` +
+            `replaces any previous version of it:\n\n${pinnedBlock(p)}`);
+    }
+    const removed = (prev ?? []).filter((p) => !after.has(p.id)).map((p) => p.name);
+    if (removed.length > 0) {
+        parts.push(`Pinned skills removed (their pinned instructions no longer apply): ${removed.join(", ")}`);
+    }
+    return parts.join("\n\n");
+}
+/** The pinned skills after a compaction summary, when they differ from the system snapshot's. */
+export function pinnedCurrentText(pinned) {
+    if (!pinned || pinned.length === 0) {
+        return "No skills are pinned now (this replaces any earlier pinned skills).";
+    }
+    return `Pinned skills now (this replaces any earlier pinned skills):\n\n${pinned
+        .map(pinnedBlock)
+        .join("\n\n")}`;
+}
+/** The tool-name map change notice (the map differs from the previous one). */
+export function toolMapChangeText(next) {
+    return next === undefined
+        ? "The Claude Code tool-name map no longer applies."
+        : `The following tool-name map now applies:\n${next}`;
+}
+/**
+ * The one system message of a later snapshot: the catalog change (when the skills differ, or when
+ * nothing else differs: logs before phase B render exactly as before), the pinned change, the
+ * tool-name map change; joined by blank lines.
+ */
+export function snapshotChangeText(prev, next) {
+    const prevSkills = prev?.skills ?? [];
+    const pinnedDiff = !samePinned(prev?.pinned, next.pinned);
+    const mapDiff = prev?.toolMap !== next.toolMap;
+    // a snapshot with pinned skills leaves them out of the "Updated skills" list; when that leaves no
+    // catalog change, the catalog text is skipped (the pinned change carries the message). Logs
+    // without `pinned` render exactly as before.
+    const pinnedIds = next.pinned && next.pinned.length > 0 ? new Set(next.pinned.map((p) => p.id)) : undefined;
+    const c = catalogChanges(prevSkills, next.skills, pinnedIds);
+    const catalogDiff = pinnedIds
+        ? c.added.length + c.updated.length + c.removed.length > 0
+        : !sameSkills(prevSkills, next.skills);
+    const parts = [];
+    if (catalogDiff || (!pinnedDiff && !mapDiff)) {
+        parts.push(skillsChangeText(prevSkills, next.skills, pinnedIds));
+    }
+    if (pinnedDiff)
+        parts.push(pinnedChangeText(prev?.pinned, next.pinned));
+    if (mapDiff)
+        parts.push(toolMapChangeText(next.toolMap));
+    return parts.filter((p) => p !== "").join("\n\n");
+}
+/**
+ * What follows a compaction summary when the covered snapshot is not the system one: today's
+ * current catalog (when the skills differ from the system snapshot's), the current pinned skills
+ * (when they differ), the tool-name map (when it differs); joined by blank lines, "" for nothing.
+ */
+export function snapshotCurrentText(system, covered) {
+    const parts = [];
+    if (!sameSkills(system?.skills ?? [], covered.skills)) {
+        parts.push(skillsCurrentText(covered.skills));
+    }
+    if (!samePinned(system?.pinned, covered.pinned))
+        parts.push(pinnedCurrentText(covered.pinned));
+    if (system?.toolMap !== covered.toolMap) {
+        parts.push(toolMapChangeText(covered.toolMap));
+    }
+    return parts.join("\n\n");
+}
+/** The system snapshot's text after the agent's instructions: catalog, pinned skills, tool map. */
+export function snapshotSystemText(s) {
+    let text = skillsCatalogText(s.skills);
+    if (s.pinned && s.pinned.length > 0)
+        text += `\n\n${pinnedSystemText(s.pinned)}`;
+    if (s.toolMap !== undefined)
+        text += `\n\n${s.toolMap}`;
+    return text;
+}

package/dist/runtime/context/tokens.d.ts

@@ -0,0 +1,19 @@
+import type { ModelMessage, ModelRequest } from "@capybara-hq/plugin-sdk";
+/**
+ * 估算请求的输入 token 数：ASCII 字符数 ÷ 4 + 非 ASCII 字符数 × 1，向上取整。
+ * 故意不用 BPE 分词器：长段中文分词会阻塞事件循环（可靠性清单 A）；偏差由 `calibrate` 按真实用量校正。
+ * 工具定义（名字、描述、inputSchema 的 JSON）计入。供应商私有数据（opaque）大小未知，不计入。
+ * 媒体块：传了 `mediaTokens`（`buildModelRequest` 按行信息算好的：图片 1600、PDF 页数 × 1000 等）时
+ * 直接用它、不再逐块估算；否则按块兜底（图片 1600，文档按字节 ÷ 3，不解码）。
+ */
+export declare function estimateTokens(messages: ModelMessage[], system: ModelRequest["system"], tools?: ModelRequest["tools"], mediaTokens?: number): number;
+/**
+ * 用上一轮的真实输入 token 数校正估算：乘以 `inputTokens / estimate`，比例夹在 0.5–3。
+ * 没有上一轮（或上一轮估算为 0）时原样返回。
+ */
+export declare function calibrate(estimate: number, lastActual: {
+    estimate: number;
+    inputTokens: number;
+} | null): number;
+/** Token estimate of a text of `bytes` UTF-8 bytes read as ASCII (the rule above: ÷ 4, rounded up). */
+export declare function textBytesTokens(bytes: number): number;

package/dist/runtime/context/tokens.js

@@ -0,0 +1,104 @@
+import { IMAGE_TOKENS, pdfTokens } from "./build.js";
+/** 文档按「字节数 ÷ 3」估算。 */
+const BYTES_PER_TOKEN = 3;
+/** 未解析的文档引用（不应出现在发出的请求里）的保守估算。 */
+const UNRESOLVED_DOCUMENT_TOKENS = 1000;
+/** base64 解码后的字节数（按长度计算，不解码）。 */
+function base64Bytes(data) {
+    const pad = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor((data.length / 4) * 3) - pad);
+}
+/**
+ * 媒体块的兜底估算（没有构建时算好的 `mediaTokens` 时用，不解码）：图片固定 1600；PDF 按大小换算页数
+ * （见 `pdfTokens`，绝不按字节 ÷ 3）；其他文档按字节 ÷ 3。
+ */
+function blockMediaTokens(b) {
+    if (b.type === "image")
+        return IMAGE_TOKENS;
+    if (b.source.kind !== "base64")
+        return UNRESOLVED_DOCUMENT_TOKENS;
+    const size = base64Bytes(b.source.data);
+    if (b.mediaType === "application/pdf")
+        return pdfTokens(size, null);
+    return Math.ceil(size / BYTES_PER_TOKEN);
+}
+/** 校正比例的上下限：单轮真实值偏差再大，也不让估算失控。 */
+const MIN_RATIO = 0.5;
+const MAX_RATIO = 3;
+/** 逐个 UTF-16 码元计数：ASCII 与非 ASCII 分开累加。线性扫描，不做分词。 */
+class CharCounter {
+    ascii = 0;
+    other = 0;
+    add(text) {
+        let ascii = 0;
+        const len = text.length;
+        for (let i = 0; i < len; i++) {
+            if (text.charCodeAt(i) < 128)
+                ascii++;
+        }
+        this.ascii += ascii;
+        this.other += len - ascii;
+    }
+    tokens() {
+        return Math.ceil(this.ascii / 4 + this.other);
+    }
+}
+/**
+ * 估算请求的输入 token 数：ASCII 字符数 ÷ 4 + 非 ASCII 字符数 × 1，向上取整。
+ * 故意不用 BPE 分词器：长段中文分词会阻塞事件循环（可靠性清单 A）；偏差由 `calibrate` 按真实用量校正。
+ * 工具定义（名字、描述、inputSchema 的 JSON）计入。供应商私有数据（opaque）大小未知，不计入。
+ * 媒体块：传了 `mediaTokens`（`buildModelRequest` 按行信息算好的：图片 1600、PDF 页数 × 1000 等）时
+ * 直接用它、不再逐块估算；否则按块兜底（图片 1600，文档按字节 ÷ 3，不解码）。
+ */
+export function estimateTokens(messages, system, tools = [], mediaTokens) {
+    const c = new CharCounter();
+    let media = 0;
+    for (const s of system)
+        c.add(s.text);
+    for (const t of tools) {
+        c.add(t.name);
+        c.add(t.description);
+        c.add(JSON.stringify(t.inputSchema) ?? "");
+    }
+    for (const m of messages) {
+        if (m.role === "system") {
+            c.add(m.content);
+            continue;
+        }
+        for (const b of m.content) {
+            switch (b.type) {
+                case "text":
+                case "thinking":
+                    c.add(b.text);
+                    break;
+                case "tool_call":
+                    c.add(b.name);
+                    c.add(JSON.stringify(b.input) ?? "");
+                    break;
+                case "tool_result":
+                    c.add(b.content);
+                    break;
+                case "image":
+                case "document":
+                    if (mediaTokens === undefined)
+                        media += blockMediaTokens(b);
+                    break;
+            }
+        }
+    }
+    return c.tokens() + (mediaTokens ?? media);
+}
+/**
+ * 用上一轮的真实输入 token 数校正估算：乘以 `inputTokens / estimate`，比例夹在 0.5–3。
+ * 没有上一轮（或上一轮估算为 0）时原样返回。
+ */
+export function calibrate(estimate, lastActual) {
+    if (!lastActual || lastActual.estimate <= 0)
+        return estimate;
+    const ratio = Math.min(MAX_RATIO, Math.max(MIN_RATIO, lastActual.inputTokens / lastActual.estimate));
+    return Math.ceil(estimate * ratio);
+}
+/** Token estimate of a text of `bytes` UTF-8 bytes read as ASCII (the rule above: ÷ 4, rounded up). */
+export function textBytesTokens(bytes) {
+    return Math.ceil(bytes / 4);
+}

package/dist/runtime/conversation-lock.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+/** 会话运行锁的默认 TTL（毫秒）：持有方每 `ttlMs / 3` 续租一次。 */
+export declare const CONVERSATION_LOCK_TTL_MS = 30000;
+/** 本进程持有的会话运行锁。 */
+export interface Lease {
+    readonly conversationId: string;
+    readonly runId: string;
+    /** 续租时发现锁已不属于自己（过期后被他人取得）；此后不再续租。 */
+    readonly lost: boolean;
+    /** 立即续租一次；锁已不属于自己 → false（并标记 lost）。 */
+    renew(): Promise<boolean>;
+    /** 停止续租并释放（只删除自己持有的锁）。 */
+    release(): Promise<void>;
+    /** 只停止续租、不释放：锁在 TTL 后自然过期（停机超出预算、交给其他副本时使用）。 */
+    abandon(): void;
+    /** 注册「锁已丢失」回调（续租发现锁不再属于自己时调用一次；已丢失则立即调用）。 */
+    onLost(cb: () => void): void;
+}
+/**
+ * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
+ * 带 TTL；持有期间由本进程的定时器每 `ttlMs / 3` 续租（本进程持有的锁的续租，允许的进程内定时器）。
+ * 持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ */
+export declare class ConversationLock {
+    private readonly redis;
+    private readonly log?;
+    private readonly keyPrefix;
+    /** `keyPrefix`：同样语义、按会话互斥的其他用途用别的前缀（如渠道出站投递 `capk:channel-deliver:`）。 */
+    constructor(redis: Redis, log?: Pick<Logger, "warn"> | undefined, keyPrefix?: string);
+    private lockKey;
+    acquire(conversationId: string, runId: string, ttlMs?: number): Promise<Lease | null>;
+    /**
+     * 释放某个运行持有的锁（只在仍由该 runId 持有时删除），不需要 Lease：用于 BullMQ 已判定任务失败
+     * （例如持有者崩溃、stalled 次数超限）后清理死去持有者留下的锁，不必等 TTL 过期。
+     */
+    releaseFor(conversationId: string, runId: string): Promise<void>;
+    /** 当前持有者的 runId；无人持有 → null。 */
+    holder(conversationId: string): Promise<string | null>;
+}

package/dist/runtime/conversation-lock.js

@@ -0,0 +1,97 @@
+/** 会话运行锁的默认 TTL（毫秒）：持有方每 `ttlMs / 3` 续租一次。 */
+export const CONVERSATION_LOCK_TTL_MS = 30_000;
+/** 会话运行锁的键前缀。 */
+const RUN_LOCK_PREFIX = "capk:conv-run:";
+const RENEW = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
+end
+return 0
+`;
+const RELEASE = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+`;
+/**
+ * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
+ * 带 TTL；持有期间由本进程的定时器每 `ttlMs / 3` 续租（本进程持有的锁的续租，允许的进程内定时器）。
+ * 持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ */
+export class ConversationLock {
+    redis;
+    log;
+    keyPrefix;
+    /** `keyPrefix`：同样语义、按会话互斥的其他用途用别的前缀（如渠道出站投递 `capk:channel-deliver:`）。 */
+    constructor(redis, log, keyPrefix = RUN_LOCK_PREFIX) {
+        this.redis = redis;
+        this.log = log;
+        this.keyPrefix = keyPrefix;
+    }
+    lockKey(conversationId) {
+        return `${this.keyPrefix}${conversationId}`;
+    }
+    async acquire(conversationId, runId, ttlMs = CONVERSATION_LOCK_TTL_MS) {
+        const key = this.lockKey(conversationId);
+        const ok = await this.redis.set(key, runId, "PX", ttlMs, "NX");
+        if (ok !== "OK")
+            return null;
+        const redis = this.redis;
+        const log = this.log;
+        let lost = false;
+        let timer;
+        const lostCallbacks = [];
+        const stop = () => {
+            clearInterval(timer);
+            timer = undefined;
+        };
+        const lease = {
+            conversationId,
+            runId,
+            get lost() {
+                return lost;
+            },
+            async renew() {
+                if (lost)
+                    return false;
+                const r = Number(await redis.eval(RENEW, 1, key, runId, ttlMs));
+                if (r !== 1) {
+                    lost = true;
+                    stop();
+                    log?.warn("conversation run lock lost", { conversationId, runId });
+                    for (const cb of lostCallbacks.splice(0))
+                        cb();
+                }
+                return r === 1;
+            },
+            async release() {
+                stop();
+                await redis.eval(RELEASE, 1, key, runId);
+            },
+            abandon: stop,
+            onLost(cb) {
+                if (lost)
+                    cb();
+                else
+                    lostCallbacks.push(cb);
+            },
+        };
+        timer = setInterval(() => {
+            lease.renew().catch((err) => log?.warn("conversation run lock renew failed", { err }));
+        }, Math.max(1, Math.floor(ttlMs / 3)));
+        timer.unref();
+        return lease;
+    }
+    /**
+     * 释放某个运行持有的锁（只在仍由该 runId 持有时删除），不需要 Lease：用于 BullMQ 已判定任务失败
+     * （例如持有者崩溃、stalled 次数超限）后清理死去持有者留下的锁，不必等 TTL 过期。
+     */
+    async releaseFor(conversationId, runId) {
+        await this.redis.eval(RELEASE, 1, this.lockKey(conversationId), runId);
+    }
+    /** 当前持有者的 runId；无人持有 → null。 */
+    holder(conversationId) {
+        return this.redis.get(this.lockKey(conversationId));
+    }
+}

package/dist/runtime/hook-calls.d.ts

@@ -0,0 +1,84 @@
+import type { AvailableHook, HookModelRequest, HookParentScope, HookPayloads, HookScope, Logger, ModelRequest } from "@capybara-hq/plugin-sdk";
+import type { AppendEvent, EventLog } from "../conversations/event-log.js";
+import type { EventPayload } from "../conversations/events.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { HookOutcome, HookRegistry } from "../extensions/hooks.js";
+import { audit } from "../identity/audit.js";
+/** What the runtime needs from the host's hook registry (absent in eval replays). */
+export type HookRunner = Pick<HookRegistry, "run" | "has">;
+/**
+ * Kind of the conversation a run belongs to; hooks fire for `chat` and `subagent` (F10, P-18,
+ * sub-agents spec §11), never for `eval`.
+ */
+export type ConversationKindForHooks = "chat" | "eval" | "subagent";
+/** A denial as `run()` returns it. */
+export type HookDenial = Extract<HookOutcome, {
+    allowed: false;
+}>;
+/**
+ * The scope for hook payloads, or null when hooks must not fire: no registry (eval replays omit it),
+ * a conversation that is neither `chat` nor `subagent`, or missing identity fields. A sub-agent's
+ * scope carries `parent` (where it was dispatched from).
+ */
+export declare function hookScope(hooks: HookRunner | undefined, s: {
+    conversationKind?: ConversationKindForHooks;
+    orgId: string;
+    accountId?: string;
+    agentId?: string;
+    agentVersion: number;
+    conversationId: string;
+    runId: string;
+    parent?: HookParentScope | undefined;
+}): HookScope | null;
+/**
+ * Fires observe-only hooks (`model.response`, `tool.postExecute`) without waiting. `signal` must be
+ * run-scoped (not a per-call controller aborted when the call ends), or the hooks would be cut off.
+ */
+export declare function fireObserve<K extends "model.response" | "tool.postExecute">(hooks: HookRunner, mount: K, payload: HookPayloads[K], signal: AbortSignal, log: Pick<Logger, "warn">): void;
+/**
+ * The `model.request` payload's request (F10, I-3): the request sent to the provider with every image
+ * and document block replaced by a {@link HookMediaPlaceholder} (`kind`, `mediaType`, decoded `size`),
+ * so hook payloads carry neither media bytes nor attachment ids. Media never sits outside user
+ * messages, but every message is projected anyway. Building the copy also keeps the per-call clone
+ * and freeze of the payload small. A `ref` source should never reach here (the kernel resolves refs
+ * before sending); it becomes a placeholder of size 0 and logs a warning.
+ */
+export declare function hookRequestOf(request: ModelRequest, log?: Pick<Logger, "warn">): HookModelRequest;
+/** Where a denial is recorded (conversation, run, actor and the idem key of its `hook_denied`). */
+export interface DenialSite {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    accountId?: string;
+    agentId?: string;
+    idemKey: string;
+}
+/** The `hook_denied` event of a denial (not model-visible: request building skips it). */
+export declare function hookDeniedEvent(at: DenialSite, mount: Extract<AvailableHook, "model.request" | "tool.preExecute">, denial: HookDenial, where: {
+    step: number;
+    attempt?: number;
+    callId?: string;
+}): AppendEvent & {
+    type: "hook_denied";
+    payload: EventPayload<"hook_denied">;
+};
+/**
+ * The `hook.denied` audit entry of a denial. For an R10 denial (`preflight`) it says that no plugin ran
+ * and that the named plugin is only the first policy plugin on the mount.
+ */
+export declare function hookDeniedAudit(at: DenialSite, payload: EventPayload<"hook_denied">, denial: HookDenial): AuditEntry;
+/** Audit entry shape (the argument of `audit()`). */
+export type AuditEntry = Parameters<typeof audit>[1];
+/**
+ * Writes a model request's `hook_denied` event and its audit entry in one transaction (the tool path
+ * writes them with the `tool_result` instead). Idempotent by idem key: a resumed run that finds the
+ * denial rethrows it before running the hooks again, so no second audit entry is written.
+ */
+export declare function recordHookDenial(d: {
+    db: KernelDb;
+    eventLog: EventLog;
+}, at: DenialSite, mount: Extract<AvailableHook, "model.request" | "tool.preExecute">, denial: HookDenial, where: {
+    step: number;
+    attempt?: number;
+    callId?: string;
+}): Promise<void>;