@aparte/plugin-compaction 0.25.0 → 0.27.0

package/README.md

@@ -1,9 +1,9 @@
 # @aparte/plugin-compaction
 
-Conversation **compaction** for [aparté](https://github.com/apartejs/aparte): summarise the turns
-that no longer fit the model's window, keep the recent ones verbatim, and answer the context
-gauge's `aparte-compact`. Nothing in core compacts by itself — no UI kit does, and every agent
-SDK ships it as an opt-in module — so this is where it lives.
+Conversation **compaction** for [aparté](https://github.com/apartejs/aparte): when a conversation
+outgrows the model's window, summarise the older turns for the model and keep the recent ones
+verbatim — without deleting anything. Nothing in core compacts by itself — no UI kit does, and
+every agent SDK ships it as an opt-in module — so this is where it lives.
 
 ```bash
 npm install @aparte/plugin-compaction @aparte/core
@@ -12,47 +12,66 @@ npm install @aparte/plugin-compaction @aparte/core
 ```ts
 import { setupCompaction } from '@aparte/plugin-compaction';
 
-const compaction = setupCompaction();   // the global config, the current model's budget
+const compaction = setupCompaction();   // the global config, the current model's window
 ```
 
-```html
-<aparte-composer-toolbar>
-  <!-- asks for a compaction on reaching 90 % of the window; the plugin answers -->
-  <aparte-context auto-compact style="flex: 1"></aparte-context>
-</aparte-composer-toolbar>
-```
+That is the whole wiring. The plugin registers itself as the config's compactor and decides on
+its own: after a turn that leaves the conversation past 80 % of the window (`threshold`), and
+before a send whose request would not fit (the turn waits, Stop cancels both), and when the
+model refuses a request as over its window (it compacts and sends the turn once more).
+
+A compaction aims **below** the threshold, not at it: the history the model reads afterwards
+lands at about `threshold − 0.2` of the window, less the fixed costs (system prompt, tools, the
+room for the reply, the summary's slot), so one summary buys several turns instead of being asked
+for again after the next. The selection is made in the model's own tokens (the character
+heuristic's undercount is calibrated from the last reply, as the context gauge does) and leaves
+room for the turn being prepared, so a long paste is made room for. A `selector` of your own is
+called with the messages alone and is left as it is. Each chat compacts on its own: a summary
+being written for one does not hold up another. A Restore cancels a summary still being written
+for that chat (with `listen: false`, which hears no window event, the summary is refused when it
+comes back instead), and Stop cancels it in every case.
 
-That is the whole wiring. A compaction resolves the chat, selects what to summarise —
-by default the budget-aware selector over the current model's `contextWindow`, the system
-prompt and the tools, keeping the newest turns that still fit; the last two exchanges when
-the model declares no window — summarises it through the config's transport (the request
-carries `_meta: { compaction: true }`, so a backend can route it to a cheaper model), then
-puts back the summary as a **notice** (`compaction: true` — centred, no avatar, no actions;
-sent to the model under a preamble saying what it is) followed by the kept turns verbatim.
+A compaction **writes a checkpoint, it deletes nothing**. The summary goes on the first turn it
+keeps — `contextSummary: { summary, count, createdAt }`, saved with the conversation — and the
+history the model receives starts there, the summary first. Every message stays on screen and
+in storage; the bubble draws a separator above that turn ("12 messages summarised for the
+model", Show summary, Restore), and Restore sends the original messages to the model again.
 
 ```ts
-await compaction.compact();          // or from a button; returns the outcome, never throws
-compaction.abort();                  // the summarisation in flight; the transcript is untouched
-compaction.running;                  // true meanwhile
-compaction.dispose();                // remove the listeners
+await compaction.compact('main-chat');   // on demand; returns the outcome, never throws
+compaction.abort();                      // the summary in flight; the conversation is untouched
+compaction.running;                      // true meanwhile
+compaction.dispose();                    // remove the listeners and the compactor
 ```
 
-**Options** — `selector` (your own `(messages) => { keep, drop }`; `createCompactionSelector`
-builds the budget-aware one over a window you choose), `prompt` (the summariser's
-instruction), `keyResolver` (the resolver you gave `AparteClient`, when the key is not on the
-config), `summarize` (replace the model call entirely: your endpoint, a cheaper model),
-`resolveTarget` (a transcript that lives in a store rather than in the DOM),
-`scopeToTargetId` (one setup per chat on a multi-chat page), `keepWithoutWindow`, `listen`.
-The config comes last, like every `setup*`: `setupCompaction(options, config)`.
+**The summary** is asked of the current model through the config's transport: streamed, with a
+`maxTokens` that keeps the answer inside the window and `_meta: { compaction: true }`, so a
+backend can route it to a cheaper model. The default prompt asks for fixed sections in the
+conversation's language; a second compaction updates the summary rather than summarising a
+summary; the first request is kept word for word. A summary cut off at the length limit, ending
+in an error, or no shorter than what it replaces is refused and the conversation stays as it
+was. With **no** window on the model (and no `contextWindow` option) nothing says what fits, so
+the default skips with `'no-window'`.
+
+**Options** — `auto` (default `true`; `false` is **manual only**: only a person's request compacts —
+Compact now, Retry, `compact()`, `aparte-compact` — and neither the after-turn, the before-send nor
+the overflow attempt is made, so a model's overflow error stands as it did before the plugin; so
+does `listen: false`), `threshold` (default `0.8`), `contextWindow` (the window when the model declares none),
+`selector` (your own `(messages) => { keep, drop }`; `createCompactionSelector` builds the
+budget-aware one), `prompt`, `keyResolver`, `summarize` (replace the model call: your endpoint, a
+cheaper model), `resolveTarget` (a transcript in a store: `{ getMessages, updateMessage }`),
+`scopeToTargetId` (one setup per chat on a multi-chat page), `keepWithoutWindow`, `listen`. The
+config comes last, like every `setup*`: `setupCompaction(options, config)`.
 
-**Events**, on `window`, each naming the chat: `aparte-compact-start`, `aparte-compact-done`
-(`{ summary, kept, dropped }`, or `{ skipped: true, reason }` — `empty`, `nothing-to-drop`,
-`running`, `streaming`), `aparte-compact-error` (`{ error }`).
+**Events**, on `window`, each naming the chat and the message the checkpoint sits on:
+`aparte-compact-start`, `aparte-compact-done` (`{ summary, kept, dropped, count }`, `{ skipped:
+true, reason }` — `empty`, `nothing-to-drop`, `running`, `streaming`, `no-window` — or `{ restored:
+true }`), `aparte-compact-error` (`{ error }`).
 
 **The budget**, exported for a host that wants the numbers: `computeHistoryBudget`,
-`splitHistoryBudget`, `estimateTokens`, `estimateTokensJson`, `DEFAULT_COMPACTION_CONFIG`;
-and `transcriptForSummary` / `messageText` / `DEFAULT_COMPACTION_PROMPT` for a `summarize`
-of your own that wants the same transcript.
+`splitHistoryBudget`, `estimateTokens`, `estimateTokensJson`, `DEFAULT_COMPACTION_CONFIG`; and
+`transcriptForSummary` / `messageText` / `DEFAULT_COMPACTION_PROMPT` for a `summarize` of your
+own that wants the same transcript.
 
 `@aparte/core` is the only **peer dependency**. No element, no DOM at import: the same entry
 serves the browser and Node.

package/dist/budget.d.ts

@@ -16,6 +16,7 @@
  * reports usage and lets the caller decide — so it moved here, next to the one thing
  * that does: the compaction this plugin performs. Zero deps, a char-count heuristic.
  */
+import { estimateTokens } from '@aparte/core';
 export interface CompactionConfig {
     /** Total context window of the active model, in tokens. */
     contextWindow: number;
@@ -35,8 +36,10 @@ export interface CompactionConfig {
      */
     summaryRatio: number;
     /**
-     * Ceiling on that reservation, in tokens. It sizes the WINDOW — it does not bound
-     * the summary your `summarize` returns, and nothing here truncates one.
+     * Ceiling on that reservation, in tokens. It sizes the WINDOW: the verbatim turns
+     * leave this much room for the summary. The summary request's own `maxTokens` is a
+     * looser ceiling that only keeps the answer inside the window (see `setupCompaction`),
+     * and a summary no shorter than the turns it replaces is refused.
      */
     summaryMaxTokens: number;
 }
@@ -59,9 +62,9 @@ export interface BudgetResult {
  * The history budget, split: the room held back for the running summary, and the
  * verbatim window that is what remains.
  *
- * `summary` is a RESERVATION, read only to shrink `window`. Nothing measures the
- * summary against it, and nothing clips one that comes back longer — a summariser that
- * overruns simply costs the turn more than the split assumed.
+ * `summary` is a RESERVATION, read to shrink `window`. The summary request carries a
+ * looser `maxTokens` of its own (it keeps the answer inside the window), and a summary
+ * that is cut off at that limit, or no shorter than the turns it replaces, is refused.
  */
 export interface SplitBudget {
     summary: number;
@@ -69,11 +72,13 @@ export interface SplitBudget {
 }
 export declare const DEFAULT_COMPACTION_CONFIG: CompactionConfig;
 /**
- * Token heuristic (FR ~3.5 chars/tok, EN ~4 chars/tok).
- * Accurate to ±10% — enough for budgeting, and it avoids `tokenizer.encode()`,
- * which costs ~5ms per message × N (too slow to run on every turn).
+ * Token heuristic — core's, re-exported under the name this module always had.
+ *
+ * It lives in `@aparte/core` (`estimateTokens`) because the context gauge and the count
+ * the client records on each reply read the SAME estimate: a plugin that kept a private copy
+ * would decide on figures the page does not show.
  */
-export declare function estimateTokens(text: string | null | undefined): number;
+export { estimateTokens };
 /**
  * Estimate tokens for a JSON-serializable structure (e.g. tools array).
  */

package/dist/budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,WAAW,gBAAgB;IAC7B,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAClB;AAID,eAAO,MAAM,yBAAyB,EAAE,gBAYvC,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGtE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAOvD;AAID;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC,GAAG,YAAY,CA2Bf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAC9B,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,gBAA4C,GAClD,WAAW,CAGb"}
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAI9C,MAAM,WAAW,gBAAgB;IAC7B,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAClB;AAID,eAAO,MAAM,yBAAyB,EAAE,gBAYvC,CAAC;AAIF;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAOvD;AAID;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC,GAAG,YAAY,CA2Bf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAC9B,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,gBAA4C,GAClD,WAAW,CAGb"}

package/dist/compaction.d.ts

@@ -2,103 +2,132 @@
  * compaction.ts — `setupCompaction`: the controller that answers `aparte-compact`.
  *
  * One compaction is: resolve the chat, select what to summarise (the budget-aware
- * selector over the current model by default), summarise it through the config's
- * transport — or a summariser of the host's — then replace the transcript with the
- * summary as a notice followed by the kept turns verbatim. Every step that can fail
- * reports on `window` (`aparte-compact-start` / `-done` / `-error`, each naming the
- * chat) AND in the returned outcome, so a host that called `compact()` itself never
- * has to listen for the answer to its own call.
+ * selector over the model's view of the conversation by default), summarise it through
+ * the config's transport — or a summariser of the host's — then write the summary as a
+ * CHECKPOINT on the first message that stays verbatim. Nothing is deleted: the messages
+ * above the checkpoint stay on the screen and in storage, and the history the client
+ * builds resumes from the checkpoint, so the model reads the summary in their place.
+ * Every step that can fail reports on `window` (`aparte-compact-start` / `-done` /
+ * `-error`, each naming the chat) AND in the returned outcome, so a host that called
+ * `compact()` itself never has to listen for the answer to its own call.
  *
  * What this file is careful about, each learned on the client's version of it:
- *   - one compaction at a time per setup — a second request while one runs is
- *     reported skipped, not started (two paid summaries, both replacing the transcript);
- *   - a transcript with a turn in flight is left alone — summarising under a streaming
- *     reply would drop it;
- *   - the summarisation has its OWN abort controller, reached by `abort()` and by an
- *     `aparte-abort` addressed to the chat, so a summary the user cancelled stops there;
- *   - and a summary nobody cancelled is refused too when the transcript it was written
- *     from is gone: if not one selected turn is left on the target when the model
- *     answers, the conversation was switched (or reset) underneath, and the summary
- *     would land over a transcript it never read;
- *   - what arrived while the summary was being written is kept: the replacement is
- *     summary, then the kept turns, then anything newer than the selection;
+ *   - one compaction at a time per CHAT — a second request for a chat whose summary is
+ *     being written is reported skipped, not started (two paid summaries, both written),
+ *     while another chat on the same setup compacts on its own;
+ *   - a transcript with a turn in flight is left alone — except the turn being PREPARED
+ *     (a send or retry the client is about to make), which the caller names in
+ *     `exclude`: it is neither summarised nor counted as in flight;
+ *   - the summarisation has its OWN abort controller, reached by `abort()`, by an
+ *     `aparte-abort` addressed to the chat and by the abort signal of the request that
+ *     asked for it (the client's Stop), so a summary the user cancelled stops there, and a
+ *     Restore of the same chat cancels it too;
+ *   - and a summary nobody cancelled is refused too when the message it was to sit on
+ *     is no longer on the chat's path, or the checkpoint it updates was taken off: the
+ *     conversation was switched (or reset) or restored underneath, and a success the host
+ *     dropped would be reported as one;
+ *   - the checkpoint is the model's own update of the one before it: a second compaction
+ *     sends "Summary so far:" and only the messages since, not the whole history again;
  *   - a chat is addressed by id through the same rule the gauge and the client use, and
  *     `scopeToTargetId` makes a setup answer one chat on a page that has several.
  */
-import { type AparteConfig, type AparteMessage, type AparteChatRequest } from '@aparte/core';
+import { type AparteConfig, type AparteMessage, type AparteChatRequest, type AparteCompactor, type AparteCompactorOutcome, type AparteCompactorRequest } from '@aparte/core';
 import { type CompactionSelection } from './selector.js';
 /**
- * The three things a chat must expose to be compacted: read the active path, empty
- * it, append to it. `<aparte-chat-viewport>` does; an `<aparte-chat>` shell hands over
- * its viewport. A host whose transcript lives elsewhere (a framework store) gives
- * `resolveTarget` an object of its own.
+ * What a chat must expose to be compacted: read the active path and update one message
+ * of it. `<aparte-chat-viewport>` does; an `<aparte-chat>` shell hands over its viewport.
+ * A host whose transcript lives elsewhere (a framework store) gives `resolveTarget` an
+ * object of its own.
  */
 export interface CompactionTarget {
     getMessages(): AparteMessage[];
     /**
-     * Empty the transcript. A compaction passes `{ revokeAttachments: false }`,
-     * because it puts the kept turns straight back: `<aparte-chat-viewport>` releases
-     * every message's object URLs on the way out, which killed the images and files of
-     * the turns the compaction was keeping. It revokes the summarised-away ones itself
-     * afterwards. A target that ignores the argument keeps working — it just leaks the
-     * URLs of what it drops, which is what it did before this existed.
+     * Merge `updates` into one message of the path — the one write a compaction makes: the
+     * checkpoint (`contextSummary`) on the first message that stays. A target without it
+     * cannot hold a checkpoint, and the compaction fails with an error saying so rather
+     * than falling back to rewriting the transcript.
      */
-    clearAll(options?: {
+    updateMessage?(messageId: string, updates: Partial<AparteMessage>): void;
+    /**
+     * Not called any more. A compaction used to empty the transcript and put the kept turns
+     * back; it now writes one checkpoint and removes nothing. Still accepted, so a target
+     * written for the earlier contract keeps type-checking.
+     */
+    clearAll?(options?: {
         revokeAttachments?: boolean;
     }): void;
-    appendMessage(message: AparteMessage): void;
+    /** Not called any more; see `clearAll`. */
+    appendMessage?(message: AparteMessage): void;
 }
 /** Which messages are summarised (`drop`) and which stay verbatim (`keep`). Pure — no model call. */
 export type CompactionMessageSelector = (messages: AparteMessage[]) => CompactionSelection<AparteMessage>;
 /** The key (or record of settings) for a provider — the same shape `AparteClientOptions.keyResolver` takes. */
 export type CompactionKeyResolver = (providerId: string) => string | Record<string, string> | undefined | null | Promise<string | Record<string, string> | undefined | null>;
-/** Replaces the model call: given the summarisation request, return the summary text. */
+/**
+ * Replaces the model call: given the summarisation request, return the summary text.
+ * The request asks for a stream (`stream: true`) and carries `maxTokens`, a ceiling on the
+ * answer that keeps it inside the window — a summariser that talks to a model should pass both on.
+ */
 export type CompactionSummarizer = (request: AparteChatRequest, signal: AbortSignal) => Promise<string>;
 /** Why a compaction did nothing. */
 export type CompactionSkipReason = 
 /** The transcript is empty. */
 'empty'
-/** The selector kept everything — within budget, or nothing older than what is kept. */
+/**
+ * The selector kept everything — within budget, or nothing older than what is kept —
+ * or no user message could carry the checkpoint (the first message kept must be the
+ * user's). Also what an automatic request is told when the back-off, a Restore or the
+ * hysteresis says not to try now, and what an automatic or overflow request is told
+ * when `auto: false` (or `listen: false`) keeps the setup manual.
+ */
  | 'nothing-to-drop'
-/** A compaction is already running for this setup. */
+/** A compaction is already running for this chat. */
  | 'running'
-/** A turn is in flight in the transcript; compacting under it would drop it. */
- | 'streaming';
-export type CompactionOutcome = {
-    ok: true;
-    skipped: true;
-    reason: CompactionSkipReason;
-    targetId?: string;
-} | {
-    ok: true;
-    skipped: false;
-    summary: string;
-    kept: number;
-    dropped: number;
-    targetId?: string;
-} | {
-    ok: false;
-    error: string;
-    targetId?: string;
-};
+/** A turn is in flight in the transcript; compacting under it would summarise a half-written reply. */
+ | 'streaming'
+/**
+ * The current model declares no `contextWindow` and nothing of the host's sizes the
+ * request (no `selector`, no `summarize`, no `keepWithoutWindow`). Without a window the
+ * default would send everything but the last few messages in one request, which a small
+ * model refuses as over its context. Declare the window, or pass one of the three.
+ */
+ | 'no-window';
+/** How a compaction ended — core's outcome, the same type the compactor seam returns. */
+export type CompactionOutcome = AparteCompactorOutcome;
 export interface CompactionSetupOptions {
     /**
-     * Which messages are summarised away and which stay verbatim.
+     * Which messages are summarised and which stay verbatim, over what the model reads:
+     * the messages from the latest checkpoint on, minus the turn being prepared.
      *
      * Default: `createCompactionSelector` over the current model — its `contextWindow`,
      * the resolved system prompt and the registered tools set the budget, and the
-     * newest turns that fit the window stay. When the current model declares no
-     * window there is no budget to walk, so the last `keepWithoutWindow` messages
-     * stay and the rest is summarised.
+     * newest turns that fit stay. Each compaction sizes it: to land below the `threshold`
+     * (about `threshold − 0.2` of the window once the fixed costs are paid, so one
+     * compaction buys several turns), with room for the turn being prepared, and in the
+     * model's own tokens (the heuristic's undercount, as the context gauge calibrates it).
+     * A `selector` of your own is called with the messages alone and keeps what it keeps.
+     * Whatever it chooses, the cut is moved so the
+     * first message kept is a user message (the checkpoint sits on it). When the current
+     * model declares no window there is no budget to walk, and the compaction skips
+     * (`'no-window'`) unless the host sizes the request itself: a `selector`, a
+     * `summarize` or `keepWithoutWindow`.
      */
     selector?: CompactionMessageSelector;
-    /** How many of the newest messages stay when the model declares no window. Default 4 — the last two exchanges. */
+    /**
+     * How many of the newest messages stay when the model declares no window; everything
+     * older goes to the summariser in ONE request, so the number is the host's bet that it
+     * fits the model. Passing it is the opt-in: left out, a model without a window makes the
+     * default compaction skip with `'no-window'`, since nothing says the request would fit.
+     * Without a `selector` of your own, `4` (the last two exchanges) is what it takes when
+     * you opt in through `summarize` alone. Ignored when the model declares a window.
+     */
     keepWithoutWindow?: number;
     /**
      * The summariser's instruction — carried by the ask itself, not by a `system`
      * message, so a provider that imposes its own system prompt cannot drop it.
      * English by default — it is addressed to the model, not to the user — asking for
-     * the decisions, the open tasks and the tool results that still matter. Replace it
+     * fixed sections (the goal, the decisions, the open tasks, the facts and tool results
+     * still needed, the next step) in the language of the conversation. Replace it
      * to steer the summary (a language, a domain, a length).
      */
     prompt?: string;
@@ -110,51 +139,118 @@ export interface CompactionSetupOptions {
     keyResolver?: CompactionKeyResolver;
     /**
      * Replace the model call entirely. The request carries the transcript of the
-     * dropped turns, then a final `user` message holding the summariser's instruction
-     * and the ask, and `_meta: { compaction: true }`; return the summary text. For a
+     * turns being summarised, then a final `user` message holding the summariser's
+     * instruction and the ask, `stream: true`, `maxTokens` (a ceiling on the answer that
+     * keeps it inside the window) and `_meta: { compaction: true }`; return the summary
+     * text. When an earlier checkpoint exists the request opens with "Summary so far:" and
+     * that summary, and asks for an updated one. Your own call
+     * is not trimmed to the window — the sizing is yours — but a summary that is no
+     * shorter than the turns it replaces is still refused. For a
      * host with an endpoint of its own, or a cheaper model for summaries. With one, no
      * provider needs to be configured at all.
      */
     summarize?: CompactionSummarizer;
     /**
-     * Resolve the chat to compact. Default: the element whose id is the `targetId`
-     * (or, unnamed, the first `<aparte-chat>` / `<aparte-chat-viewport>` /
-     * `[data-aparte-chat]` on the page), taking its viewport when the element itself
-     * cannot render. Return your own object for a transcript that lives in a store.
+     * Resolve the chat to compact. Default: the chat element the request carries (the
+     * compactor seam passes it, so a chat inside a shadow root is found), else the element
+     * whose id is the `targetId` (or, unnamed, the first `<aparte-chat>` /
+     * `<aparte-chat-viewport>` / `[data-aparte-chat]` on the page), taking its viewport
+     * when the element itself cannot render. Return your own object for a transcript that
+     * lives in a store.
      */
     resolveTarget?: (targetId?: string) => CompactionTarget | null;
     /**
      * Answer only the `aparte-compact` and `aparte-abort` events that name this chat
-     * id, and compact it when `compact()` is called without one. For a page with
-     * several chats and one setup per chat.
+     * id, and compact it when `compact()` is called without one. A request for another chat
+     * is refused. For a page with several chats and one setup per chat — and note that the
+     * config has ONE compactor: the setup made last on a config is the one the client and
+     * the gauge call.
      */
     scopeToTargetId?: string;
-    /** Listen for `aparte-compact` and `aparte-abort` on `window`. Default `true`; `false` for a host that calls `compact()` itself. */
+    /**
+     * Listen for `aparte-compact` and `aparte-abort` on `window`. Default `true`; `false` for
+     * a host that calls `compact()` itself.
+     *
+     * `false` also keeps compaction manual, whatever `auto` says (see `auto`): a setup that
+     * hears nothing decides nothing. A Stop still cancels a summary: the client hands the
+     * turn's abort signal to the compactor, so it does not depend on this listener.
+     */
     listen?: boolean;
+    /**
+     * Compact by itself. Default `true`: once set up, the plugin summarises a chat when a
+     * turn ends with the context at `threshold` of its window, before a send whose request
+     * would not fit — the client asks first (`beforeSend`) — and when the model refuses a
+     * request as over its window (the client asks again, with `reason: 'overflow'`, and
+     * sends the turn once more).
+     *
+     * `false` means MANUAL ONLY: only a person's request compacts (the gauge's Compact now,
+     * a separator's Retry, `compact()`, `aparte-compact`). None of the three automatic
+     * attempts is made, the overflow included — `compact()` answers an `'auto'` or
+     * `'overflow'` request with a skip, so the model's error stands exactly as it did before
+     * the plugin. Forced `false` with `listen: false` (a setup that hears nothing decides
+     * nothing).
+     *
+     * It acts only when a summariser can run: a provider registered for the current model,
+     * or a `summarize` of the host's. It never acts on a Restore, a conversation switch or a
+     * load, and never again after two failures in a row until something succeeds or a person
+     * asks (see the back-off in the docs).
+     */
+    auto?: boolean;
+    /**
+     * The share of the window, from 0 to 1, at which a turn's end triggers a compaction.
+     * Default `0.8`. The gauge's own levels are independent of it.
+     *
+     * A compaction aims lower than the threshold: with the default selector it leaves the
+     * history the model reads at about `threshold − 0.2` of the window, less the fixed costs
+     * (the system prompt, the tools, the room for the reply, the summary's slot), so one
+     * compaction buys several turns and the next is not asked for after this one. That holds
+     * for a person's request and an overflow retry too; a `selector` of your own is left
+     * alone. If the context is still at the threshold afterwards (a long recent tail the
+     * selector must keep), the after-turn trigger waits until a turn ends below it; a request
+     * that would not fit is still compacted before it is sent, and an overflow still retried.
+     */
+    threshold?: number;
+    /**
+     * The window to measure against when the current model declares none — a number, or a
+     * getter read at each use (`() => settings.contextWindow`). A local server has no
+     * window the page can read, and without one nothing is automatic and the default
+     * selector skips. The model's own `contextWindow` wins when it declares one. For one
+     * more release, the `window` a gauge sends with its `aparte-compact` request is read
+     * as a last resort.
+     */
+    contextWindow?: number | (() => number | undefined);
 }
-export interface CompactionController {
+/**
+ * The controller `setupCompaction` returns — and the compactor it registers on the
+ * config (`AparteConfig.setCompactor`), so the gauge and the client call the same object
+ * a host does.
+ */
+export interface CompactionController extends Omit<AparteCompactor, 'compact' | 'beforeSend' | 'preview'>, Required<Pick<AparteCompactor, 'beforeSend' | 'preview'>> {
     /**
-     * Compact one chat — the one `targetId` names, else the scoped one, else the
-     * first on the page. Never rejects: the outcome says what happened, and the
+     * Compact one chat. Takes the compactor seam's request (the chat element, its id, the
+     * ids of a turn being prepared, why) or, as it always did, a chat id, or nothing:
+     * the scoped chat, else the first on the page. A string or nothing is a person's
+     * request (`reason: 'manual'`). Never rejects: the outcome says what happened, and the
      * same information goes out as `aparte-compact-done` / `aparte-compact-error`.
      */
-    compact(targetId?: string): Promise<CompactionOutcome>;
-    /** Abort the summarisation in flight, if any. The transcript is left untouched. */
+    compact(request?: string | AparteCompactorRequest): Promise<CompactionOutcome>;
+    /** Abort the summarisations in flight, if any. The transcripts are left untouched. */
     abort(): void;
-    /** `true` while a summarisation is in flight. */
+    /** `true` while a summarisation is in flight, for any chat of this setup. */
     readonly running: boolean;
-    /** Remove the listeners and forget this setup; an in-flight summarisation is aborted. */
+    /** Remove the listeners and forget this setup; an in-flight summarisation is aborted and the compactor unregistered. */
     dispose(): void;
 }
 /**
- * Install compaction on a config. Returns the controller; the same call on the same
- * config replaces the previous setup (its listeners are removed first).
+ * Install compaction on a config. Returns the controller, which is also registered as the
+ * config's compactor; the same call on the same config replaces the previous setup (its
+ * listeners are removed first).
  *
  * ```ts
  * import { setupCompaction } from '@aparte/plugin-compaction';
  *
  * const compaction = setupCompaction();          // the global config, the current model's budget
- * // `<aparte-context auto-compact>` now asks for a compaction on reaching 90 %;
+ * // `<aparte-context>` now offers "Compact now", and the separator's Retry works;
  * // or ask yourself:
  * await compaction.compact();
  * ```

package/dist/compaction.d.ts.map

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

package/dist/cut.d.ts

@@ -0,0 +1,53 @@
+/**
+ * cut.ts — where a checkpoint sits, and the one thing a summary must not lose.
+ *
+ * Two small pure pieces `compact()` leans on, kept out of it so each can be read (and
+ * tested) without a model call in sight.
+ */
+/**
+ * The index of the first message that stays verbatim, moved so it is a USER message.
+ *
+ * A checkpoint is read by the model as "the summary, then this message and everything
+ * after it", and every provider wants the first turn after a preamble to be the user's:
+ * a history that resumes on an assistant reply is refused by some templates and
+ * misread by the rest. So the boundary the selector chose (`boundary`, the count of
+ * leading messages it dropped) is moved toward the OLDER end until it lands on a user
+ * message, which keeps more verbatim and summarises less than the selector asked for.
+ * When that would summarise nothing at all, it moves toward the NEWER end instead, which
+ * summarises a little more. A kept message has to exist to carry the checkpoint, so the
+ * boundary never goes past the last message.
+ *
+ * `null` when no user message qualifies — there is nothing a checkpoint could sit on.
+ */
+export declare function cutAtUser(messages: ReadonlyArray<{
+    role: string;
+}>, boundary: number): number | null;
+/**
+ * The line that introduces the conversation's first request inside a stored summary.
+ * English and fixed, because the summary is addressed to the model and because an
+ * update of the summary has to find the block again (see {@link splitFirstRequest}).
+ */
+export declare const FIRST_REQUEST_LINE = "The conversation's first request, verbatim:";
+/** The most of the first request a summary carries. */
+export declare const FIRST_REQUEST_MAX = 1500;
+/**
+ * The first request, appended to the model's summary under {@link FIRST_REQUEST_LINE}.
+ *
+ * It is not written by the model: what the user first asked is the one piece of a
+ * conversation every later turn is judged against, and a summariser paraphrases it away
+ * as readily as anything else. Clipped, so a pasted document does not become the summary.
+ */
+export declare function firstRequestBlock(text: string): string;
+/**
+ * A stored summary taken apart: what the model wrote, and the first-request block that
+ * was appended to it (empty when there is none).
+ *
+ * An update of a summary hands the model the first part only and puts the second back
+ * unchanged afterwards. Handing it the whole thing would have it copy the block into
+ * its own answer, and the block would be there twice.
+ */
+export declare function splitFirstRequest(summary: string): {
+    base: string;
+    block: string;
+};
+//# sourceMappingURL=cut.d.ts.map

package/dist/cut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut.d.ts","sourceRoot":"","sources":["../src/cut.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpG;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,gDAAgD,CAAC;AAEhF,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAItD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAGlF"}