@armadra/agent 0.0.0-stage → 0.2.1

package/dist/agent/session-cache.js

@@ -0,0 +1,511 @@
+/**
+ * 会话层缓存控制器（第三波 §1.2、§1.5–§1.7、§1.9、§1.10）。[W3-C1b]
+ *
+ * `wrapStream()` 包住会话的流函数：每次真实请求记一条 `RequestRecord`（内存）、算前缀指纹、
+ * 更新三态、检测未命中（发 `cache_miss`）、跨 70% / 90% 发 `context_pressure`，turn 请求完成后
+ * 交给保温状态机。摘要请求自成一条链，不与主链比对；压缩 / 分支摘要 / 档一裁剪 / `/tree`
+ * 之后的首个请求是重置点。子会话（depth > 0）有自己的控制器，`warmSubagents` 为 false 时不保温。
+ * fork 出的会话沿用根会话 id 作 `prompt_cache_key`（只是路由提示）；task 子会话不沿用。
+ */
+import { readFileSync } from "node:fs";
+import { evaluateWarm } from "../ai/cache/economics.js";
+import { fingerprintContext } from "../ai/cache/fingerprint.js";
+import { DEFAULT_MIN_CACHE_TOKENS, IMPLICIT_CACHE_TTL_MS, detectMiss } from "../ai/cache/miss.js";
+import { endpointKey, sharedCacheReporting, } from "../ai/cache/reporting.js";
+import { CacheWarmer, replayBlocker } from "../ai/cache/warmer.js";
+import { SUMMARY_MAX_TOKENS } from "../compaction/summarize-tier.js";
+import { convertToLlm } from "./transform.js";
+export const DEFAULT_CACHE_SETTINGS = Object.freeze({
+    warming: "streaming",
+    retention: "short",
+    minSavingsUsd: 0.05,
+    missNotices: true,
+    warmSubagents: false,
+});
+export const PRESSURE_THRESHOLDS = [70, 90];
+const GROWTH_SAMPLES = 5;
+const TASK_CUSTOM_TYPE = "ama.task";
+export function resolveCacheSettings(partial = {}) {
+    const settings = { ...DEFAULT_CACHE_SETTINGS };
+    for (const [key, value] of Object.entries(partial)) {
+        if (value !== undefined)
+            settings[key] = value;
+    }
+    return settings;
+}
+/** 目录 TTL（毫秒）：long 保留且有 long 档时用 long；无承诺 → undefined。 */
+export function cacheTtlMs(model, retention) {
+    const cache = model.promptCache;
+    const seconds = retention === "long" && cache?.long !== undefined ? cache.long : cache?.short;
+    return seconds === undefined ? undefined : seconds * 1000;
+}
+function readHead(file) {
+    try {
+        const [header, first] = readFileSync(file, "utf8").split("\n", 2);
+        const parsed = JSON.parse(header ?? "{}");
+        const entry = first ? JSON.parse(first) : undefined;
+        return { ...parsed, task: entry?.customType === TASK_CUSTOM_TYPE };
+    }
+    catch {
+        return { task: false };
+    }
+}
+/** fork 链上的根会话 id（task 子会话与非 fork 会话用自己的 id）。 */
+export function cacheKeyOf(manager) {
+    const header = manager.header();
+    const isTask = manager
+        .entries()
+        .some((entry) => entry.type === "custom" && entry.customType === TASK_CUSTOM_TYPE);
+    if (header.parentSession === undefined || isTask)
+        return manager.id;
+    let id = manager.id;
+    let file = header.parentSession;
+    for (let depth = 0; depth < 8 && file !== undefined; depth++) {
+        const head = readHead(file);
+        if (head.id === undefined || head.task)
+            break;
+        id = head.id;
+        file = head.parentSession;
+    }
+    return id;
+}
+export class SessionCacheController {
+    core;
+    settings;
+    now;
+    tracker;
+    decider;
+    warmer;
+    models = new WeakMap();
+    snapshots = new WeakMap();
+    replaced = new WeakSet();
+    inner;
+    warmingOverride;
+    cacheKey;
+    prev;
+    lastTurnRecord;
+    resetPending = false;
+    disposed = false;
+    activeTasks = 0;
+    taskSince = 0;
+    taskMs = 0;
+    sums = new Map();
+    missCount = 0;
+    byReason = {};
+    reBilledTokens = 0;
+    reBilledUsd = 0;
+    growth = [];
+    lastPercent = 0;
+    subagents = { count: 0, read: 0, prompt: 0, reBilledTokens: 0 };
+    constructor(core, settings, deps = {}) {
+        this.core = core;
+        this.settings = settings;
+        this.now = deps.now ?? (() => Date.now());
+        this.tracker = deps.tracker ?? sharedCacheReporting;
+        this.decider = deps.decider ?? (() => undefined);
+        const warmerDeps = {
+            mode: () => this.mode(),
+            now: this.now,
+            send: (record, signal) => this.replay(record, signal),
+            isCurrent: (record) => this.isCurrent(record),
+            evaluate: (record, phase) => evaluateWarm(this.modelOf(record), record.promptTokens, phase, this.settings.minSavingsUsd),
+            decide: (decision) => this.decider()?.(decision) ?? decision.action,
+            onWarmed: (record, message, sentAt) => this.onWarmed(record, message, sentAt),
+            onScheduled: (nextWarmAt) => this.core.emit({ type: "cache_warm", phase: "scheduled", nextWarmAt }),
+            onStopped: (reason) => this.core.emit({ type: "cache_warm", phase: "stopped", reason }),
+        };
+        if (deps.timers !== undefined)
+            warmerDeps.timers = deps.timers;
+        this.warmer = new CacheWarmer(warmerDeps);
+    }
+    /** 生效的保温模式：子会话在 warmSubagents 为 false 时 off；`/cache warm` 会话内覆盖。 */
+    mode() {
+        if (this.core.depth > 0 && !this.settings.warmSubagents)
+            return "off";
+        return this.warmingOverride ?? this.settings.warming;
+    }
+    get cacheSettings() {
+        return this.settings;
+    }
+    setWarming(mode) {
+        this.warmingOverride = mode;
+        if (mode === "off")
+            this.warmer.cancel();
+    }
+    /** 最后一条 turn 请求（摘要续写的前缀依据）。 */
+    get lastTurn() {
+        return this.lastTurnRecord;
+    }
+    wrapStream(inner) {
+        this.inner = inner;
+        return (model, context, options) => {
+            const purpose = options.purpose ?? "turn";
+            if (this.disposed || purpose === "warm" || purpose === "probe") {
+                return inner(model, context, options);
+            }
+            const sent = { ...options };
+            let snapshot;
+            let subtaskMs = 0;
+            const at = this.now();
+            if (purpose === "turn") {
+                sent.cacheRetention ??= this.settings.retention;
+                if (sent.sessionId !== undefined && sent.sessionId === this.core.manager.id) {
+                    this.cacheKey ??= cacheKeyOf(this.core.manager);
+                    sent.sessionId = this.cacheKey;
+                }
+                this.warmer.pause();
+                snapshot = {
+                    messages: this.core.agent.messages.slice(),
+                    tools: this.toolsKey(),
+                    thinking: options.thinkingLevel,
+                };
+                subtaskMs = this.takeTaskMs(at);
+            }
+            let replaced = false;
+            const onPayload = options.onPayload;
+            if (onPayload !== undefined) {
+                sent.onPayload = (payload) => {
+                    const result = onPayload(payload);
+                    if (result !== undefined)
+                        replaced = true;
+                    return result;
+                };
+            }
+            const stream = inner(model, context, sent);
+            void stream.result().then((message) => {
+                if (this.disposed || message.stopReason === "error" || message.stopReason === "aborted")
+                    return;
+                const { signal: _signal, ...rest } = sent;
+                const stored = { ...rest };
+                if (onPayload !== undefined)
+                    stored.onPayload = onPayload;
+                const usage = message.usage;
+                const record = {
+                    at,
+                    purpose,
+                    model: { provider: model.provider, id: model.id },
+                    api: model.api,
+                    baseUrl: model.baseUrl ?? "",
+                    fingerprint: fingerprintContext(context, model),
+                    promptTokens: usage.input + usage.cacheRead + usage.cacheWrite,
+                    usage,
+                    contextRef: context,
+                    options: stored,
+                };
+                this.models.set(record, model);
+                if (snapshot !== undefined)
+                    this.snapshots.set(record, snapshot);
+                if (replaced)
+                    this.replaced.add(record);
+                this.observe(record, model, subtaskMs);
+            }, () => undefined);
+            return stream;
+        };
+    }
+    /** 会话事件（AgentSessionImpl.emit 转交）。 */
+    onEvent(event) {
+        switch (event.type) {
+            case "agent_settled":
+                this.onAgentSettled();
+                return;
+            case "model_changed":
+            case "thinking_level_changed":
+            case "compaction_start":
+                this.warmer.cancel();
+                return;
+            case "entry_appended": {
+                const { entry } = event;
+                if (entry.type === "compaction" ||
+                    entry.type === "branch_summary" ||
+                    (entry.type === "context_edit" && entry.reason === "prune")) {
+                    this.onContextChanged();
+                }
+                return;
+            }
+            case "tool_execution_start":
+                if (event.toolName === "task" && this.activeTasks++ === 0)
+                    this.taskSince = this.now();
+                return;
+            case "tool_execution_end":
+                if (event.toolName === "task" && this.activeTasks > 0 && --this.activeTasks === 0)
+                    this.taskMs += this.now() - this.taskSince;
+                return;
+            default:
+                return;
+        }
+    }
+    onAgentSettled() {
+        this.warmer.onAgentSettled();
+    }
+    /** 压缩 / context_edit / setModel / navigate 之后：下一条请求是重置点，保温作废。 */
+    onContextChanged() {
+        this.resetPending = true;
+        this.warmer.cancel();
+    }
+    /** task 子会话结束时由父会话汇总（各自独立统计）。 */
+    addSubagent(tokens, reBilledTokens) {
+        this.subagents.count++;
+        this.subagents.read += tokens.cacheRead;
+        this.subagents.prompt += tokens.prompt;
+        this.subagents.reBilledTokens += reBilledTokens;
+    }
+    stats(context = {}) {
+        const model = this.core.model();
+        const setting = model.compat?.cacheReporting;
+        const endpoint = endpointKey({ model, baseUrl: model.baseUrl ?? "" });
+        const reporting = this.tracker.get(endpoint, setting);
+        const stats = {
+            reporting,
+            reBilledTokens: this.reBilledTokens,
+            misses: { count: this.missCount, byReason: { ...this.byReason } },
+            warming: this.warmer.status,
+        };
+        const granularity = this.tracker.granularity(endpoint);
+        if (granularity !== undefined)
+            stats.granularity = granularity;
+        const last = this.lastTurnRecord;
+        if (reporting === "reported" && last !== undefined && last.promptTokens > 0)
+            stats.lastHitRate = last.usage.cacheRead / last.promptTokens;
+        let read = 0;
+        let prompt = 0;
+        for (const [key, sum] of this.sums) {
+            if (this.tracker.get(key) !== "reported")
+                continue;
+            read += sum.read;
+            prompt += sum.prompt;
+        }
+        if (prompt > 0)
+            stats.hitRate = read / prompt;
+        if (this.reBilledUsd !== undefined)
+            stats.reBilledUsd = this.reBilledUsd;
+        if (context.tokens !== undefined && context.window !== undefined) {
+            const remaining = Math.max(0, context.window - context.tokens);
+            stats.contextRemainingTokens = remaining;
+            const turns = this.turnsLeft(remaining);
+            if (turns !== undefined)
+                stats.estimatedTurnsLeft = turns;
+        }
+        if (this.subagents.count > 0) {
+            const sub = {
+                count: this.subagents.count,
+                reBilledTokens: this.subagents.reBilledTokens,
+            };
+            if (this.subagents.prompt > 0)
+                sub.hitRate = this.subagents.read / this.subagents.prompt;
+            stats.subagents = sub;
+        }
+        return stats;
+    }
+    /**
+     * 摘要续写的前缀（第三波 §1.8）：当前转录按回合同样的方式转换，且上一次 turn 请求的消息
+     * 逐条是它的前缀（缓存必然命中）、加上摘要输出放得进窗口；否则 undefined（走独立请求）。
+     */
+    summaryContinuation() {
+        const record = this.lastTurnRecord;
+        const model = this.core.model();
+        if (record === undefined || this.disposed)
+            return undefined;
+        if (model.provider !== record.model.provider || model.id !== record.model.id)
+            return undefined;
+        const messages = convertToLlm(this.core.agent.messages, {
+            provider: model.provider,
+            model: model.id,
+        });
+        const prev = record.contextRef.messages;
+        if (prev.length > messages.length)
+            return undefined;
+        for (let i = 0; i < prev.length; i++)
+            if (JSON.stringify(prev[i]) !== JSON.stringify(messages[i]))
+                return undefined;
+        const extra = Math.ceil(JSON.stringify(messages.slice(prev.length)).length / 4);
+        const window = model.contextWindow;
+        if (window !== undefined && record.promptTokens + extra + SUMMARY_MAX_TOKENS + 2048 > window)
+            return undefined;
+        const { onPayload: _p, onResponse: _r, purpose: _u, toolChoice: _t, cacheRetention: _c, maxTokens, ...rest } = record.options;
+        const streamOptions = { ...rest };
+        // 预算型思考的预算从 max_tokens 推导，改它会让消息缓存失效：沿用回合的值。
+        const budget = replayBlocker({
+            model,
+            options: rest,
+            payloadReplaced: false,
+            reporting: "reported",
+        });
+        if (budget === "thinking_budget")
+            streamOptions.maxTokens = maxTokens ?? model.maxTokens;
+        return { prefix: { messages }, streamOptions };
+    }
+    dispose() {
+        this.disposed = true;
+        this.warmer.cancel();
+    }
+    // -------------------------------------------------------------------------
+    // 内部
+    // -------------------------------------------------------------------------
+    modelOf(record) {
+        return this.models.get(record) ?? this.core.model();
+    }
+    toolsKey() {
+        return this.core.activeToolNames().sort().join(",");
+    }
+    takeTaskMs(at) {
+        let total = this.taskMs;
+        if (this.activeTasks > 0) {
+            total += at - this.taskSince;
+            this.taskSince = at;
+        }
+        this.taskMs = 0;
+        return total;
+    }
+    turnsLeft(remaining) {
+        if (this.growth.length === 0)
+            return undefined;
+        const average = this.growth.reduce((a, b) => a + b, 0) / this.growth.length;
+        return average > 0 ? Math.floor(remaining / average) : undefined;
+    }
+    observe(record, model, subtaskMs) {
+        const minTokens = model.promptCache?.minTokens ?? DEFAULT_MIN_CACHE_TOKENS;
+        const ttl = cacheTtlMs(model, record.options.cacheRetention);
+        const reporting = this.tracker.observe(record, minTokens, ttl ?? IMPLICIT_CACHE_TTL_MS, model.compat?.cacheReporting);
+        const key = endpointKey(record);
+        const sum = this.sums.get(key) ?? { read: 0, prompt: 0 };
+        sum.read += record.usage.cacheRead;
+        sum.prompt += record.promptTokens;
+        this.sums.set(key, sum);
+        if (record.purpose !== "turn")
+            return reporting;
+        const prev = this.resetPending ? undefined : this.prev;
+        const lastTurn = this.resetPending ? undefined : this.lastTurnRecord;
+        this.resetPending = false;
+        const missOptions = { reporting, minTokens, subtaskMs };
+        if (model.cost !== undefined)
+            missOptions.cost = model.cost;
+        const granularity = this.tracker.granularity(key);
+        if (granularity !== undefined)
+            missOptions.granularity = granularity;
+        const miss = detectMiss(prev, record, ttl, missOptions);
+        if (miss !== undefined) {
+            this.missCount++;
+            this.byReason[miss.reason] = (this.byReason[miss.reason] ?? 0) + 1;
+            this.reBilledTokens += miss.missedTokens;
+            this.reBilledUsd =
+                this.reBilledUsd === undefined || miss.missedCost === undefined
+                    ? undefined
+                    : this.reBilledUsd + miss.missedCost;
+            this.core.emit({ type: "cache_miss", ...miss });
+        }
+        if (lastTurn !== undefined && record.promptTokens > lastTurn.promptTokens) {
+            this.growth.push(record.promptTokens - lastTurn.promptTokens);
+            if (this.growth.length > GROWTH_SAMPLES)
+                this.growth.shift();
+        }
+        this.prev = record;
+        this.lastTurnRecord = record;
+        this.checkPressure(record, model);
+        this.scheduleWarm(record, model, reporting, ttl);
+        return reporting;
+    }
+    checkPressure(record, model) {
+        const window = model.contextWindow;
+        if (window === undefined || window <= 0)
+            return;
+        const used = record.promptTokens + record.usage.output;
+        const percent = Math.min(100, Math.round((used / window) * 1000) / 10);
+        const before = this.lastPercent;
+        this.lastPercent = percent;
+        for (const threshold of PRESSURE_THRESHOLDS) {
+            if (before >= threshold || percent < threshold)
+                continue;
+            const remainingTokens = Math.max(0, window - used);
+            const event = {
+                type: "context_pressure",
+                percent,
+                threshold,
+                remainingTokens,
+            };
+            const turns = this.turnsLeft(remainingTokens);
+            if (turns !== undefined)
+                event.estimatedTurnsLeft = turns;
+            this.core.emit(event);
+        }
+    }
+    scheduleWarm(record, model, reporting, ttl) {
+        if (this.mode() === "off")
+            return this.warmer.cancel();
+        const blocker = replayBlocker({
+            model,
+            options: record.options,
+            payloadReplaced: this.replaced.has(record),
+            reporting,
+        });
+        if (blocker !== undefined)
+            return this.warmer.block(blocker);
+        if (ttl === undefined)
+            return this.warmer.block("no_ttl");
+        if (this.decider() === undefined) {
+            const decision = evaluateWarm(model, record.promptTokens, "streaming", this.settings.minSavingsUsd);
+            if (decision.action === "stop")
+                return this.warmer.block(decision.reason ?? "declined");
+        }
+        this.warmer.start(record, ttl);
+    }
+    isCurrent(record) {
+        const model = this.core.model();
+        if (model.provider !== record.model.provider || model.id !== record.model.id)
+            return false;
+        const snapshot = this.snapshots.get(record);
+        if (snapshot === undefined)
+            return false;
+        if (snapshot.thinking !== undefined && snapshot.thinking !== this.core.thinkingLevel())
+            return false;
+        if (snapshot.tools !== this.toolsKey())
+            return false;
+        const current = this.core.agent.messages;
+        if (current.length < snapshot.messages.length)
+            return false;
+        return snapshot.messages.every((message, i) => current[i] === message);
+    }
+    async replay(record, signal) {
+        const inner = this.inner;
+        if (inner === undefined)
+            throw new Error("stream not wrapped");
+        const options = { ...record.options, maxTokens: 1, purpose: "warm", signal };
+        return inner(this.modelOf(record), record.contextRef, options).result();
+    }
+    onWarmed(record, message, sentAt) {
+        const usage = message.usage;
+        try {
+            this.core.appendEntry({
+                type: "usage",
+                kind: "cache_warm",
+                provider: record.model.provider,
+                model: record.model.id,
+                usage,
+            });
+        }
+        catch (error) {
+            this.core.log("debug", `cache warm usage not recorded: ${String(error)}`);
+        }
+        const event = { type: "cache_warm", phase: "sent", usage };
+        if (usage.cost !== undefined)
+            event.cost = usage.cost.total;
+        this.core.emit(event);
+        const warm = {
+            ...record,
+            at: sentAt,
+            purpose: "warm",
+            usage,
+            promptTokens: usage.input + usage.cacheRead + usage.cacheWrite,
+        };
+        const model = this.modelOf(record);
+        this.models.set(warm, model);
+        const minTokens = model.promptCache?.minTokens ?? DEFAULT_MIN_CACHE_TOKENS;
+        this.tracker.observe(warm, minTokens, cacheTtlMs(model), model.compat?.cacheReporting);
+        const sum = this.sums.get(endpointKey(warm));
+        if (sum !== undefined) {
+            sum.read += usage.cacheRead;
+            sum.prompt += warm.promptTokens;
+        }
+        if (!this.resetPending)
+            this.prev = warm;
+    }
+}

package/dist/agent/session-compaction.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 会话侧的压缩调度（设计 §9）。[B2]
+ *
+ * - 阈值检查（新提示前、`prepareNextTurn` 里）：估算 > 0.7 ×（窗口 − 预留）→ 档一裁剪；仍 > 窗口 − 预留
+ *   且熔断允许 → 档二摘要（trigger `threshold`）。
+ * - 溢出恢复（会话 run 结束后，失败尝试已用 context_edit 剔除）：PreCompact Hook → 档二摘要（trigger
+ *   `overflow`，不受「每 run 一次」限制但受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
+ * - 手动 `/compact`：PreCompact（trigger `manual`）→ 摘要；成功清零熔断。
+ * PreCompact 的 `decision: "block"` 取消本次压缩；`customInstructions` 追加到摘要提示。
+ * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
+ * （前缀本身已超窗口）；续写失败回落独立请求并记 warning。
+ */
+import { CompactionBreaker } from "../compaction/breaker.js";
+import { type ContextEstimate } from "../compaction/estimate.js";
+import type { BranchSummaryEntry } from "../session/types.js";
+import type { SessionCore } from "./session-core.js";
+import type { CompactionResult, CompactionSettings } from "./types.js";
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/** 保留区不超过 (窗口 − 预留) 的 40%，否则小窗口模型上摘要后仍然溢出。 */
+export declare const KEEP_RECENT_MAX_RATIO = 0.4;
+export declare class CompactionController {
+    readonly breaker: CompactionBreaker;
+    settings: CompactionSettings;
+    private readonly core;
+    private compacting;
+    constructor(core: SessionCore, settings?: Partial<CompactionSettings>);
+    get isCompacting(): boolean;
+    /** 模型或开关变化后调用。 */
+    refresh(): void;
+    setAuto(enabled: boolean): void;
+    estimate(): ContextEstimate;
+    private budget;
+    private keepRecent;
+    /** 摘要请求的公共选项；`continuation` 时附上会话前缀续写的材料。 */
+    private summarizer;
+    /** 档一；返回是否裁剪了内容。 */
+    prune(): boolean;
+    /** 阈值检查（档一 → 档二）。失败只记录，不打断 run。 */
+    checkThreshold(signal: AbortSignal): Promise<void>;
+    /** 溢出恢复：返回是否应以新 run 重试。 */
+    recoverOverflow(signal: AbortSignal): Promise<{
+        retry: boolean;
+        warning?: string;
+    }>;
+    compactManual(instructions: string | undefined, signal: AbortSignal): Promise<CompactionResult>;
+    /** `/tree` 离开分支：换叶子，并为离开的那段写 branch_summary（挂在新叶子下）。 */
+    leaveBranch(targetId: string | null, instructions: string | undefined, signal: AbortSignal): Promise<BranchSummaryEntry | undefined>;
+    private summarize;
+}