@vincemakes/kiso-runtime 0.1.19 → 0.1.21

package/dist/session.js

@@ -1,5 +1,5 @@
 /**
- * AgentSession + Run — the durable multi-turn conversation (Phase C/D).
+ * AgentSession — the durable multi-turn conversation (Phase C/D).
  *
  * A session owns ONE EventLog, seeded from disk on load and continued in
  * memory. Each `run(input)`:
@@ -22,10 +22,17 @@
  *
  * Restart recovery is the same code path as a second run: rebuild the log
  * from the JSONL, continue numbering where the file ended.
+ *
+ * 手感批 B4 (pure move): the Run class lives in run.ts, the recovery
+ * support in recovery.ts, the E1/E2 composition helpers in compose.ts —
+ * same package, same exports (index.ts re-exports all four).
  */
-import { EventLog, executionLedger, loop, projectMessages, } from "@vincemakes/kiso-core";
+import { EventLog, executionLedger, projectMessages, } from "@vincemakes/kiso-core";
 import { denialResult } from "@vincemakes/kiso-core";
+import { estimateSummarySavings, KEEP_RECENT_ROUNDS, lastSummaryPoint, summarizeConversation, summaryBoundarySeq, } from "@vincemakes/kiso-core";
 import { StaleWriterError } from "./store.js";
+import { composeHooks } from "./compose.js";
+import { Run } from "./run.js";
 /** A session whose disk write was rejected (stale handle) is PERMANENTLY
  * poisoned: its in-memory log no longer matches the disk, so no further
  * run may proceed — reload the session (一). */
@@ -148,6 +155,42 @@ export class AgentSession {
         this.ensureHealthy();
         return new Run(this.#store, this.#adapter, this.#config, this, undefined, undefined, true);
     }
+    /**
+     * /compact (ADR-0044): compress the older conversation with a model
+     * summary. Covers the range (previous summary point, boundary] —
+     * boundary = the event before the keepRounds-th most recent round —
+     * and persists ONE `summarized` event. The summary call is OFF-LOOP
+     * through the session's OWN adapter: it writes nothing; a failure
+     * throws and the session is unchanged ("nothing happened"). Returns
+     * null when fewer than keepRounds+1 uncovered rounds exist (nothing
+     * worth covering yet). Crash semantics: a crash BEFORE the persist is
+     * "nothing happened"; after it, a resume projects the compressed view.
+     */
+    async summarize(options = {}) {
+        this.ensureHealthy();
+        const keepRounds = options.keepRounds ?? KEEP_RECENT_ROUNDS;
+        const events = this.log.all;
+        const boundary = summaryBoundarySeq(events, keepRounds);
+        if (boundary === undefined)
+            return null;
+        const prevPoint = lastSummaryPoint(events);
+        const covered = projectMessages(events.filter((e) => e.seq > prevPoint && e.seq <= boundary && e.type !== "summarized"));
+        const summary = await summarizeConversation({
+            adapter: this.#adapter,
+            model: this.#config.model,
+            messages: covered,
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        const full = this.log.append({ type: "summarized", coversToSeq: boundary, summary });
+        // The record rides the LAST recorded run's id — a summarized fact
+        // must never open a run of its own: the open-run gate keys on
+        // terminal-less runIds, and a "compact" runId would block the next
+        // run() ("still has an open run").
+        const records = this.#store.load(this.id);
+        const runId = records.length > 0 ? records[records.length - 1].runId : "compact";
+        await this.persist(runId, full);
+        return { coversToSeq: boundary, summary, savedTokens: estimateSummarySavings(covered, summary) };
+    }
     // ── Phase D: approvals ───────────────────────────────────────────────
     /**
      * Pauses that still await a human decision (durable, survives restart).
@@ -391,632 +434,3 @@ export class AgentSession {
         this.#pendingResolvers.delete(decisionId);
     }
 }
-/**
- * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
- * is the natural shape; the handle also carries the runId and the abort.
- */
-export class Run {
-    runId;
-    #store;
-    #adapter;
-    #config;
-    #session;
-    #input;
-    #resume;
-    #abort = new AbortController();
-    #externalSignal;
-    #decisionIds = [];
-    #uncertaintyIds = [];
-    #started = false;
-    constructor(store, adapter, config, session, input, externalSignal, resume) {
-        this.#store = store;
-        this.#adapter = adapter;
-        this.#config = config;
-        this.#session = session;
-        this.#input = input;
-        this.#externalSignal = externalSignal;
-        this.#resume = resume;
-        this.runId = crypto.randomUUID();
-    }
-    /** Cancel the run: propagates to the adapter (SDK) and future executions. */
-    abort() {
-        this.#abort.abort();
-    }
-    async *[Symbol.asyncIterator]() {
-        if (this.#started)
-            throw new Error("a run may only be consumed once");
-        this.#started = true;
-        // The WHOLE body is one try/finally: a consumer that abandons the
-        // run at ANY yield (even the user_input one) must release the
-        // session's single-run slot and its approval resolvers.
-        try {
-            // 第四轮: health is re-checked when the iterator ACTUALLY starts —
-            // a run constructed before the session was poisoned must fail
-            // here, before any log or disk mutation.
-            this.#session.ensureHealthy();
-            this.#session.beginRun(this);
-            const log = this.#session.log;
-            const signal = this.#externalSignal ? new MergedSignal(this.#abort.signal, this.#externalSignal) : this.#abort.signal;
-            // E2: the session's own microcompact wins; otherwise the FIRST
-            // extension providing a compaction config supplies it.
-            const microcompact = microcompactFor(this.#config);
-            // E2: the session's own systemPrompt first, then every extension
-            // append in LOAD order — deterministic (same extensions → same
-            // prompt); no appends → byte-identical to the extension-less run.
-            const systemPrompt = composeSystemPrompt(this.#config.systemPrompt, this.#config.extensions ?? []);
-            const loopConfig = () => ({
-                adapter: this.#adapter,
-                model: this.#config.model,
-                sessionId: this.#session.id, // P3: tools see their session (ToolContext.sessionId)
-                ...(systemPrompt !== undefined ? { systemPrompt } : {}),
-                registry: this.#config.registry,
-                ...(this.#config.hooks !== undefined ? { hooks: this.#config.hooks } : {}),
-                ...(this.#config.maxTurns !== undefined ? { maxTurns: this.#config.maxTurns } : {}),
-                ...(this.#config.maxTokens !== undefined ? { maxTokens: this.#config.maxTokens } : {}),
-                ...(this.#config.temperature !== undefined ? { temperature: this.#config.temperature } : {}),
-                ...(this.#config.compaction !== undefined ? { compaction: this.#config.compaction } : {}),
-                ...(microcompact !== undefined ? { microcompact } : {}),
-                ...(this.#config.maxRetries !== undefined ? { maxRetries: this.#config.maxRetries } : {}),
-                approvalPolicies: (this.#config.extensions ?? []).flatMap((e) => (e.approvals ?? []).map((policy) => ({ extension: e.name, policy }))),
-                log,
-                signal,
-                resolveApproval: (decisionId) => new Promise((resolve) => {
-                    this.#decisionIds.push(decisionId);
-                    this.#session.registerResolver(decisionId, resolve);
-                }),
-                // 第四轮(对抗): the abort paths consult these so a verdict
-                // the human gave in the same instant as the abort is
-                // recorded, exactly once.
-                approvalVerdict: (decisionId) => this.#session.approvalVerdict(decisionId),
-                uncertaintyVerdict: (executionId) => this.#session.uncertaintyVerdict(executionId),
-                resolveUncertainty: (executionId) => new Promise((resolve) => {
-                    this.#uncertaintyIds.push(executionId);
-                    this.#session.registerUncertaintyResolver(executionId, resolve);
-                }),
-            });
-            const self = this;
-            const runLoop = async function* () {
-                for await (const ev of loop(loopConfig())) {
-                    await self.#session.persist(self.runId, ev);
-                    yield ev;
-                }
-            };
-            if (this.#resume) {
-                // ── B 组: recovery is PER-RUN, keyed by StoreRecord.runId ──
-                // Rebuild run boundaries; only the LAST unterminated run is
-                // recovered. Earlier runs that DID terminate have their
-                // dangling approvals closed (permission_expired) — a dead
-                // run's approval is never re-presented or resurrected.
-                const records = this.#store.load(this.#session.id);
-                const runs = new Map();
-                const order = [];
-                for (const r of records) {
-                    if (!runs.has(r.runId)) {
-                        runs.set(r.runId, []);
-                        order.push(r.runId);
-                    }
-                    runs.get(r.runId).push(r.event);
-                }
-                let lastOpen;
-                for (const runId of order) {
-                    const events = runs.get(runId);
-                    if (!events.some((e) => e.type === "terminal"))
-                        lastOpen = { runId, events };
-                }
-                if (!lastOpen)
-                    return; // everything terminated — nothing to resume
-                // Adopt the ORIGINAL runId so the whole trajectory stays one
-                // run in the audit.
-                this.runId = lastOpen.runId;
-                // Close dangling approvals of TERMINATED runs.
-                for (const [runId, events] of runs) {
-                    if (runId === lastOpen.runId)
-                        continue;
-                    if (!events.some((e) => e.type === "terminal"))
-                        continue; // an open earlier run? impossible — lastOpen is the LAST
-                    for (const ev of events) {
-                        if (ev.type !== "permission_requested")
-                            continue;
-                        const dead = this.#session.log.all.some((e) => (e.type === "permission_decided" || e.type === "permission_expired") &&
-                            e.decisionId === ev.decisionId);
-                        if (dead)
-                            continue;
-                        const expired = this.#session.log.append({
-                            type: "permission_expired",
-                            decisionId: ev.decisionId,
-                            reason: `run ${runId} terminated before the request was answered`,
-                        });
-                        await this.#session.persist(runId, expired);
-                    }
-                }
-                // Uncertain executions block until a human decides.
-                const uncertain = this.#session.uncertainExecutions();
-                if (uncertain.length > 0) {
-                    throw new ResumeBlockedError(uncertain.map((u) => ({ executionId: u.executionId, callId: u.callId, name: u.name })));
-                }
-                // 1. Recovery scoped to the LAST OPEN RUN's events. The recover
-                //    phase re-announces ALREADY-PERSISTED events (the stored
-                //    permission_requested) for the consumer to re-prompt on —
-                //    those must never be written to the store again, or seq
-                //    would duplicate. Only events newer than the base log
-                //    entry are durable.
-                const baseSeq = log.lastSeq;
-                const persist = async (ev) => {
-                    if (ev.seq > baseSeq)
-                        await this.#session.persist(this.runId, ev);
-                };
-                for await (const ev of this.#recover(log, signal, lastOpen.events)) {
-                    await persist(ev);
-                    yield ev;
-                }
-                // 2. Continuation: drive the LAST OPEN run to its terminal.
-                //    The guard is scoped to that run — an earlier run's
-                //    terminal must not suppress it (B 组).
-                if (!lastOpen.events.some((e) => e.type === "terminal")) {
-                    for await (const ev of runLoop())
-                        yield ev;
-                }
-                return;
-            }
-            // 四: a session with an open run REFUSES new runs at the
-            // persistence layer — a second open run would be permanently
-            // orphaned (recovery only ever recovers the last one). The
-            // open run is continued via resume(), never by starting another.
-            const openRun = openRunId(this.#store.load(this.#session.id));
-            if (openRun !== undefined) {
-                throw new Error(`session ${this.#session.id} still has an open run (${openRun}) — resume() it instead of starting a new run`);
-            }
-            // 1. Durable first: the prompt enters the log and the store
-            //    before any model call — a crash here leaves a restorable
-            //    session. The prompt is also the first event the consumer
-            //    sees, so what was asked and what happened live in the same
-            //    stream.
-            const inputEvent = log.append({ type: "user_input", content: this.#input });
-            await this.#session.persist(this.runId, inputEvent);
-            yield inputEvent;
-            // 2. The loop projects from the session log — multi-turn context
-            //    is the projection, not a second copy.
-            for await (const ev of runLoop())
-                yield ev;
-        }
-        finally {
-            // 第五轮(P1-5): flush verdicts the consumer submitted before the
-            // generator was abandoned — an approve()/resolveUncertain() whose
-            // durable event the loop never got to persist must STILL land on
-            // disk, exactly once.
-            try {
-                await this.#session.flushPendingVerdicts(this.runId, this.#session.log);
-            }
-            catch {
-                // the flush itself failed (poisoned session) — the error
-                // already poisoned everything; nothing more can be done.
-            }
-            // The run is over (or abandoned): its unanswered approvals must
-            // fall back to the direct-persist path, so a late approve() is
-            // still durable.
-            for (const decisionId of this.#decisionIds) {
-                this.#session.dropResolver(decisionId);
-            }
-            for (const executionId of this.#uncertaintyIds) {
-                this.#session.dropUncertaintyResolver(executionId);
-            }
-            this.#session.endRun(this);
-        }
-    }
-    // ── Area 2: the durable recovery state machine ───────────────────────
-    /**
-     * Apply every durable decision and fill every missing receipt, in log
-     * order. A decision with no execution yet EXECUTES the persisted call
-     * (its original name/input/callId — never re-asked of the model, never
-     * re-approved); a denial writes its tool result; a succeeded/failed
-     * execution whose tool_result never landed is completed from the
-     * receipt. Undecided requests pause and await approve().
-     */
-    async *#recover(log, signal, scope) {
-        const requests = scope.filter((e) => e.type === "permission_requested");
-        for (const pending of requests) {
-            const decided = log.all.find((e) => e.type === "permission_decided" && e.decisionId === pending.decisionId);
-            // 四: paired by events NEWER than the request — a historical
-            // same-callId execution from an earlier run must not count as THIS
-            // request's execution (the provider callId may repeat across runs).
-            const hasExecution = log.all.some((e) => e.type === "tool_execution_started" && e.callId === pending.callId && e.seq > pending.seq);
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.callId === pending.callId && e.seq > pending.seq);
-            if (decided === undefined) {
-                // Pause: announce the stored request, await the human.
-                const pendingDecision = new Promise((resolve) => {
-                    this.#decisionIds.push(pending.decisionId);
-                    this.#session.registerResolver(pending.decisionId, resolve);
-                });
-                yield pending;
-                // Area 4: an abort during the resumed approval wait ends the
-                // run; the request stays durable and pending.
-                if (signal.aborted) {
-                    // 第五轮(P1-6): a verdict given in the same instant as the
-                    // abort is still recorded — the abort must not bypass the
-                    // durable fallback (aligned with the loop's abort path).
-                    const verdict = this.#session.approvalVerdict(pending.decisionId);
-                    if (verdict !== undefined) {
-                        yield log.append({
-                            type: "permission_decided",
-                            decisionId: pending.decisionId,
-                            callId: pending.callId,
-                            decision: verdict ? "approved" : "denied",
-                            ...(verdict ? {} : { reason: "denied by user" }),
-                        });
-                    }
-                    return;
-                }
-                const final = await abortable(pendingDecision, signal);
-                if (final === ABORTED) {
-                    // 第四轮(对抗): a verdict given in the same instant as the
-                    // abort is recorded (exactly once), never lost.
-                    const verdict = this.#session.approvalVerdict(pending.decisionId);
-                    if (verdict !== undefined) {
-                        yield log.append({
-                            type: "permission_decided",
-                            decisionId: pending.decisionId,
-                            callId: pending.callId,
-                            decision: verdict ? "approved" : "denied",
-                            ...(verdict ? {} : { reason: "denied by user" }),
-                        });
-                    }
-                    return;
-                }
-                // The decision is written here — exactly one writer per event.
-                yield log.append({
-                    type: "permission_decided",
-                    decisionId: pending.decisionId,
-                    callId: pending.callId, // binds the decision to the invocation (B 组)
-                    decision: final.action === "allow" ? "approved" : "denied",
-                    ...(final.action === "deny" && final.reason !== undefined ? { reason: final.reason } : {}),
-                });
-                if (final.action === "allow") {
-                    if (!hasExecution)
-                        yield* this.#executePersisted(pending.callId, pending.name, pending.input, signal);
-                }
-                else if (!hasResult) {
-                    yield* this.#denialResult(pending.callId, final.reason ?? "denied by user");
-                }
-            }
-            else if (decided.decision === "approved") {
-                // Decided while no process was running: apply without pausing.
-                // An abort during recovery must stop the pending executions,
-                // exactly like the live loop's sibling guard (finding 3).
-                if (signal.aborted)
-                    return;
-                if (!hasExecution)
-                    yield* this.#executePersisted(pending.callId, pending.name, pending.input, signal);
-            }
-            else if (!hasResult) {
-                yield* this.#denialResult(pending.callId, decided.reason ?? "denied by user");
-            }
-        }
-        // Receipt repair: an execution that reached a terminal state but
-        // whose model-facing result never landed is completed FROM THE
-        // RECEIPT — never re-executed. Snapshot the scope first: this phase
-        // appends the repaired results, and iterating a growing array would
-        // re-visit them. 四: pairing is by executionId — a same-callId result
-        // from a different execution never suppresses the repair.
-        for (const ev of [...scope]) {
-            if (ev.type !== "tool_execution_succeeded" && ev.type !== "tool_execution_failed")
-                continue;
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.executionId === ev.executionId);
-            if (hasResult)
-                continue;
-            yield log.append(ev.type === "tool_execution_succeeded"
-                ? {
-                    type: "tool_result",
-                    callId: ev.callId,
-                    content: ev.result.content,
-                    isError: false,
-                    // 八: the repaired result reproduces the normal path
-                    // losslessly — the tags ride on the durable receipt.
-                    ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
-                    executionId: ev.executionId,
-                }
-                : {
-                    type: "tool_result",
-                    callId: ev.callId,
-                    content: ev.error,
-                    isError: true,
-                    ...(ev.errorKind !== undefined ? { errorKind: ev.errorKind } : {}),
-                    ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
-                    executionId: ev.executionId,
-                });
-        }
-        // B 组 crash window: a resolution was persisted but its tool_result
-        // fill never landed — complete it so the model is never left staring
-        // at a dangling tool_use. 四: keyed by executionId, and the fill
-        // carries it, so a same-callId result from another execution is never
-        // confused with this one.
-        for (const ev of [...scope]) {
-            if (ev.type !== "tool_execution_resolved")
-                continue;
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.executionId === ev.executionId);
-            if (hasResult)
-                continue;
-            const denial = denialResult(ev.resolution === "rerun"
-                ? "interrupted execution — rerun approved: the attempt is treated as NOT applied; the model may retry"
-                : "abandoned by human decision — the interrupted attempt must not be treated as applied");
-            yield log.append({
-                type: "tool_result",
-                callId: ev.callId,
-                content: denial.content,
-                isError: true,
-                errorKind: denial.errorKind,
-                executionId: ev.executionId,
-            });
-        }
-    }
-    /**
-     * Execute a call whose approval is already durable: the original
-     * name/input/callId from the persisted permission_requested, bypassing
-     * the permission hook (it was decided) and the model (it was never
-     * asked to re-issue). Full ledgered lifecycle.
-     */
-    async *#executePersisted(callId, name, input, signal) {
-        const log = this.#session.log;
-        const tool = this.#config.registry.get(name);
-        const executionId = `ex-${log.lastSeq + 1}`;
-        // An abort that landed while the decision was being applied must
-        // not start the side effect (finding 3).
-        if (signal.aborted)
-            return;
-        yield log.append({ type: "tool_execution_started", executionId, callId, name, input });
-        let result;
-        if (tool === undefined) {
-            result = { content: `Unknown tool: ${name}`, isError: true, errorKind: "invalid_input" };
-        }
-        else {
-            try {
-                if (signal.aborted) {
-                    result = { content: "aborted before execution", isError: true, errorKind: "fatal" };
-                }
-                else {
-                    result = await tool.execute(input, { signal });
-                }
-            }
-            catch (err) {
-                result = {
-                    content: err instanceof Error ? err.message : String(err),
-                    isError: true,
-                    errorKind: "fatal",
-                };
-            }
-            if (this.#config.hooks?.onPostTool) {
-                result = await this.#config.hooks.onPostTool({ callId, name, input }, result, { sessionId: this.#session.id });
-            }
-        }
-        // 裁决 #12 修正一: the honest note rides the recovered failure too —
-        // the receipt and the repaired tool_result reproduce the live path
-        // losslessly.
-        if (result.isError && tool?.idempotent !== true) {
-            result = {
-                ...result,
-                content: `${result.content}\n[non-idempotent tool failed — its side effects may have partially applied; verify before retrying]`,
-            };
-        }
-        if (result.isError) {
-            yield log.append({
-                type: "tool_execution_failed",
-                executionId,
-                callId,
-                error: result.content,
-                // P1-9: errorKind only exists on errors — runtime-guarded too.
-                ...(result.isError && result.errorKind !== undefined ? { errorKind: result.errorKind } : {}),
-                safeToRetry: tool?.idempotent === true,
-                ...(result.tags !== undefined ? { tags: result.tags } : {}),
-            });
-        }
-        else {
-            yield log.append({
-                type: "tool_execution_succeeded",
-                executionId,
-                callId,
-                result: { content: result.content, isError: false },
-                ...(result.tags !== undefined ? { tags: result.tags } : {}),
-            });
-        }
-        yield log.append({
-            type: "tool_result",
-            callId,
-            content: result.content,
-            isError: result.isError,
-            // P1-9: errorKind only exists on errors — runtime-guarded too.
-            ...(result.isError && result.errorKind !== undefined ? { errorKind: result.errorKind } : {}),
-            // 五: live tags survive the resumed path too.
-            ...(result.tags !== undefined ? { tags: result.tags } : {}),
-            executionId,
-        });
-        // 裁决 #12 (ADR-0038): the failed-receipt uncertain PAUSE is REMOVED
-        // here too (it mirrored the live loop's C 组 pause) — a complete
-        // receipt IS the outcome; uncertainty belongs to the crash window
-        // alone. A retry passes the approval chain again.
-    }
-    /** The model-facing result of a durable denial — no execution happened. */
-    async *#denialResult(callId, reason) {
-        const denial = denialResult(reason);
-        yield this.#session.log.append({
-            type: "tool_result",
-            callId,
-            content: denial.content,
-            isError: true,
-            errorKind: denial.errorKind,
-        });
-    }
-}
-/**
- * E2: the session's systemPrompt plus every extension's append, in LOAD
- * order, \n\n-joined — deterministic (same extension list → same prompt).
- * No appends → the base passes through byte-identical.
- */
-function composeSystemPrompt(base, extensions) {
-    const appends = extensions.flatMap((e) => (e.systemPrompt?.append === undefined ? [] : [e.systemPrompt.append]));
-    if (appends.length === 0)
-        return base;
-    return base === undefined ? appends.join("\n\n") : `${base}\n\n${appends.join("\n\n")}`;
-}
-/**
- * E1: extension hooks compose AFTER the agent's own (既有先行 — the existing
- * hook sees every event first). Observers all run, in order; onUserMessage
- * and onPreTool — the FIRST decisive answer wins (the existing hook
- * outranks extensions; defers fall through); onPostTool folds — each
- * transforms the previous result. Returns the existing host unchanged when
- * no extension provides hooks.
- */
-function composeHooks(existing, extensions) {
-    const extHooks = extensions.flatMap((e) => (e.hooks === undefined ? [] : [e.hooks]));
-    if (extHooks.length === 0)
-        return existing;
-    const out = { ...existing };
-    const sources = existing === undefined ? extHooks : [existing, ...extHooks];
-    const observers = (key) => {
-        const handlers = sources.map(key).filter((h) => h !== undefined);
-        if (handlers.length <= 1)
-            return handlers[0];
-        return async (payload, ctx) => {
-            for (const h of handlers)
-                await h(payload, ctx);
-        };
-    };
-    for (const key of ["onPreLlm", "onEvent", "onPreCompact", "onPostCompact", "onPause", "onStop"]) {
-        const handler = observers((h) => h[key]);
-        if (handler !== undefined)
-            out[key] = handler;
-    }
-    const messageHandlers = sources
-        .map((h) => h.onUserMessage)
-        .filter((h) => h !== undefined);
-    if (messageHandlers.length === 1) {
-        out.onUserMessage = messageHandlers[0]; // length 1 guarantees the element
-    }
-    else if (messageHandlers.length > 1) {
-        // 复审 E1-P2: the pipe + veto short-circuit — each handler sees the
-        // message as the PREVIOUS one left it (既有先行), and a null (veto)
-        // anywhere ends the chain immediately: never "no opinion" for the
-        // next handler to outvote. Adding an extension can therefore never
-        // make the chain MORE permissive (the approval chain's deny>ask>allow
-        // monotonicity, on the message side).
-        out.onUserMessage = async (msg, ctx) => {
-            let current = msg;
-            for (const h of messageHandlers) {
-                const r = await h(current, ctx);
-                if (r === null)
-                    return null;
-                current = r;
-            }
-            return current;
-        };
-    }
-    const preToolHandlers = sources
-        .map((h) => h.onPreTool)
-        .filter((h) => h !== undefined);
-    if (preToolHandlers.length === 1) {
-        out.onPreTool = preToolHandlers[0];
-    }
-    else if (preToolHandlers.length > 1) {
-        out.onPreTool = async (call, ctx) => {
-            for (const h of preToolHandlers) {
-                const d = await h(call, ctx);
-                if (d.action !== "defer")
-                    return d;
-            }
-            return { action: "defer" };
-        };
-    }
-    const postToolHandlers = sources
-        .map((h) => h.onPostTool)
-        .filter((h) => h !== undefined);
-    if (postToolHandlers.length === 1) {
-        out.onPostTool = postToolHandlers[0];
-    }
-    else if (postToolHandlers.length > 1) {
-        out.onPostTool = async (call, result, ctx) => {
-            let r = result;
-            for (const h of postToolHandlers)
-                r = await h(call, r, ctx);
-            return r;
-        };
-    }
-    return out;
-}
-/**
- * E2: the loop's microcompact config — the session's own microcompact wins;
- * otherwise the FIRST extension providing a compaction config supplies it.
- * An extension config without a threshold contributes nothing (a boundary
- * needs a threshold to ever fire).
- */
-function microcompactFor(config) {
-    if (config.microcompact !== undefined)
-        return config.microcompact;
-    for (const ext of config.extensions ?? []) {
-        const c = ext.compaction;
-        if (c !== undefined && c.thresholdTokens !== undefined) {
-            return { thresholdTokens: c.thresholdTokens, ...(c.keepResults !== undefined ? { keepResults: c.keepResults } : {}) };
-        }
-    }
-    return undefined;
-}
-/**
- * The most recent run WITHOUT a terminal, or undefined when every recorded
- * run terminated. Recovery can only drive ONE run to its terminal, so an
- * open run must be the exclusive reason a session refuses new runs (四).
- */
-function openRunId(records) {
-    const terminated = new Set(records.filter((r) => r.event.type === "terminal").map((r) => r.runId));
-    for (let i = records.length - 1; i >= 0; i--) {
-        const runId = records[i].runId;
-        if (!terminated.has(runId))
-            return runId;
-    }
-    return undefined;
-}
-/** Sentinel: the signal aborted while the recovery awaited a decision. */
-const ABORTED = Symbol("kiso-resume-aborted");
-/** Resolve with the decision, or ABORTED when the signal fires first. */
-async function abortable(promise, signal) {
-    if (signal.aborted)
-        return ABORTED;
-    return new Promise((resolve) => {
-        const onAbort = () => {
-            signal.removeEventListener("abort", onAbort);
-            resolve(ABORTED);
-        };
-        signal.addEventListener("abort", onAbort, { once: true });
-        promise.then((value) => {
-            signal.removeEventListener("abort", onAbort);
-            resolve(value);
-        }, (err) => {
-            signal.removeEventListener("abort", onAbort);
-            throw err;
-        });
-    });
-}
-/**
- * A signal that fires when ANY source fires — the run's own controller and
- * an optional external signal (the CLI's Ctrl+C, a fixture's flip).
- */
-class MergedSignal {
-    #sources;
-    #listeners = new Set();
-    constructor(...sources) {
-        this.#sources = sources;
-        for (const source of sources) {
-            if (source.aborted)
-                continue;
-            source.addEventListener("abort", () => {
-                for (const listener of this.#listeners)
-                    listener();
-            });
-        }
-    }
-    get aborted() {
-        return this.#sources.some((s) => s.aborted);
-    }
-    addEventListener(_type, listener) {
-        this.#listeners.add(() => listener.call(this, undefined));
-    }
-    removeEventListener(_type, listener) {
-        this.#listeners.delete(listener);
-    }
-}