@vincemakes/kiso-runtime 0.39.2 → 0.40.0

package/dist/session.js

@@ -35,15 +35,19 @@ import { assessTasks } from "./task-assessment.js";
  *  verification surface. Override per call for custom evidence tools. */
 const DEFAULT_EVIDENCE_TOOLS = new Set(["shell"]);
 import { denialResult } from "@vincemakes/kiso-core";
-import { buildProfile, readProfile, writeProfile } from "./profile.js";
-import { resolveReasoning } from "./provider/metadata.js";
-import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, MANUAL_SUMMARY_BUDGET, SUMMARY_MAX_OUTPUT, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
+import { buildProfile, readProfile, writeProfile, writeSummary } from "./profile.js";
+import { summarizeEvents } from "./session-summary.js";
+import { lookupModelMetadata, resolveReasoning } from "./provider/metadata.js";
+import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, MANUAL_SUMMARY_BUDGET, SUMMARY_MAX_OUTPUT, summarizeConversation, SummaryBudgetExhausted, summaryBoundarySeq, } from "./summarize.js";
 import { canonicalizeUsageForModel } from "./usage/canonical.js";
+import { contextAnchor } from "./context-anchor.js";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { estimateTokens } from "@vincemakes/kiso-core";
 import { StaleWriterError } from "./store.js";
-import { composeHooks } from "./compose.js";
+import { composeHooks, composeSystemPrompt, microcompactFor, runBasePrompt } from "./compose.js";
+import { checkpointBoundarySeq } from "./checkpoint.js";
+import { breakEvenFactor, guardedPruneSeq, KEEP_COMPACTABLE_RESULTS, microcompactBoundarySeq, phaseEnd, runsACheck, tierReason, tiersFor } from "./compaction-policy.js";
 import { Run } from "./run.js";
 // TUI2-R3v2 ③ — the side query rides the SAME tracer the runs ride; that
 // sameness is the whole point (one ledger, one shape, no second path).
@@ -120,6 +124,12 @@ export class AgentSession {
     // XP-1: a legacy session records revision 1 at the next explicit
     // selection or first request — never eagerly at open.
     #profilePending;
+    /** 0.40.0: the config profile name of the live binding (configuration:
+     *  each revision records the name in force when it is written). */
+    #profileName;
+    /** 0.40.0: what this open's drift acknowledgement replaced — the CLI
+     *  says so once. Null when the session opened without material drift. */
+    driftAcknowledgement;
     #pendingResolvers = new Map();
     #answered = new Set();
     /** round 4 (adversarial): verdicts the human GAVE, recorded when passed to a live
@@ -140,6 +150,18 @@ export class AgentSession {
     /** E6 (h): the circuit-breaker counter — consecutive auto-policy
      *  summary failures this session (a success resets it). */
     #summaryFailures = 0;
+    /** 0.40.0: usage at or before this seq was billed under another model — never an anchor. */
+    #anchorFloorSeq = -1;
+    /** A1b: the window the tiers are drawn from — the live binding's, once a
+     *  switch states one (CTX-1: the threshold travels with the model). */
+    #tiersWindow;
+    #lastUsageAt;
+    /** 0.40.0: when the provider last billed this session (epoch ms) — the
+     *  record's time on load, the write's time after. A provider's prompt
+     *  cache expires with time, so an old bill means a cold prefix. */
+    get lastUsageAt() {
+        return this.#lastUsageAt;
+    }
     /** Permanently invalidate the session after a rejected disk write (round 1). */
     poison(reason) {
         if (this.#poisoned === null)
@@ -150,7 +172,8 @@ export class AgentSession {
             throw new PoisonedSessionError(this.#poisoned);
     }
     #activeRuns = new Set();
-    constructor(id, log, store, adapter, config) {
+    constructor(id, log, store, adapter, config, lastUsageAt) {
+        this.#lastUsageAt = lastUsageAt;
         this.id = id;
         this.log = log;
         this.#store = store;
@@ -174,6 +197,8 @@ export class AgentSession {
         // CTX-1: starts as the startup policy, then follows the binding.
         this.#microcompact = config.microcompact;
         this.#profilePending = config.profilePending === true;
+        this.#profileName = config.profileName ?? null;
+        this.driftAcknowledgement = config.driftAcknowledgement ?? null;
     }
     /** The config a NEW run/resume/summary sees: the frozen startup config
      *  with the LIVE binding fields (model, provider) substituted. Built
@@ -200,6 +225,8 @@ export class AgentSession {
         this.ensureHealthy();
         try {
             await this.#store.append(this.id, runId, event);
+            if (event.type === "usage" && event.known)
+                this.#lastUsageAt = Date.now();
         }
         catch (err) {
             // round 4: ANY rejected write poisons — not only the typed
@@ -224,6 +251,145 @@ export class AgentSession {
     projected() {
         return projectMessages(this.log.all);
     }
+    /** 0.40.0: the context as the last bill measured it, plus what the log
+     *  appended since — or undefined when no bill describes it any more
+     *  (context-anchor.ts). `events` defaults to the session's log. */
+    contextAnchor(events = this.log.all) {
+        return contextAnchor(events, (u) => {
+            const c = canonicalizeUsageForModel(this.#model, this.#baseUrl, this.#provider ?? "adapter", u);
+            return c.input + c.cacheRead + (c.cacheWrite ?? 0) + c.output;
+        }, this.#anchorFloorSeq);
+    }
+    /** 0.40.0: what the context holds — the anchored figure, or the estimate
+     *  over the projection when no bill describes it. The thresholds and the
+     *  ctx row read this, never the bare estimate. */
+    contextUsed() {
+        return this.contextAnchor() ?? estimateTokens(this.projected());
+    }
+    /**
+     * ADR-0055 Amendment 1 (A1b) — the kernel's compaction point for ONE run,
+     * or undefined when nothing in-run is armed (the kernel then never asks).
+     *
+     * With `contextPolicy.tiers`: the §1a figure against the tiers — soft
+     * waits for a phase end (A3), hard and emergency fire now, an overflow
+     * fires once. The summary is in-band (A2) with ONE fallback to the
+     * serialised form; if both fail, an emergency or an overflow may prune
+     * once (A4b), and otherwise nothing happens and the run goes on.
+     *
+     * Without tiers, an EXPLICITLY configured `microcompact` keeps its old
+     * standing prune here, for SDK callers — the kernel no longer has one.
+     */
+    compactionPoint(run) {
+        const tiersPolicy = this.#config.contextPolicy?.tiers;
+        const legacy = tiersPolicy === undefined ? microcompactFor(this.#effectiveConfig(), this.log.all) : undefined;
+        if (tiersPolicy === undefined && legacy === undefined)
+            return undefined;
+        return async (events, messages, why) => {
+            const used = this.contextAnchor(events) ?? estimateTokens(messages);
+            if (tiersPolicy === undefined) {
+                if (legacy === undefined || used <= legacy.thresholdTokens)
+                    return [];
+                const beforeSeq = microcompactBoundarySeq(events, legacy.keepResults ?? KEEP_COMPACTABLE_RESULTS);
+                return beforeSeq === undefined ? [] : [{ type: "microcompacted", beforeSeq }];
+            }
+            const window = this.#tiersWindow ?? tiersPolicy.windowTokens;
+            const maxOutput = this.#config.maxTokens ?? lookupModelMetadata(this.#model, this.#baseUrl)?.capabilities.maxOutputTokens ?? 0;
+            const t = tiersFor(window, Math.max(maxOutput, MANUAL_SUMMARY_BUDGET));
+            const isCheck = tiersPolicy.isCheck ?? ((command) => runsACheck(command));
+            const reason = tierReason(used, t, why, () => phaseEnd(events, lastSummaryPoint(events), isCheck));
+            if (reason === null)
+                return [];
+            const urgent = reason === "overflow" || reason === "emergency";
+            if (!urgent && this.#summaryFailures >= (tiersPolicy.maxFailures ?? MAX_SUMMARY_FAILURES))
+                return [];
+            const summarized = await this.#summarizeInRun(events, messages, t.tail, reason, run);
+            if (summarized !== null)
+                return [summarized];
+            if (!urgent)
+                return [];
+            const pricing = lookupModelMetadata(this.#model, this.#baseUrl)?.pricing ?? null;
+            const beforeSeq = guardedPruneSeq(events, breakEvenFactor(pricing?.inputPerM, pricing?.cacheReadPerM));
+            return beforeSeq === undefined ? [] : [{ type: "microcompacted", beforeSeq }];
+        };
+    }
+    /**
+     * ADR-0055 A2 — one checkpoint call, both paths: IN-BAND first (the
+     * messages as a run sends them, under the run's system prompt and tool
+     * table, the instruction appended — the prefix reads at the cache-hit
+     * price), and ONCE the serialised covered range when that reply is
+     * rejected (a tool call, markup, a missing section). An
+     * abort is never answered with the second call. Throws when both fail.
+     */
+    async #checkpointCall(args) {
+        const common = {
+            adapter: this.#adapter,
+            model: this.#model,
+            maxOutputTokens: args.budget,
+            ...(args.signal !== undefined ? { signal: args.signal } : {}),
+            ...(this.#config.maxRetries !== undefined ? { maxRetries: this.#config.maxRetries } : {}),
+            onRetry: async (info) => {
+                await this.#config.hooks?.onRetry?.(info, {});
+            },
+            ...(args.onProgress !== undefined ? { onProgress: args.onProgress } : {}),
+        };
+        try {
+            const result = await summarizeConversation({ ...common, messages: args.messages, inBand: args.inBand, ...(args.reasoning !== undefined ? { reasoning: args.reasoning } : {}) });
+            return { result, path: "in-band" };
+        }
+        catch (err) {
+            // Only a REJECTED reply earns the second call: a transport failure
+            // already spent its retries, and an exhausted budget would exhaust
+            // the serialised call the same way.
+            if (args.signal?.aborted === true || !(err instanceof Error) || err instanceof SummaryBudgetExhausted)
+                throw err;
+            const result = await summarizeConversation({
+                ...common,
+                messages: [{ role: "user", content: args.serialized() }],
+                ...(args.serializedReasoning ? summaryReasoning(this.#model, this.#baseUrl) : {}),
+            });
+            return { result, path: "serialized" };
+        }
+    }
+    /** A2 — one in-run summary: in-band first, the serialised form once on
+     *  a rejection; null when neither produced a valid checkpoint. The
+     *  summary call's usage and path ride the trace ledger, as /compact's do. */
+    async #summarizeInRun(events, messages, tail, reason, run) {
+        const boundary = checkpointBoundarySeq(events, { keepTokens: tail });
+        if (boundary === undefined)
+            return null;
+        let path;
+        let result;
+        try {
+            ({ result, path } = await this.#checkpointCall({
+                messages,
+                inBand: { ...(run.systemPrompt !== undefined ? { systemPrompt: run.systemPrompt } : {}), tools: run.tools() },
+                ...(run.reasoning !== undefined ? { reasoning: run.reasoning } : {}),
+                serialized: () => serializeCovered({ events, prevPoint: lastSummaryPoint(events), boundary }),
+                serializedReasoning: true,
+                budget: MANUAL_SUMMARY_BUDGET,
+                ...(run.signal !== undefined ? { signal: run.signal } : {}),
+            }));
+        }
+        catch {
+            if (run.signal?.aborted !== true)
+                this.#summaryFailures += 1;
+            return null;
+        }
+        this.#summaryFailures = 0;
+        // Every in-run fire is recorded — its reason and path are what the
+        // measurement counts — and its usage when the provider reported one.
+        {
+            try {
+                const canonical = result.usage === null ? null : canonicalizeUsageForModel(this.#model, this.#baseUrl, this.#provider ?? "adapter", result.usage);
+                mkdirSync(join(this.#store.root, "traces"), { recursive: true, mode: 0o700 });
+                appendFileSync(join(this.#store.root, "traces", `${this.id}.jsonl`), `${JSON.stringify({ kind: "summary", canonical, reason, path })}\n`, { mode: 0o600 });
+            }
+            catch (err) {
+                console.error(`[kiso] summary usage ledger degraded (${err instanceof Error ? err.message : String(err)}); the summary call's cost is not recorded`);
+            }
+        }
+        return { type: "summarized", coversToSeq: boundary, summary: result.text };
+    }
     /**
      * merge round B (/model): replace the adapter for SUBSEQUENT runs. The
      * kernel reads the adapter through the loop-config closure at each
@@ -246,14 +412,22 @@ export class AgentSession {
      * metadata exists — the PH-1c registry.)
      */
     setModelBinding(binding) {
+        // 0.40.0: another model counts tokens differently — the last bill
+        // stops describing the context until the new model sends one.
+        if (binding.model !== this.#model || binding.provider !== this.#provider || binding.baseUrl !== this.#baseUrl) {
+            this.#anchorFloorSeq = this.log.all.at(-1)?.seq ?? -1;
+        }
         this.#adapter = binding.adapter;
         this.#model = binding.model;
         this.#provider = binding.provider;
         this.#baseUrl = binding.baseUrl;
         this.#continuationScope = binding.scope;
         this.#reasoning = binding.reasoning ?? { thinking: "default", effort: "default" };
+        this.#profileName = binding.profileName ?? null;
         if (binding.microcompact !== undefined)
             this.#microcompact = binding.microcompact;
+        if (binding.contextWindow !== undefined)
+            this.#tiersWindow = binding.contextWindow;
         // XP-1: an explicit selection is DURABLE — the setting survives
         // /resume because a revision records it now, not at some later flush.
         this.#recordProfile();
@@ -277,6 +451,17 @@ export class AgentSession {
     setMicrocompactThreshold(thresholdTokens) {
         this.#microcompact = { thresholdTokens };
     }
+    /** The raw tail a manual cut at a settled round keeps: the tiers' tail
+     *  when a window is known, else the policy's keep floor. */
+    #manualTailTokens() {
+        const window = this.#tiersWindow ?? this.#config.contextPolicy?.tiers?.windowTokens;
+        return window === undefined ? KEEP_TOKENS_DEFAULT : tiersFor(window, MANUAL_SUMMARY_BUDGET).tail;
+    }
+    /** A1b: the window the in-run tiers are drawn from, for a restored or
+     *  re-bound session (the CLI's one binding step calls both). */
+    setContextWindow(windowTokens) {
+        this.#tiersWindow = windowTokens;
+    }
     /** E2: the adapter identity (anthropic / openai-compat / openai-responses) — the route
      *  key the canonical consumer (CLI usage, the trace block) keys on. The
      *  per-run tracer reads the SAME live binding; one source, one
@@ -313,6 +498,29 @@ export class AgentSession {
     get reasoning() {
         return this.#reasoning;
     }
+    /**
+     * The 0.40.0 dogfood (item 2): the session list's row, written into the
+     * sidecar's `summary` tenant at a run's start (`open`) and at its end.
+     * Computed from the IN-MEMORY log — never a re-read of the file — and
+     * best-effort: a summary that cannot be written leaves the list saying
+     * less, and never fails the run. Observation only: nothing that decides
+     * recovery, projection or a request reads it.
+     */
+    recordSummary(open) {
+        try {
+            const prior = readProfile(this.#store.root, this.id);
+            writeSummary(this.#store.root, this.id, summarizeEvents(this.log.all, {
+                open,
+                updatedAt: Date.now(),
+                asks: open ? 0 : this.pendingApprovals().length,
+                workspaceUnknown: !(prior.kind === "ok" && prior.profile.workspace !== null),
+                source: "run",
+            }));
+        }
+        catch {
+            // observation only — the row says less; the run is untouched
+        }
+    }
     /** XP-1: record the live binding as the next durable profile revision
      *  (read-modify-write under the session's single-writer ownership). */
     #recordProfile() {
@@ -322,6 +530,11 @@ export class AgentSession {
             revision,
             modelId: this.#model,
             provider: this.#continuationScope ?? null,
+            profileName: this.#profileName,
+            // 0.40.0: history is CARRIED from the prior revision, never
+            // re-derived from this process. With no prior (a legacy
+            // session's first revision) the start is unknown: null.
+            workspace: prior.kind === "ok" ? prior.profile.workspace : null,
             reasoning: this.#reasoning,
             ...(this.#config.systemPrompt !== undefined ? { systemPrompt: this.#config.systemPrompt } : {}),
             registry: this.#config.registry,
@@ -420,7 +633,7 @@ export class AgentSession {
         this.ensureHealthy();
         if (this.#profilePending)
             this.#recordProfile(); // XP-1: legacy revision 1, before the first request
-        return new Run(this.#store, this.#adapter, this.#effectiveConfig(), this, input, options?.signal, false, options?.source);
+        return new Run(this.#store, this.#adapter, this.#effectiveConfig(), this, input, options?.signal, false, options?.source, options?.via);
     }
     /**
      * Continue the interrupted run (Area 2): apply durable decisions,
@@ -463,7 +676,15 @@ export class AgentSession {
         if (options.signal !== undefined && options.signal.aborted)
             throw cancelled();
         const events = this.log.all;
-        const boundary = summaryBoundarySeq(events, keepRounds, options.keepTokens);
+        // ADR-0055 (the owner's dogfood): a long autonomous session has few
+        // user turns and many tool rounds, and the user-turn cut found nothing
+        // in it ("fewer than 5 rounds") while the context was hundreds of
+        // thousands of tokens. When there is no user-turn cut, the manual
+        // gesture cuts where the in-run tiers do: at a settled round, the raw
+        // tail kept by tokens (the tiers' `min(0.1·window, 100K)` when the
+        // window is known, else the policy floor).
+        const tailTokens = Math.max(options.keepTokens ?? 0, this.#manualTailTokens());
+        const boundary = summaryBoundarySeq(events, keepRounds, options.keepTokens) ?? (options.manualBudget === true ? checkpointBoundarySeq(events, { keepTokens: tailTokens }) : undefined);
         if (boundary === undefined)
             return null;
         const prevPoint = lastSummaryPoint(events);
@@ -488,6 +709,7 @@ export class AgentSession {
         });
         let summary;
         let usage = null;
+        let summaryPath = null;
         // OR-1 (the second review): the summary is priced by the binding that
         // MADE the request. A /model switch during this call — the session's
         // longest single request — moves #model/#baseUrl/#provider under it;
@@ -502,21 +724,31 @@ export class AgentSession {
             summary = DROP_PLACEHOLDER;
         }
         else {
-            const call = await summarizeConversation({
-                adapter: binding.adapter,
-                model: binding.model,
-                // E6 (a): ONE serialized user message — the DSML bug's
-                // raw-message array is structurally dead on this path.
-                messages: [{ role: "user", content: serializedInput }],
-                // E6 (g): the summary call ALWAYS carries an explicit output
-                // budget (a wire-level truncation is caught by the (b)
-                // required-section validation, never silently passed).
-                // 0.39.2: measured for the manual gesture, fixed for the policy.
-                ...(options.manualBudget === true
-                    ? { maxOutputTokens: MANUAL_SUMMARY_BUDGET, ...summaryReasoning(binding.model, binding.baseUrl) }
-                    : { maxOutputTokens: SUMMARY_MAX_OUTPUT }),
+            // ADR-0055 A2 (the lead's ruling on the /compact gap): the checkpoint
+            // is asked IN-BAND on the prefix a run sends — the session's base
+            // prompt, the tool table, the extension appends, the registry's
+            // tools, the session's reasoning — so a /compact on a warm session
+            // reads its context at the cache-hit price; the serialised form is
+            // the one fallback. The budget is unchanged: measured for the
+            // manual gesture, fixed for the policy (0.39.2).
+            const cfg = this.#effectiveConfig();
+            const systemPrompt = composeSystemPrompt(runBasePrompt(cfg.systemPrompt, cfg.registry), cfg.extensions ?? []);
+            const wire = cfg.reasoning === undefined ? undefined : resolveReasoning(binding.model, cfg.reasoning, binding.baseUrl);
+            const { result: call, path } = await this.#checkpointCall({
+                messages: this.projected(),
+                inBand: {
+                    ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+                    tools: cfg.registry.snapshot().specs,
+                    ...(options.focus !== undefined ? { focus: options.focus } : {}),
+                },
+                ...(wire !== undefined && wire.ok && Object.keys(wire.wire).length > 0 ? { reasoning: wire.wire } : {}),
+                serialized: () => serializedInput,
+                serializedReasoning: options.manualBudget === true,
+                budget: options.manualBudget === true ? MANUAL_SUMMARY_BUDGET : SUMMARY_MAX_OUTPUT,
                 ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                ...(options.onProgress !== undefined ? { onProgress: options.onProgress } : {}),
             });
+            summaryPath = path;
             summary = call.text;
             usage = call.usage;
         }
@@ -541,7 +773,7 @@ export class AgentSession {
         if (usage !== null) {
             try {
                 const canonical = canonicalizeUsageForModel(binding.model, binding.baseUrl, binding.provider ?? "adapter", usage);
-                const line = JSON.stringify({ kind: "summary", canonical }) + "\n";
+                const line = JSON.stringify({ kind: "summary", canonical, ...(summaryPath !== null ? { path: summaryPath } : {}) }) + "\n";
                 mkdirSync(join(this.#store.root, "traces"), { recursive: true, mode: 0o700 }); // DF-0322-F1
                 appendFileSync(join(this.#store.root, "traces", `${this.id}.jsonl`), line, { mode: 0o600 });
             }
@@ -568,6 +800,10 @@ export class AgentSession {
         const policy = this.#config.contextPolicy;
         if (policy === undefined)
             return;
+        // A1b: with the in-run tiers armed, the kernel's compaction point
+        // decides before every request, the first one included.
+        if (policy.tiers !== undefined)
+            return;
         const mode = policy.drop ?? policy.summary;
         if (mode === undefined)
             return;
@@ -587,7 +823,7 @@ export class AgentSession {
         const maxFailures = mode.maxFailures ?? MAX_SUMMARY_FAILURES;
         if (this.#summaryFailures >= maxFailures)
             return;
-        if (estimateTokens(this.projected()) <= triggerTokens)
+        if (this.contextUsed() <= triggerTokens)
             return;
         try {
             await this.summarize({

package/dist/store.d.ts

@@ -111,6 +111,14 @@ export declare class SessionStore {
      */
     load(sessionId: string): StoreRecord[];
     has(sessionId: string): boolean;
+    /**
+     * 0.40.0 dogfood (the owner: /resume still waited seconds): the session
+     * ids, from the directory alone — no log is opened. `list()` reads every
+     * log whole to title it (one owner session is 83 MB); a caller that
+     * needs only the ids must never pay that. An empty log is skipped, as
+     * list() skips it.
+     */
+    ids(): string[];
     list(): SessionMeta[];
     /** Release a session's fd and OUR writer lock. Idempotent. */
     close(sessionId: string): void;

package/dist/store.js

@@ -42,7 +42,7 @@
  * - load is strict (A group round 1): a partial final line is the only
  *   tolerated damage; everything else throws StoreCorruptionError.
  */
-import { appendFileSync, closeSync, existsSync, fsyncSync, fstatSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, } from "node:fs";
+import { appendFileSync, closeSync, existsSync, fsyncSync, fstatSync, statSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { isKisoEvent } from "@vincemakes/kiso-core";
 import { LockedError, nativeLockAdapter, } from "./lock-adapter.js";
@@ -136,7 +136,9 @@ export function sessionTitle(records) {
     const asked = records
         .map((r) => r.event)
         .filter((e) => e.type === "user_input")
-        .map((e) => contentText(e.content).trim())
+        // 0.40.0: a skill turn is named by what the person TYPED — its
+        // content is a SKILL.md body the person never wrote.
+        .map((e) => (typeof e.via?.line === "string" ? e.via.line : contentText(e.content)).trim())
         .filter((t) => t !== "");
     if (asked.length === 0)
         return "(no prompt)";
@@ -385,6 +387,29 @@ export class SessionStore {
     has(sessionId) {
         return existsSync(this.pathFor(sessionId));
     }
+    /**
+     * 0.40.0 dogfood (the owner: /resume still waited seconds): the session
+     * ids, from the directory alone — no log is opened. `list()` reads every
+     * log whole to title it (one owner session is 83 MB); a caller that
+     * needs only the ids must never pay that. An empty log is skipped, as
+     * list() skips it.
+     */
+    ids() {
+        const out = [];
+        for (const entry of readdirSync(this.root)) {
+            if (!entry.endsWith(".jsonl"))
+                continue;
+            try {
+                if (statSync(join(this.root, entry)).size === 0)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            out.push(entry.slice(0, -".jsonl".length));
+        }
+        return out.sort();
+    }
     list() {
         const metas = [];
         for (const entry of readdirSync(this.root)) {

package/dist/summarize.d.ts

@@ -13,7 +13,7 @@
  * unchanged ("nothing happened"). Only the generated `summarized` event
  * lands on disk; the original events stay there forever.
  */
-import type { AbortSignalLike, Adapter } from "@vincemakes/kiso-core";
+import type { AbortSignalLike, Adapter, RetryInfo, ToolSpec } from "@vincemakes/kiso-core";
 import type { Event } from "@vincemakes/kiso-core";
 import type { Message } from "@vincemakes/kiso-core";
 import type { RawUsage } from "./usage/canonical.js";
@@ -86,6 +86,14 @@ export declare const POLICY_RESERVE: number;
  * blocks. That belongs to A1b, and the measurement above is its input.
  */
 export declare const MANUAL_SUMMARY_BUDGET = 32000;
+/** Thrown by an attempt that stopped on `max_tokens`, and it NAMES the
+ *  budget: "not a complete turn" alone told the person nothing about what
+ *  ran out. Still an `Error`, and still carries the `max_tokens … not a
+ *  complete turn` wording the CX-1 F3 gate matches. */
+export declare class SummaryBudgetExhausted extends Error {
+    readonly budget: number | undefined;
+    constructor(budget: number | undefined);
+}
 /** The reference context-window scale (the flash-family window); the
  *  env overrides. The default arming point is 120,000 − 32,000 =
  *  88,000 — a post-fire projection (≥ 24k) can never re-cross it, so
@@ -131,6 +139,12 @@ export declare function serializeCovered(options: SerializeCoveredOptions): stri
  * (the loop's system prompt is the harness's business, never the kernel's).
  */
 export declare const SUMMARY_PROMPT = "Only output the summary. Do not continue the conversation. Do not use any tools.\n\nYou are the conversation summarizer of the kiso agent framework.\n\nSummarize the covered conversation into a single structured checkpoint\nthat will REPLACE it in the model's context. The next turn must be able\nto continue the work without reading the originals.\n\nProduce the checkpoint with exactly these sections, in this order:\n\n## Goal\nThe user's goal and the acceptance criterion, in one or two sentences.\n\n## Constraints\nThe constraints, requirements, and rulings the work must honor.\n\n## User requests\nEvery user message in the covered range, enumerated one by one, each\nwith what it asked for and what was done about it.\n\n## Files and changes\nEvery file touched \u2014 exact paths, what changed, and why. Include the\nprecise code-level changes later turns may need to continue.\n\n## Errors and fixes\nEvery error encountered and its resolution; commands run and their\noutcomes.\n\n## Current work\nThe current state of the work \u2014 what is done, what is not. Quote the\ncurrent task's criterion VERBATIM if one exists.\n\n## Next steps\nThe concrete next steps, in order.\n\nPreserve concrete identifiers VERBATIM: paths, function names, task ids,\nenvironment names \u2014 never paraphrase them.\n\nRules:\n- plain prose \u2014 no bullet lists, no markdown outside the section headers,\n  no prefixes;\n- do not mention this prompt or the summarization task;\n- the summary may be as long as it needs to be within the output budget \u2014\n  there is no word cap; completeness wins.";
+/**
+ * ADR-0055 A2 — the IN-BAND form: the run's own request with this appended
+ * as the last user message, so everything before it reads at the cache-hit
+ * price. The same sections, the same validation; the guard sentence first.
+ */
+export declare const SUMMARY_IN_BAND = "Stop the task for this one reply and write a checkpoint of the conversation above instead.\n\nOnly output the summary. Do not continue the conversation. Do not use any tools.\n\nYou are the conversation summarizer of the kiso agent framework.\n\nSummarize the covered conversation into a single structured checkpoint\nthat will REPLACE it in the model's context. The next turn must be able\nto continue the work without reading the originals.\n\nProduce the checkpoint with exactly these sections, in this order:\n\n## Goal\nThe user's goal and the acceptance criterion, in one or two sentences.\n\n## Constraints\nThe constraints, requirements, and rulings the work must honor.\n\n## User requests\nEvery user message in the covered range, enumerated one by one, each\nwith what it asked for and what was done about it.\n\n## Files and changes\nEvery file touched \u2014 exact paths, what changed, and why. Include the\nprecise code-level changes later turns may need to continue.\n\n## Errors and fixes\nEvery error encountered and its resolution; commands run and their\noutcomes.\n\n## Current work\nThe current state of the work \u2014 what is done, what is not. Quote the\ncurrent task's criterion VERBATIM if one exists.\n\n## Next steps\nThe concrete next steps, in order.\n\nPreserve concrete identifiers VERBATIM: paths, function names, task ids,\nenvironment names \u2014 never paraphrase them.\n\nRules:\n- plain prose \u2014 no bullet lists, no markdown outside the section headers,\n  no prefixes;\n- do not mention this prompt or the summarization task;\n- the summary may be as long as it needs to be within the output budget \u2014\n  there is no word cap; completeness wins.";
 /**
  * E6 (b) — the output-side validation (the finding E6-F4/F5 follow-up):
  * a summary must be a complete checkpoint or NOTHING. The marker family
@@ -150,6 +164,15 @@ export declare function validateSummary(text: string): string | null;
 export interface SummarizeConversationOptions {
     readonly adapter: Adapter;
     readonly model: string;
+    /** ADR-0055 A2: send `messages` AS THE RUN SENT THEM, under the run's own
+     *  system prompt and tool table, with SUMMARY_IN_BAND appended — the
+     *  cache-hot form. Absent: `messages` is the serialized covered range
+     *  under SUMMARY_PROMPT, the cold form. */
+    readonly inBand?: {
+        readonly systemPrompt?: string;
+        readonly tools: readonly ToolSpec[];
+        readonly focus?: string;
+    };
     /** The covered conversation — the ONLY material the summary is about. */
     readonly messages: readonly Message[];
     readonly signal?: AbortSignalLike;
@@ -162,6 +185,34 @@ export interface SummarizeConversationOptions {
         readonly thinking?: "adaptive" | "enabled" | "disabled";
         readonly effort?: string;
     };
+    /** ADR-0005 Amendment 2: the kernel's retry budget, applied to this
+     *  off-loop call. Absent, the kernel's default. */
+    readonly maxRetries?: number;
+    /** ADR-0005 Amendment 2: announced before each wait, as the kernel
+     *  announces its own. Observation only — a throw is swallowed. */
+    readonly onRetry?: (info: RetryInfo) => Promise<void> | void;
+    /** 0.40.0: how much of the OUTPUT budget the call has spent so far —
+     *  reported at each attempt's start (zero) and as text, reasoning and
+     *  the final usage arrive. Observation only: a throw is swallowed, and
+     *  the request is identical with or without it. */
+    readonly onProgress?: (progress: SummaryProgress) => void;
+}
+/**
+ * 0.40.0 — the summary call's progress against its output budget.
+ *
+ * `produced` counts streamed text AND streamed reasoning (owner's ruling —
+ * a bar over text alone sits low while thinking spends the budget, and the
+ * call then fails at "full"), by the session's chars/4 proxy, until the
+ * provider reports its output total, which replaces the estimate
+ * (`reported`). `reasoningUnseen`: the provider billed reasoning that never
+ * streamed, so the jump to the reported total has a named cause.
+ */
+export interface SummaryProgress {
+    readonly produced: number;
+    /** the call's output budget; null when the call carries none */
+    readonly budget: number | null;
+    readonly reasoningUnseen: boolean;
+    readonly reported: boolean;
 }
 /** The summary call's result — the text PLUS the provider-reported usage
  *  (E6: the honest accounting — the summary call's cost rides the trace
@@ -172,7 +223,7 @@ export interface SummarizeConversationResult {
     readonly usage: RawUsage | null;
 }
 /**
- * The summary call, with ONE retry.
+ * The summary call, retried under the KERNEL'S policy.
  *
  * 0.39.1: `/compact` had no retry at all. The kernel owns retries
  * (ADR-0005) and this path does not go through the kernel — it calls the
@@ -182,11 +233,18 @@ export interface SummarizeConversationResult {
  * (the transport-failure-after-headers class); here is the only place
  * that can act on it.
  *
- * ONE retry, not a loop, and not the kernel's budget: a summary re-pays
- * its whole input, which on the sessions that need compacting is the
- * most expensive request the session makes. A permanent error still
- * throws on the first attempt — the retry is keyed on the classification
- * the adapter already made, never on the fact that something failed.
+ * 0.39.1 gave it ONE retry after 250 ms. ADR-0005 Amendment 2 gives it the
+ * kernel's rule instead, because a dropped summary stream is the same
+ * failure as a dropped turn and meets the same gateway: the same curve,
+ * the same budget (the same `maxRetries` knob), Retry-After as a floor and
+ * a wait beyond RETRY_AFTER_MAX_MS as an explicit stop — never a retry
+ * that comes early — and the same announcement before each wait. Each
+ * retry re-pays the summary's input, exactly as each turn retry re-pays
+ * the turn's; the budget that bounds one bounds the other.
+ *
+ * A permanent error still throws on the first attempt — the retry is
+ * keyed on the classification the adapter already made, never on the
+ * fact that something failed.
  */
 export declare function summarizeConversation(options: SummarizeConversationOptions): Promise<SummarizeConversationResult>;
 /** E6 — the crux-experiment drop arm: the covered turns are replaced by