@zmzai/agent-framework 0.1.0

package/dist/core/permission/engine.js

@@ -0,0 +1,131 @@
+import { newPermissionRequestId } from "../session/ids.js";
+import { evaluateRules } from "../permission/ruleset.js";
+export class RejectedError extends Error {
+    feedback;
+    constructor(message, feedback) {
+        super(feedback ? `${message}（用户反馈：${feedback}）` : message);
+        this.feedback = feedback;
+        this.name = "RejectedError";
+    }
+}
+export class PermissionEngine {
+    sessionId;
+    options;
+    /** Rulesets in ascending precedence: built-in defaults → agent preset → session. */
+    rulesets;
+    sessionRules = [];
+    pending = new Map();
+    disposed = false;
+    /** 临时允许缓存：once 批准后同一 run 内相同模式直接放行（F1，避免 Agent
+     *  二次调用相同命令时重复打断用户）。run 结束（dispose）时清空，下次 run
+     *  重新询问。键 = permission + pattern（bash 的 pattern 即命令原文）。 */
+    onceAllowed = new Set();
+    constructor(sessionId, baseRulesets, sessionRules = [], options = {}) {
+        this.sessionId = sessionId;
+        this.options = options;
+        this.rulesets = [...baseRulesets, this.sessionRules];
+        this.sessionRules.push(...sessionRules);
+    }
+    onceKey(permission, pattern) {
+        return `${permission}\u0000${pattern}`;
+    }
+    evaluate(permission, pattern) {
+        return evaluateRules(this.rulesets, permission, pattern);
+    }
+    /** Snapshot of the effective session rules (for persistence on reply "always"). */
+    get sessionRuleset() {
+        return [...this.sessionRules];
+    }
+    revoke(permission, patterns) {
+        const before = this.sessionRules.length;
+        const patternSet = new Set(patterns);
+        const retained = this.sessionRules.filter((rule) => !(rule.permission === permission && patternSet.has(rule.pattern)));
+        this.sessionRules.splice(0, this.sessionRules.length, ...retained);
+        return retained.length !== before;
+    }
+    get pendingRequests() {
+        return [...this.pending.values()].map((entry) => entry.request);
+    }
+    async ask(input) {
+        if (this.disposed)
+            throw new RejectedError("权限引擎已关闭（服务重启或会话结束），请重试");
+        const patterns = input.patterns.length ? input.patterns : ["*"];
+        // 已 once 批准的相同模式直接放行，不重复询问。
+        const undecided = patterns.filter((pattern) => this.evaluate(input.permission, pattern) !== "allow" && !this.onceAllowed.has(this.onceKey(input.permission, pattern)));
+        if (undecided.length === 0)
+            return "once";
+        const request = {
+            id: newPermissionRequestId(),
+            sessionId: input.sessionId,
+            permission: input.permission,
+            patterns: undecided,
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+            always: input.always ?? [...undecided],
+            ...(input.tool ? { tool: input.tool } : {}),
+        };
+        const decision = new Promise((resolve) => {
+            this.pending.set(request.id, { request, resolve });
+        });
+        await this.options.onAsked?.(request);
+        const { reply, feedback } = await decision;
+        await this.options.onReplied?.(request, reply);
+        if (reply === "reject") {
+            throw new RejectedError(`权限被拒绝：${input.permission} ${undecided.join(", ")}`, feedback);
+        }
+        if (reply === "once") {
+            // F1：本 run 内相同命令/模式不再询问。
+            for (const pattern of request.patterns)
+                this.onceAllowed.add(this.onceKey(input.permission, pattern));
+        }
+        if (reply === "always") {
+            for (const pattern of request.always) {
+                const rule = { permission: input.permission, pattern, action: "allow" };
+                this.sessionRules.push(rule);
+                await this.options.onSessionRuleAdded?.(input.sessionId, rule);
+            }
+            // Auto-resolve other pending requests in this session now fully covered.
+            for (const [id, entry] of [...this.pending]) {
+                const covered = entry.request.patterns.every((pattern) => this.evaluate(entry.request.permission, pattern) === "allow");
+                if (covered) {
+                    this.pending.delete(id);
+                    entry.resolve({ reply: "always" });
+                    await this.options.onReplied?.(entry.request, "always");
+                }
+            }
+        }
+        return reply;
+    }
+    /** Resolves a pending request. Returns false when the id is unknown (already
+     *  resolved or session restarted — callers map that to a 404/conflict).
+     *
+     *  Harness-course retrofit（tutorial-harness 08，OpenCode 拒绝级联）：用户拒绝一个
+     *  请求时，同会话排队中的其他待批请求一并拒绝——用户说“不”的时候，
+     *  不该让后面的请求继续敲门。批准不连坐，拒绝连坐。 */
+    reply(requestId, reply, feedback) {
+        const entry = this.pending.get(requestId);
+        if (!entry)
+            return false;
+        this.pending.delete(requestId);
+        entry.resolve({ reply, feedback });
+        if (reply === "reject") {
+            for (const [id, other] of [...this.pending]) {
+                this.pending.delete(id);
+                // 级联拒绝不复用原反馈：这些请求没被单独审过，理由必须如实说是连坐
+                other.resolve({ reply: "reject", feedback: "用户已拒绝同会话的另一个请求，本次一并拒绝" });
+            }
+        }
+        return true;
+    }
+    /** Rejects everything still pending — used on abort and process teardown so
+     *  tool calls never hang forever (spec §5.4: restart semantics). Also clears
+     *  the once-allowed cache so the next run asks again. */
+    dispose(reason = "会话已中止或服务重启，请重试") {
+        this.disposed = true;
+        for (const [, entry] of [...this.pending]) {
+            entry.resolve({ reply: "reject", feedback: reason });
+        }
+        this.pending.clear();
+        this.onceAllowed.clear();
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/permission/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/core/permission/engine.ts"],"names":[],"mappings":"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"}

package/dist/core/permission/ruleset.d.ts

@@ -0,0 +1,30 @@
+/** Permission ruleset DSL (spec §5.1).
+ *
+ *  A ruleset is an ordered list of rules; the LAST matching rule wins and the
+ *  default action when nothing matches is "ask". Config syntax mirrors
+ *  opencode.json: a bare action string, or a map of permission -> action or
+ *  pattern->action map. */
+export type Action = "allow" | "deny" | "ask";
+export type Rule = {
+    permission: string;
+    pattern: string;
+    action: Action;
+    expiresAt?: string;
+};
+export type Ruleset = Rule[];
+export type PermissionConfig = Action | Record<string, Action | Record<string, Action>>;
+/** Well-known permission keys (spec §5.1). Tools may introduce additional keys
+ *  (e.g. future MCP `server_*`); the engine treats keys as opaque strings and
+ *  matches them with wildcards. */
+export declare const PERMISSIONS: readonly ["read", "edit", "bash", "glob", "grep", "list", "webfetch", "connector", "task", "todo", "external_directory"];
+/** Converts config syntax into a flat ruleset. Key order in the config object
+ *  is preserved, so later keys override earlier ones for overlapping matches. */
+export declare function rulesetFromConfig(config: PermissionConfig): Ruleset;
+/** Glob-style wildcard match: `*` matches any run of characters (including
+ *  path separators), `?` matches one character. Same spirit as OpenCode's
+ *  Wildcard.match — patterns are not filesystem paths, just strings. */
+export declare function wildcardMatch(pattern: string, value: string): boolean;
+/** Core evaluation: last matching rule across all rulesets (in order) wins.
+ *  Later rulesets in the array have higher precedence. Default: "ask". */
+export declare function evaluateRules(rulesets: Ruleset[], permission: string, pattern: string): Action;
+//# sourceMappingURL=ruleset.d.ts.map

package/dist/core/permission/ruleset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset.d.ts","sourceRoot":"","sources":["../../../src/core/permission/ruleset.ts"],"names":[],"mappings":"AAAA;;;;;2BAK2B;AAE3B,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAE9C,MAAM,MAAM,IAAI,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/F,MAAM,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC;AAE7B,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAExF;;mCAEmC;AACnC,eAAO,MAAM,WAAW,0HAYd,CAAC;AAEX;iFACiF;AACjF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAanE;AAED;;wEAEwE;AACxE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAqBrE;AAED;0EAC0E;AAC1E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAW9F"}

package/dist/core/permission/ruleset.js

@@ -0,0 +1,85 @@
+/** Permission ruleset DSL (spec §5.1).
+ *
+ *  A ruleset is an ordered list of rules; the LAST matching rule wins and the
+ *  default action when nothing matches is "ask". Config syntax mirrors
+ *  opencode.json: a bare action string, or a map of permission -> action or
+ *  pattern->action map. */
+/** Well-known permission keys (spec §5.1). Tools may introduce additional keys
+ *  (e.g. future MCP `server_*`); the engine treats keys as opaque strings and
+ *  matches them with wildcards. */
+export const PERMISSIONS = [
+    "read",
+    "edit", // covers write/edit/apply_patch
+    "bash",
+    "glob",
+    "grep",
+    "list",
+    "webfetch",
+    "connector",
+    "task",
+    "todo",
+    "external_directory",
+];
+/** Converts config syntax into a flat ruleset. Key order in the config object
+ *  is preserved, so later keys override earlier ones for overlapping matches. */
+export function rulesetFromConfig(config) {
+    if (typeof config === "string")
+        return [{ permission: "*", pattern: "*", action: config }];
+    const rules = [];
+    for (const [permission, value] of Object.entries(config)) {
+        if (typeof value === "string") {
+            rules.push({ permission, pattern: "*", action: value });
+        }
+        else {
+            for (const [pattern, action] of Object.entries(value)) {
+                rules.push({ permission, pattern, action });
+            }
+        }
+    }
+    return rules;
+}
+/** Glob-style wildcard match: `*` matches any run of characters (including
+ *  path separators), `?` matches one character. Same spirit as OpenCode's
+ *  Wildcard.match — patterns are not filesystem paths, just strings. */
+export function wildcardMatch(pattern, value) {
+    let p = 0;
+    let v = 0;
+    let star = -1;
+    let starValue = 0;
+    while (v < value.length) {
+        if (p < pattern.length && (pattern[p] === "?" || pattern[p] === value[v])) {
+            p++;
+            v++;
+        }
+        else if (p < pattern.length && pattern[p] === "*") {
+            star = p++;
+            starValue = v;
+        }
+        else if (star !== -1) {
+            p = star + 1;
+            v = ++starValue;
+        }
+        else {
+            return false;
+        }
+    }
+    while (p < pattern.length && pattern[p] === "*")
+        p++;
+    return p === pattern.length;
+}
+/** Core evaluation: last matching rule across all rulesets (in order) wins.
+ *  Later rulesets in the array have higher precedence. Default: "ask". */
+export function evaluateRules(rulesets, permission, pattern) {
+    let result = "ask";
+    for (const ruleset of rulesets) {
+        for (const rule of ruleset) {
+            if (rule.expiresAt && Date.parse(rule.expiresAt) <= Date.now())
+                continue;
+            if (wildcardMatch(rule.permission, permission) && wildcardMatch(rule.pattern, pattern)) {
+                result = rule.action;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=ruleset.js.map

package/dist/core/permission/ruleset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset.js","sourceRoot":"","sources":["../../../src/core/permission/ruleset.ts"],"names":[],"mappings":"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"}

package/dist/core/runtime/compaction.d.ts

@@ -0,0 +1,59 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+/** Framework compaction (spec §8.3): when the PI-visible context approaches the
+ *  model's window, replace the older history with a generated summary and keep
+ *  a recent tail. Wired through PI's transformContext — the loop calls it
+ *  before every LLM request. The emitted `compaction` part marks the boundary
+ *  in the transcript (the full pre-compaction messages stay persisted in the
+ *  framework store; only the model's working context is condensed). */
+export type CompactionOptions = {
+    /** Cheap model used to write the summary (the relay's small model). */
+    summaryModel: Model<Api>;
+    /** Main model's context window (tokens). */
+    contextWindow: number;
+    /** Reserve headroom for the summary prompt + next reply. */
+    reserveTokens?: number;
+    /** How many recent messages to keep verbatim. */
+    keepRecentMessages?: number;
+    /** Streams one completion from the summary model. */
+    streamSummary: (messages: AgentMessage[]) => Promise<string>;
+    /** Called when a compaction happens so the runner can emit the part. */
+    onCompacted?: (summary: string, tokensBefore: number) => void;
+    /** Called when a compaction attempt fails ("summary-empty" | "summary-inflated");
+     *  after any failure the transform stops retrying for this run (失败记忆). */
+    onCompactionFailed?: (reason: "summary-empty" | "summary-inflated") => void | Promise<void>;
+};
+/** Returns a transformContext that compacts when over threshold.
+ *
+ * Harness-course retrofits (tutorial-harness 05/07):
+ *  - 膨胀拒绝（Gemini chatCompressionService）：摘要比被压区还长时作废本次压缩，
+ *    宁可用全量上下文也不换一份负收益的摘要。
+ *  - 失败记忆（Gemini hasFailedCompressionAttempt）：摘要调用失败或膨胀后记住这次
+ *    失败，后续不再反复烧摘要 token；失败不静默，通过 onCompactionFailed 上报。
+ */
+export declare function createCompactionTransform(options: CompactionOptions): (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+/** One-shot completion via an AssistantMessageEventStream (relay streamFn
+ *  shape): drives the stream to completion and returns its full text. Used for
+ *  summary generation and async title generation (spec §13.2). */
+export declare function streamOneText(streamFn: (model: Model<Api>, context: {
+    systemPrompt: string;
+    messages: AgentMessage[];
+}) => Promise<{
+    result(): Promise<{
+        content?: unknown;
+    }>;
+}> | {
+    result(): Promise<{
+        content?: unknown;
+    }>;
+}, model: Model<Api>, systemPrompt: string, messages: AgentMessage[]): Promise<string>;
+/** Builds the compaction transform for a run from a relay stream fn + model
+ *  refs. Returns undefined when compaction is disabled (no summaryModel). */
+export declare function buildCompactionTransform(input: {
+    enabled: boolean;
+    contextWindow: number;
+    summaryModel: Model<Api> | null;
+    streamOne: (model: Model<Api>, messages: AgentMessage[]) => Promise<string>;
+    onCompacted?: (summary: string, tokensBefore: number) => void;
+}): ((messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>) | undefined;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/core/runtime/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;uEAKuE;AAEvE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uEAAuE;IACvE,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9D;8EAC0E;IAC1E,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,GAAG,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F,CAAC;AAiCF;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAuCjJ;AAED;;kEAEkE;AAClE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,KAAK,OAAO,CAAC;IAAE,MAAM,IAAI,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,GAAG;IAAE,MAAM,IAAI,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,EAClM,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,YAAY,EAAE,GACvB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;6EAC6E;AAC7E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,GAAG,SAAS,CAQ5F"}

package/dist/core/runtime/compaction.js

@@ -0,0 +1,108 @@
+/** Rough token estimate (chars/4) — good enough for a threshold trigger; the
+ *  precise accounting happens provider-side. */
+function estimateTokens(messages) {
+    let total = 0;
+    for (const message of messages) {
+        const content = message.content;
+        if (typeof content === "string")
+            total += Math.ceil(content.length / 4);
+        else if (Array.isArray(content)) {
+            for (const block of content) {
+                if (typeof block === "object" && block !== null && typeof block.text === "string") {
+                    total += Math.ceil((block.text).length / 4);
+                }
+            }
+        }
+        if (message.role === "toolResult") {
+            const blocks = message.content;
+            if (Array.isArray(blocks)) {
+                for (const block of blocks) {
+                    if (typeof block === "object" && block !== null && typeof block.text === "string") {
+                        total += Math.ceil((block.text).length / 4);
+                    }
+                }
+            }
+        }
+    }
+    return total;
+}
+const SUMMARY_INSTRUCTION = "把以下对话压缩成一份中文工作摘要，保留：任务目标、已完成的关键步骤与工具结果、当前进度、待办事项、重要的文件路径/命令/产物。不要续写对话，只输出结构化摘要。";
+/** Returns a transformContext that compacts when over threshold.
+ *
+ * Harness-course retrofits (tutorial-harness 05/07):
+ *  - 膨胀拒绝（Gemini chatCompressionService）：摘要比被压区还长时作废本次压缩，
+ *    宁可用全量上下文也不换一份负收益的摘要。
+ *  - 失败记忆（Gemini hasFailedCompressionAttempt）：摘要调用失败或膨胀后记住这次
+ *    失败，后续不再反复烧摘要 token；失败不静默，通过 onCompactionFailed 上报。
+ */
+export function createCompactionTransform(options) {
+    const reserve = options.reserveTokens ?? 4096;
+    const keepRecent = options.keepRecentMessages ?? 8;
+    let hasFailed = false;
+    return async (messages, signal) => {
+        void signal;
+        const tokens = estimateTokens(messages);
+        if (tokens + reserve < options.contextWindow)
+            return messages;
+        if (hasFailed)
+            return messages; // 失败记忆：不再反复尝试摘要
+        if (messages.length <= keepRecent + 1)
+            return messages; // nothing worth compacting
+        const tail = messages.slice(-keepRecent);
+        const head = messages.slice(0, -keepRecent);
+        const summaryInput = [
+            ...head,
+            { role: "user", content: SUMMARY_INSTRUCTION, timestamp: Date.now() },
+        ];
+        const summary = await options.streamSummary(summaryInput).catch(() => "");
+        if (!summary) {
+            hasFailed = true;
+            await options.onCompactionFailed?.("summary-empty");
+            return messages; // compaction failed — degrade to full context
+        }
+        // 膨胀拒绝：摘要比被压区还长，压了不如不压
+        const headTokens = estimateTokens(head);
+        if (estimateTokens([{ role: "user", content: summary, timestamp: Date.now() }]) >= headTokens) {
+            hasFailed = true;
+            await options.onCompactionFailed?.("summary-inflated");
+            return messages;
+        }
+        options.onCompacted?.(summary, tokens);
+        const compactionMessage = {
+            role: "user",
+            content: `【早期对话摘要】\n${summary}`,
+            timestamp: Date.now(),
+        };
+        return [compactionMessage, ...tail];
+    };
+}
+/** One-shot completion via an AssistantMessageEventStream (relay streamFn
+ *  shape): drives the stream to completion and returns its full text. Used for
+ *  summary generation and async title generation (spec §13.2). */
+export async function streamOneText(streamFn, model, systemPrompt, messages) {
+    const stream = await streamFn(model, { systemPrompt, messages });
+    const final = await stream.result();
+    const content = final.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((block) => (typeof block === "object" && block !== null && block.type === "text" ? String(block.text ?? "") : ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+/** Builds the compaction transform for a run from a relay stream fn + model
+ *  refs. Returns undefined when compaction is disabled (no summaryModel). */
+export function buildCompactionTransform(input) {
+    if (!input.enabled || !input.summaryModel)
+        return undefined;
+    return createCompactionTransform({
+        summaryModel: input.summaryModel,
+        contextWindow: input.contextWindow,
+        streamSummary: (messages) => input.streamOne(input.summaryModel, messages),
+        ...(input.onCompacted ? { onCompacted: input.onCompacted } : {}),
+    });
+}
+//# sourceMappingURL=compaction.js.map

package/dist/core/runtime/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../../../src/core/runtime/compaction.ts"],"names":[],"mappings":"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"}

package/dist/core/runtime/lease-recovery.d.ts

@@ -0,0 +1,45 @@
+import type { EventLog } from "../events/bus.js";
+import type { SessionStore } from "../session/store.js";
+/** Lease recovery (spec §3.2): the runner stamps a lease on the session
+ *  document while it owns a run. A periodic scan reclaims sessions whose lease
+ *  lapsed without a live owner (process crash/restart), emitting a settle
+ *  event so clients don't sit on a stale "running" status forever.
+ *
+ *  Storage-agnostic (M5): the session store owns the lease fields; recovery
+ *  only needs a list + clear. Implementations provide the store-specific
+ *  `listExpiredLeases` / `clearLeaseIfExpired`. */
+export declare const scanIntervalMs = 60000;
+export declare const leaseDurationMs: number;
+export type LeaseRecoveryStore = {
+    /** Sessions whose lease lapsed (leaseExpiresAt < now), capped. */
+    listExpiredLeases(): Promise<{
+        sessionId: string;
+    }[]>;
+    /** Clears the lease if it is still expired; false if another won the race. */
+    clearLeaseIfExpired(sessionId: string): Promise<boolean>;
+};
+/** Interrupted-run finalization (product P2): when a run dies with its lease
+ *  (crash/restart), the run's in-flight projections would otherwise stay
+ *  frozen mid-run forever — a pending permission card, tool parts stuck
+ *  "running", todos stuck "in_progress". The event log is the projection's
+ *  single source of truth, so recovery derives the leftovers from it and
+ *  folds each into a terminal state (replied/reject, tool error, cancelled),
+ *  both in the store and as appended events. Idempotent: a second pass finds
+ *  no pending leftovers. */
+export declare function finalizeInterruptedRun(input: {
+    sessionId: string;
+    log: EventLog;
+    store: SessionStore;
+}): Promise<void>;
+export declare function reclaimExpiredLeases(input: {
+    store: LeaseRecoveryStore;
+    log: EventLog;
+    finalizeStore?: SessionStore;
+}): Promise<void>;
+export declare function startLeaseRecovery(input: {
+    store: LeaseRecoveryStore;
+    log: EventLog;
+    finalizeStore?: SessionStore;
+}): void;
+export { leaseDurationMs as fwLeaseDurationMs };
+//# sourceMappingURL=lease-recovery.d.ts.map

package/dist/core/runtime/lease-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-recovery.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/lease-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAIjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;mDAOmD;AAEnD,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,eAAO,MAAM,eAAe,QAAiB,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kEAAkE;IAClE,iBAAiB,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IACtD,8EAA8E;IAC9E,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D,CAAC;AAIF;;;;;;;4BAO4B;AAC5B,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD5H;AAED,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,aAAa,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3I;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,aAAa,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,IAAI,CAS1H;AAED,OAAO,EAAE,eAAe,IAAI,iBAAiB,EAAE,CAAC"}

package/dist/core/runtime/lease-recovery.js

@@ -0,0 +1,112 @@
+import { notifyEventLogListeners } from "../events/bus.js";
+/** Lease recovery (spec §3.2): the runner stamps a lease on the session
+ *  document while it owns a run. A periodic scan reclaims sessions whose lease
+ *  lapsed without a live owner (process crash/restart), emitting a settle
+ *  event so clients don't sit on a stale "running" status forever.
+ *
+ *  Storage-agnostic (M5): the session store owns the lease fields; recovery
+ *  only needs a list + clear. Implementations provide the store-specific
+ *  `listExpiredLeases` / `clearLeaseIfExpired`. */
+export const scanIntervalMs = 60_000;
+export const leaseDurationMs = 10 * 60 * 1000;
+const globalRecovery = globalThis;
+/** Interrupted-run finalization (product P2): when a run dies with its lease
+ *  (crash/restart), the run's in-flight projections would otherwise stay
+ *  frozen mid-run forever — a pending permission card, tool parts stuck
+ *  "running", todos stuck "in_progress". The event log is the projection's
+ *  single source of truth, so recovery derives the leftovers from it and
+ *  folds each into a terminal state (replied/reject, tool error, cancelled),
+ *  both in the store and as appended events. Idempotent: a second pass finds
+ *  no pending leftovers. */
+export async function finalizeInterruptedRun(input) {
+    const events = await input.log.read(input.sessionId, 0, 1_000);
+    const append = async (event) => {
+        const persisted = await input.log.append({ sessionId: input.sessionId, ...event }).catch(() => null);
+        if (persisted)
+            notifyEventLogListeners(persisted);
+    };
+    // 1. Pending permission: a `permission.asked` with no later `replied` for
+    //    the same request id. Fold it to `reject` so the card clears.
+    for (const asked of events) {
+        if (asked.type !== "permission.asked")
+            continue;
+        const requestId = asked.data.request.id;
+        const repliedAfter = events.some((event) => event.type === "permission.replied" && event.data.id === requestId);
+        if (repliedAfter)
+            continue;
+        await append({ type: "permission.replied", data: { id: requestId, reply: "reject" } });
+    }
+    const runningParts = new Map();
+    for (const event of events) {
+        if (event.type !== "message.part.updated")
+            continue;
+        const part = event.data.part;
+        if (part.type !== "tool")
+            continue;
+        if (part.state.status === "running" || part.state.status === "pending")
+            runningParts.set(part.id, part);
+        else
+            runningParts.delete(part.id);
+    }
+    for (const part of runningParts.values()) {
+        const started = part.state.status === "pending" ? new Date().toISOString() : part.state.time.start;
+        const terminal = {
+            ...part,
+            state: {
+                status: "error",
+                input: part.state.input,
+                error: "运行因服务重启中断，可在同一会话继续。",
+                time: { start: started, end: new Date().toISOString() },
+            },
+        };
+        await input.store.updatePart(terminal).catch(() => undefined);
+        await append({ type: "message.part.updated", data: { part: terminal } });
+    }
+    // 3. Todos stuck in flight: mark pending/in_progress items cancelled. Todos
+    //    are event-only (no store row), so an appended event suffices.
+    const lastTodo = [...events].reverse().find((event) => event.type === "todo.updated");
+    if (lastTodo) {
+        const todos = lastTodo.data.todos;
+        if (todos.some((item) => item.status === "pending" || item.status === "in_progress")) {
+            const settled = todos.map((item) => (item.status === "pending" || item.status === "in_progress" ? { ...item, status: "cancelled" } : item));
+            await append({ type: "todo.updated", data: { todos: settled } });
+        }
+    }
+}
+export async function reclaimExpiredLeases(input) {
+    const expired = await input.store.listExpiredLeases();
+    for (const session of expired) {
+        const reclaimed = await input.store.clearLeaseIfExpired(session.sessionId);
+        if (!reclaimed)
+            continue; // another scanner won the race
+        const events = [
+            { type: "session.error", data: { name: "LeaseExpired", message: "运行因服务重启中断，可在同一会话继续。" } },
+            { type: "session.status", data: { status: "idle" } },
+        ];
+        for (const event of events) {
+            const persisted = await input.log.append({
+                sessionId: session.sessionId,
+                type: event.type,
+                data: event.data,
+            }).catch(() => null);
+            if (persisted)
+                notifyEventLogListeners(persisted);
+        }
+        if (input.finalizeStore) {
+            await finalizeInterruptedRun({ sessionId: session.sessionId, log: input.log, store: input.finalizeStore }).catch(() => undefined);
+        }
+    }
+}
+export function startLeaseRecovery(input) {
+    if (globalRecovery.__zmzaiFrameworkLeaseTimer)
+        return;
+    // A process may restart immediately after a lease has expired. Do one scan
+    // on startup so those sessions do not remain stale until the first interval.
+    void reclaimExpiredLeases(input).catch(() => undefined);
+    globalRecovery.__zmzaiFrameworkLeaseTimer = setInterval(() => {
+        void reclaimExpiredLeases(input).catch(() => undefined);
+    }, scanIntervalMs);
+    globalRecovery.__zmzaiFrameworkLeaseTimer.unref?.();
+}
+export { leaseDurationMs as fwLeaseDurationMs };
+//# sourceMappingURL=lease-recovery.js.map

package/dist/core/runtime/lease-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-recovery.js","sourceRoot":"","sources":["../../../src/core/runtime/lease-recovery.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAK3D;;;;;;;mDAOmD;AAEnD,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAS9C,MAAM,cAAc,GAAG,UAAiG,CAAC;AAEzH;;;;;;;4BAO4B;AAC5B,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAAgE;IAC3G,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,KAAK,EAAE,KAAqB,EAAE,EAAE;QAC7C,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACrG,IAAI,SAAS;YAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC,CAAC;IAEF,0EAA0E;IAC1E,kEAAkE;IAClE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB;YAAE,SAAS;QAChD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,oBAAoB,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;QAChH,IAAI,YAAY;YAAE,SAAS;QAC3B,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzF,CAAC;IAMD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAoB,CAAC;IACjD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,sBAAsB;YAAE,SAAS;QACpD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QACnC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;;YACnG,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;QACnG,MAAM,QAAQ,GAAS;YACrB,GAAG,IAAI;YACP,KAAK,EAAE;gBACL,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK;gBACvB,KAAK,EAAE,qBAAqB;gBAC5B,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;aACxD;SACiC,CAAC;QACrC,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC9D,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,4EAA4E;IAC5E,mEAAmE;IACnE,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC;IACtF,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAClC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC,EAAE,CAAC;YACrF,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAoB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACrJ,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAiF;IAC1H,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,iBAAiB,EAAE,CAAC;IACtD,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC3E,IAAI,CAAC,SAAS;YAAE,SAAS,CAAC,+BAA+B;QACzD,MAAM,MAAM,GAAoH;YAC9H,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,qBAAqB,EAAE,EAAE;YACzF,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;SACrD,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;gBACvC,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAa;aAC1B,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YACrB,IAAI,SAAS;gBAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,sBAAsB,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACpI,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAiF;IAClH,IAAI,cAAc,CAAC,0BAA0B;QAAE,OAAO;IACtD,2EAA2E;IAC3E,6EAA6E;IAC7E,KAAK,oBAAoB,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,CAAC,0BAA0B,GAAG,WAAW,CAAC,GAAG,EAAE;QAC3D,KAAK,oBAAoB,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC,EAAE,cAAc,CAAC,CAAC;IACnB,cAAc,CAAC,0BAA0B,CAAC,KAAK,EAAE,EAAE,CAAC;AACtD,CAAC;AAED,OAAO,EAAE,eAAe,IAAI,iBAAiB,EAAE,CAAC"}