@nathapp/nax-agent 0.91.7 → 0.91.8-canary.2

package/dist/memory/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The memory note model — the shapes and limits shared by the note codec, the
+ * mirror store, the index renderer, the providers and the sync loop.
+ *
+ * A note is one Markdown file with frontmatter (`note.ts` writes and reads it);
+ * a decision is one line of the mirror's read-only `decisions.jsonl`; a hit is
+ * one keyword-search result; a timers object is the race seam the sync loop
+ * injects in tests.
+ */
+export declare const MEMORY_NOTE_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryNoteType = (typeof MEMORY_NOTE_TYPES)[number];
+export declare const MEMORY_SCOPES: readonly ["project", "user"];
+export type MemoryScope = (typeof MEMORY_SCOPES)[number];
+export declare const MEMORY_NOTE_STATUSES: readonly ["active", "pending", "superseded", "rejected", "deleted"];
+export type MemoryNoteStatus = (typeof MEMORY_NOTE_STATUSES)[number];
+export declare const MEMORY_DECISION_STATUSES: readonly ["active", "superseded", "rejected"];
+export type MemoryDecisionStatus = (typeof MEMORY_DECISION_STATUSES)[number];
+export interface MemoryNote {
+    readonly id: string;
+    readonly slug: string;
+    readonly type: MemoryNoteType;
+    readonly scope: MemoryScope;
+    readonly description: string;
+    readonly source: string;
+    readonly updatedAt: string;
+    readonly status: MemoryNoteStatus;
+    readonly body: string;
+}
+export interface MemoryDecision {
+    readonly id: string;
+    readonly subject: string;
+    readonly predicate: string;
+    readonly object: string;
+    readonly updatedAt: string;
+    readonly status: MemoryDecisionStatus;
+}
+/**
+ * One queued forget: a `proposal` forget the mirror accepted but did not act on, kept in
+ * the mirror's `pending-forgets.jsonl` so it outlives the process that asked for it — the
+ * index marks it and an approval finds it later. The `clientId` is the write's idempotency
+ * key, and `reason` is the justification the forget carried (`""` when it carried none).
+ */
+export interface MemoryPendingForget {
+    readonly clientId: string;
+    readonly scope: MemoryScope;
+    readonly slug: string;
+    readonly reason: string;
+}
+export interface MemoryHit {
+    readonly slug: string;
+    readonly scope: MemoryScope;
+    readonly type: MemoryNoteType;
+    readonly description: string;
+    readonly status: MemoryNoteStatus;
+    readonly score: number;
+    readonly snippet: string;
+}
+export interface MemoryNoteWrite {
+    readonly slug: string;
+    readonly type: MemoryNoteType;
+    readonly scope: MemoryScope;
+    readonly description: string;
+    readonly body: string;
+}
+export interface MemoryWriteRefusal {
+    readonly field: "slug" | "type" | "description" | "body" | "source" | "reason";
+    readonly reason: string;
+}
+export interface MemoryTimers {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(id: unknown): void;
+}
+/** A note slug: 1-64 characters, lower-case alphanumerics and interior `-`. */
+export declare const MEMORY_SLUG_RE: RegExp;
+/** An outbox client id: 1-128 letters, digits, `_` or `-`. */
+export declare const MEMORY_CLIENT_ID_RE: RegExp;
+export declare const MEMORY_NOTE_BODY_MAX_BYTES = 8192;
+export declare const MEMORY_DESCRIPTION_MAX_CHARS = 200;
+export declare const MEMORY_SOURCE_MAX_CHARS = 64;
+/**
+ * The longest justification a forget may carry.
+ *
+ * A reason is a one-line answer to "why did this note go", and it is persisted twice over: on
+ * the request the provider is pushed, and inside the outbox entry a forget that cannot be
+ * delivered leaves behind. Bounding it here — the same cap as a note's description, because it
+ * is the same kind of text — keeps a terminal or a step from filling the mirror's queue with a
+ * justification of its own making. `forgetReasonRefusal` is where the rule is applied to a
+ * forget, and the outbox applies that same rule when it takes a request, so the queue never
+ * holds one it cannot replay. An entry already on disk is read whatever its reason's length:
+ * the bound is a condition on writing, not on reading.
+ */
+export declare const MEMORY_FORGET_REASON_MAX_CHARS = 200;
+export declare const MEMORY_INDEX_MAX_BYTES = 24576;
+export declare const MEMORY_INDEX_MAX_LINES = 200;
+export declare const MEMORY_INDEX_MIN_LINES = 16;
+export declare const MEMORY_INDEX_MIN_BYTES = 512;
+export declare const MEMORY_PROBE_TIMEOUT_MS = 2000;
+export declare const MEMORY_OP_TIMEOUT_MS = 10000;
+export declare const MEMORY_PULL_PAGE_SIZE = 200;
+export declare const MEMORY_PULL_MAX_PAGES = 50;
+/**
+ * The key a note is addressed by wherever the mirror and the queue meet: `<scope>/<slug>`.
+ *
+ * The outbox holds writes by this key and a save asks the outbox whether the key it is
+ * about to write is already held, so the two spellings have to be one: a save that asks
+ * with a different key would never see the entry it must queue behind.
+ */
+export declare function memoryNoteKey(scope: MemoryScope, slug: string): string;

package/dist/memory/types.js

@@ -0,0 +1,51 @@
+/**
+ * The memory note model — the shapes and limits shared by the note codec, the
+ * mirror store, the index renderer, the providers and the sync loop.
+ *
+ * A note is one Markdown file with frontmatter (`note.ts` writes and reads it);
+ * a decision is one line of the mirror's read-only `decisions.jsonl`; a hit is
+ * one keyword-search result; a timers object is the race seam the sync loop
+ * injects in tests.
+ */
+export const MEMORY_NOTE_TYPES = ["user", "feedback", "project", "reference"];
+export const MEMORY_SCOPES = ["project", "user"];
+export const MEMORY_NOTE_STATUSES = ["active", "pending", "superseded", "rejected", "deleted"];
+export const MEMORY_DECISION_STATUSES = ["active", "superseded", "rejected"];
+/** A note slug: 1-64 characters, lower-case alphanumerics and interior `-`. */
+export const MEMORY_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** An outbox client id: 1-128 letters, digits, `_` or `-`. */
+export const MEMORY_CLIENT_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+export const MEMORY_NOTE_BODY_MAX_BYTES = 8192;
+export const MEMORY_DESCRIPTION_MAX_CHARS = 200;
+export const MEMORY_SOURCE_MAX_CHARS = 64;
+/**
+ * The longest justification a forget may carry.
+ *
+ * A reason is a one-line answer to "why did this note go", and it is persisted twice over: on
+ * the request the provider is pushed, and inside the outbox entry a forget that cannot be
+ * delivered leaves behind. Bounding it here — the same cap as a note's description, because it
+ * is the same kind of text — keeps a terminal or a step from filling the mirror's queue with a
+ * justification of its own making. `forgetReasonRefusal` is where the rule is applied to a
+ * forget, and the outbox applies that same rule when it takes a request, so the queue never
+ * holds one it cannot replay. An entry already on disk is read whatever its reason's length:
+ * the bound is a condition on writing, not on reading.
+ */
+export const MEMORY_FORGET_REASON_MAX_CHARS = 200;
+export const MEMORY_INDEX_MAX_BYTES = 24_576;
+export const MEMORY_INDEX_MAX_LINES = 200;
+export const MEMORY_INDEX_MIN_LINES = 16;
+export const MEMORY_INDEX_MIN_BYTES = 512;
+export const MEMORY_PROBE_TIMEOUT_MS = 2000;
+export const MEMORY_OP_TIMEOUT_MS = 10_000;
+export const MEMORY_PULL_PAGE_SIZE = 200;
+export const MEMORY_PULL_MAX_PAGES = 50;
+/**
+ * The key a note is addressed by wherever the mirror and the queue meet: `<scope>/<slug>`.
+ *
+ * The outbox holds writes by this key and a save asks the outbox whether the key it is
+ * about to write is already held, so the two spellings have to be one: a save that asks
+ * with a different key would never see the entry it must queue behind.
+ */
+export function memoryNoteKey(scope, slug) {
+    return `${scope}/${slug}`;
+}

package/dist/memory/validate.d.ts

@@ -0,0 +1,31 @@
+import { type MemoryNoteWrite, type MemoryWriteRefusal } from "./types.ts";
+/**
+ * The write as received. `type` stays `string` because the value arrives from
+ * an agent tool call: narrowing it in the type system would leave the runtime
+ * check unreachable without a cast in the very test that has to exercise it.
+ */
+export type MemoryNoteWriteInput = Omit<MemoryNoteWrite, "type"> & {
+    readonly type: string;
+};
+/**
+ * The first secret-shaped run in `text`, as its pattern's `kind` label. Every
+ * pattern carries the `/g` flag (the logger needs it for `replace`), so
+ * `lastIndex` is reset before each scan — otherwise a second call would resume
+ * where the first stopped and skip a match.
+ */
+export declare function findSecret(text: string): {
+    readonly kind: string;
+} | null;
+/**
+ * The refusal for a forget's reason, or `null` when it may be recorded.
+ *
+ * A reason is what a later session reads to know why a note went, so it is held to the same
+ * one-line, non-empty, length-capped rule as a note's description: it is persisted on the
+ * request and inside a queued entry, and neither of those is a place to keep an essay.
+ */
+export declare function forgetReasonRefusal(reason: string): MemoryWriteRefusal | null;
+/**
+ * The refusal for a note write, or `null` when it may be stored. Stops at the
+ * first problem, in the design's order, so the caller reports one reason.
+ */
+export declare function validateMemoryNoteWrite(write: MemoryNoteWriteInput, source: string): MemoryWriteRefusal | null;

package/dist/memory/validate.js

@@ -0,0 +1,104 @@
+/**
+ * Write validation — the check a save runs before anything is persisted.
+ *
+ * `validateMemoryNoteWrite` answers one question for the save path
+ * (`operations.ts`): may this note be stored at all? It returns `null` when it
+ * may, or the first `MemoryWriteRefusal` it found, checking in the design's
+ * order: slug, type, description, source, body size, then secrets.
+ *
+ * `findSecret` is the secret half on its own: it runs the logger's
+ * `SECRET_VALUE_PATTERNS` over free text and reports the kind of the first
+ * accepted match. Both functions are pure — no file, no logger, no I/O — so the
+ * refusal text is all the caller has to work with, and it never contains the
+ * matched text.
+ */
+import { SECRET_VALUE_PATTERNS } from "#src/internal/redact";
+import { MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_TYPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, } from "./types.js";
+/** A one-line field may carry no line break and no ASCII control character (a tab or DEL included). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point of this check
+const CONTROL_OR_LINE_BREAK = /[\u0000-\u001f\u007f]/;
+function isMemoryNoteType(value) {
+    return MEMORY_NOTE_TYPES.some((type) => type === value);
+}
+function slugRefusal(slug) {
+    if (MEMORY_SLUG_RE.test(slug))
+        return null;
+    return { field: "slug", reason: 'slug must be 1-64 lower-case letters, digits or "-"' };
+}
+function typeRefusal(type) {
+    if (isMemoryNoteType(type))
+        return null;
+    return { field: "type", reason: `type must be one of ${MEMORY_NOTE_TYPES.join(", ")}` };
+}
+/** The shared check for `description` and `source`: non-empty, one line, at most `maxChars`. */
+function lineRefusal(field, text, maxChars) {
+    if (text === "")
+        return { field, reason: `${field} must not be empty` };
+    if (CONTROL_OR_LINE_BREAK.test(text)) {
+        return { field, reason: `${field} must not contain a line break or control character` };
+    }
+    if (text.length > maxChars)
+        return { field, reason: `${field} must be at most ${maxChars} characters` };
+    return null;
+}
+/** The body cap counts UTF-8 bytes, so a multi-byte body can fail below the character limit. */
+function bodyRefusal(body) {
+    if (Buffer.byteLength(body, "utf8") <= MEMORY_NOTE_BODY_MAX_BYTES)
+        return null;
+    return { field: "body", reason: `body must be at most ${MEMORY_NOTE_BODY_MAX_BYTES} bytes` };
+}
+/**
+ * A refusal when `text` carries a secret. The reason names the pattern's kind
+ * and never the matched text: a refusal is shown to the agent and logged.
+ */
+function secretRefusal(field, text) {
+    const secret = findSecret(text);
+    return secret === null ? null : { field, reason: `secret (${secret.kind}) must not be stored` };
+}
+/**
+ * The first secret-shaped run in `text`, as its pattern's `kind` label. Every
+ * pattern carries the `/g` flag (the logger needs it for `replace`), so
+ * `lastIndex` is reset before each scan — otherwise a second call would resume
+ * where the first stopped and skip a match.
+ */
+export function findSecret(text) {
+    for (const { kind, re, acceptMatch } of SECRET_VALUE_PATTERNS) {
+        re.lastIndex = 0;
+        let match = re.exec(text);
+        while (match !== null) {
+            const matched = match[0];
+            // A zero-length match would leave `lastIndex` unchanged and spin forever.
+            if (matched === "") {
+                re.lastIndex += 1;
+            }
+            else if (acceptMatch === undefined || acceptMatch(matched)) {
+                return { kind };
+            }
+            match = re.exec(text);
+        }
+    }
+    return null;
+}
+/**
+ * The refusal for a forget's reason, or `null` when it may be recorded.
+ *
+ * A reason is what a later session reads to know why a note went, so it is held to the same
+ * one-line, non-empty, length-capped rule as a note's description: it is persisted on the
+ * request and inside a queued entry, and neither of those is a place to keep an essay.
+ */
+export function forgetReasonRefusal(reason) {
+    return lineRefusal("reason", reason, MEMORY_FORGET_REASON_MAX_CHARS);
+}
+/**
+ * The refusal for a note write, or `null` when it may be stored. Stops at the
+ * first problem, in the design's order, so the caller reports one reason.
+ */
+export function validateMemoryNoteWrite(write, source) {
+    return (slugRefusal(write.slug) ??
+        typeRefusal(write.type) ??
+        lineRefusal("description", write.description, MEMORY_DESCRIPTION_MAX_CHARS) ??
+        lineRefusal("source", source, MEMORY_SOURCE_MAX_CHARS) ??
+        bodyRefusal(write.body) ??
+        secretRefusal("description", write.description) ??
+        secretRefusal("body", write.body));
+}

package/dist/native/adapter-deps.d.ts

@@ -35,6 +35,15 @@ export declare const _adapterDeps: {
      */
     setTimeout: (fn: () => void, ms: number) => unknown;
     clearTimeout: (id: unknown) => void;
+    /**
+     * US-001: the clock the whole-turn deadline measures against, injectable for
+     * the same reason as the timer pair above. `createTurnDeadline` reads it at
+     * every check, so a test can advance a virtual clock past the budget without
+     * waiting the schema's one-second minimum in real time.
+     *
+     * @internal
+     */
+    now: () => number;
 };
 /**
  * US-006: `{ auth }` for the identity the credential store observed for

package/dist/native/adapter-deps.js

@@ -31,6 +31,15 @@ export const _adapterDeps = {
      */
     setTimeout: ((fn, ms) => setTimeout(fn, ms)),
     clearTimeout: ((id) => clearTimeout(id)),
+    /**
+     * US-001: the clock the whole-turn deadline measures against, injectable for
+     * the same reason as the timer pair above. `createTurnDeadline` reads it at
+     * every check, so a test can advance a virtual clock past the budget without
+     * waiting the schema's one-second minimum in real time.
+     *
+     * @internal
+     */
+    now: () => Date.now(),
 };
 /**
  * US-006: `{ auth }` for the identity the credential store observed for

package/dist/native/models.js

@@ -120,6 +120,9 @@ export function toProviderOverrides(overrides) {
             ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
             ...(model.input !== undefined ? { input: model.input } : {}),
             ...(model.thinkingFormat !== undefined ? { thinkingFormat: model.thinkingFormat } : {}),
+            ...(model.thinkingBudgetField !== undefined ? { thinkingBudgetField: model.thinkingBudgetField } : {}),
+            // Copy model declarations so later config mutations cannot change client budgets.
+            ...(model.thinkingBudgets !== undefined ? { thinkingBudgets: { ...model.thinkingBudgets } } : {}),
             supportsTools: model.supportsTools,
             thinkingLevels: model.thinkingLevels,
             // nax#2191: forwarded verbatim. nax-ai's `assertOverrideModelRouting`

package/dist/native/session/compaction.d.ts

@@ -73,6 +73,8 @@ export declare function keepBudget(window: number, cfg: ResolvedCompaction, aggr
  */
 export declare const COMPACTION_SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
 export declare const COMPACTION_SUMMARY_SUFFIX = "\n</summary>\n";
+/** One summary message. The single place its shape is built, so both appliers agree. */
+export declare function summaryMessage(summary: string): TranscriptMessage;
 /**
  * Walk backwards accumulating estimated size; once `keepTokens` is reached, take
  * the nearest valid cut at or after that point.
@@ -90,5 +92,17 @@ export interface CompactionPlan {
     readonly toSummarize: readonly TranscriptMessage[];
     readonly previousSummary?: string;
 }
-export declare function prepareCompaction(messages: readonly TranscriptMessage[], keepTokens: number): CompactionPlan | undefined;
+export interface CompactionOptions {
+    /**
+     * Keep `messages[0]` out of the span and in place (the default), which is what
+     * an automatic compaction does: the run's task prompt survives every compaction
+     * byte-identical (design §Pinning). A MANUAL compaction passes `false` — its
+     * summary takes that position (US-002 AC-2) — and must then summarize the
+     * opening message, or its requirements and images reach neither the summarizer
+     * nor the compacted transcript. `false` starts the span at the opening message
+     * even when an automatic summary sits right behind it at index 1.
+     */
+    readonly pinFirstMessage?: boolean;
+}
+export declare function prepareCompaction(messages: readonly TranscriptMessage[], keepTokens: number, options?: CompactionOptions): CompactionPlan | undefined;
 export declare function applyCompaction(messages: readonly TranscriptMessage[], plan: CompactionPlan, summary: string): TranscriptMessage[];

package/dist/native/session/compaction.js

@@ -98,6 +98,14 @@ export const COMPACTION_SUMMARY_SUFFIX = "\n</summary>\n";
 const PIN_INDEX = 0;
 /** Where the summary sits once written. */
 const SUMMARY_INDEX = 1;
+/** One summary message. The single place its shape is built, so both appliers agree. */
+export function summaryMessage(summary) {
+    return { role: "user", content: COMPACTION_SUMMARY_PREFIX + summary + COMPACTION_SUMMARY_SUFFIX };
+}
+/** True when `message` is one this module wrote as a summary. */
+function isSummaryMessage(message) {
+    return message?.role === "user" && message.content.startsWith(COMPACTION_SUMMARY_PREFIX);
+}
 /**
  * Valid cut points are user or assistant messages, NEVER a tool-result.
  *
@@ -141,38 +149,97 @@ export function findCutPoint(messages, startIndex, keepTokens) {
     }
     return candidate;
 }
-/** Reads a previous summary out of the message at SUMMARY_INDEX, if one is there. */
+/**
+ * Reads a previous summary out of the transcript.
+ *
+ * Two positions are possible. An automatic compaction pins messages[0] and
+ * writes the summary at `SUMMARY_INDEX`; a MANUAL compaction leaves no task
+ * prompt to pin, so its summary sits at `PIN_INDEX` (US-002 AC-2). Both are read
+ * so a second compaction MERGES instead of silently dropping the earlier
+ * summary — the alternative was a manual compaction quietly losing the only
+ * record of the work it shed. Newest first: after an automatic compaction on a
+ * manual one, the summary further in is the merged, newer text.
+ */
 function readPreviousSummary(messages) {
-    const candidate = messages[SUMMARY_INDEX];
-    if (candidate === undefined || candidate.role !== "user")
-        return undefined;
-    if (!candidate.content.startsWith(COMPACTION_SUMMARY_PREFIX))
-        return undefined;
-    return candidate.content.slice(COMPACTION_SUMMARY_PREFIX.length, -COMPACTION_SUMMARY_SUFFIX.length);
+    for (const index of [SUMMARY_INDEX, PIN_INDEX]) {
+        const candidate = messages[index];
+        if (isSummaryMessage(candidate)) {
+            return {
+                text: candidate.content.slice(COMPACTION_SUMMARY_PREFIX.length, -COMPACTION_SUMMARY_SUFFIX.length),
+                index,
+            };
+        }
+    }
+    return undefined;
 }
-export function prepareCompaction(messages, keepTokens) {
-    const previousSummary = readPreviousSummary(messages);
+/**
+ * Where the span to summarize begins.
+ *
+ * A PINNED transcript (the automatic path) starts after `messages[0]`, or after
+ * any summary already in it — that summary is merged, not re-summarized.
+ *
+ * An UNPINNED one (manual compaction) starts at `messages[0]` whatever else the
+ * transcript holds. Its summary takes the pin's position, so the opening message
+ * is being replaced rather than kept, and starting anywhere later would discard
+ * it — requirements, constraints and images included — without summarizing it.
+ * That case is real: after an automatic compaction the opening message is still
+ * at index 0 with the automatic summary right behind it at index 1.
+ */
+function spanStartFor(previous, options) {
+    if (options.pinFirstMessage === false)
+        return PIN_INDEX;
+    return previous !== undefined ? previous.index + 1 : PIN_INDEX + 1;
+}
+/**
+ * The messages the summarizer is handed: `[spanStart, cutIndex)` without the
+ * summary that `previousSummary` already carries, so a merge pays once for that
+ * text (as the merge instruction) instead of twice.
+ */
+function spanOf(messages, spanStart, cutIndex, previous) {
+    const span = messages.slice(spanStart, cutIndex);
+    if (previous === undefined || previous.index < spanStart)
+        return span;
+    return span.filter((_message, offset) => spanStart + offset !== previous.index);
+}
+export function prepareCompaction(messages, keepTokens, options = {}) {
+    const previous = readPreviousSummary(messages);
     // Everything from here is fair game; the pin, and any existing summary, are not.
-    const spanStart = previousSummary === undefined ? PIN_INDEX + 1 : SUMMARY_INDEX + 1;
-    const cutIndex = findCutPoint(messages, spanStart, keepTokens);
+    const spanStart = spanStartFor(previous, options);
+    const cut = findCutPoint(messages, spanStart, keepTokens);
+    // Nothing to drop: the whole history fits the keep budget, so the cut is where
+    // the span starts and there is no plan (nax#1842). Checked on the RAW cut,
+    // before the clamp below — clamping first would turn "everything fits" into a
+    // paid compaction of the opening message (AC-5/AC-6).
+    if (cut <= spanStart)
+        return undefined;
+    // The kept window never starts at or before a summary that is being merged:
+    // its content already travels as `previousSummary`, and keeping it as well
+    // would leave two summaries in the transcript (the "merged, not stacked"
+    // rule). Reachable only when nothing is pinned — the manual path, whose span
+    // can now begin before that summary.
+    const cutIndex = previous !== undefined ? Math.max(cut, previous.index + 1) : cut;
+    const toSummarize = spanOf(messages, spanStart, cutIndex, previous);
     // An empty span is "nothing to do" whether or not a summary already exists
     // (nax#1842). A merge plan is still returnable — that needs `previousSummary`
-    // AND new content, which is exactly `cutIndex > spanStart`. With an empty span
-    // there is nothing to fold in: summarize() would be paid to re-summarize the
-    // previous summary alone and applyCompaction would rebuild an array no smaller
-    // than the one it replaced, once per round trip for the rest of the turn.
-    if (cutIndex <= spanStart)
+    // AND new content. With an empty span there is nothing to fold in:
+    // summarize() would be paid to re-summarize the previous summary alone and
+    // applyCompaction would rebuild an array no smaller than the one it replaced,
+    // once per round trip for the rest of the turn. Measured on the span itself
+    // because excluding a summary from it can empty a range that was not empty.
+    if (toSummarize.length === 0)
         return undefined;
     return {
         cutIndex,
-        toSummarize: messages.slice(spanStart, cutIndex),
-        ...(previousSummary !== undefined ? { previousSummary } : {}),
+        toSummarize,
+        ...(previous !== undefined ? { previousSummary: previous.text } : {}),
     };
 }
 export function applyCompaction(messages, plan, summary) {
-    return [
-        messages[PIN_INDEX],
-        { role: "user", content: COMPACTION_SUMMARY_PREFIX + summary + COMPACTION_SUMMARY_SUFFIX },
-        ...messages.slice(plan.cutIndex),
-    ];
+    // A summary AT the pin is one this session already compacted into — a manual
+    // compaction writes it there (applyManualCompaction), because that path has no
+    // task prompt worth pinning. Keeping it as the pin would stack two summaries,
+    // the older one out of reach of the merge rule above and so never removable;
+    // the new summary replaces it instead (US-002).
+    const pin = isSummaryMessage(messages[PIN_INDEX]) ? [] : [messages[PIN_INDEX]];
+    return [...pin, summaryMessage(summary), ...messages.slice(plan.cutIndex)];
 }

package/dist/native/session/manual-compaction.d.ts

@@ -0,0 +1,57 @@
+/**
+ * US-002: on-demand compaction of a native session's stored history.
+ *
+ * Automatic compaction fires near the context limit. This is the person saying
+ * the finished exploration is over — so the same pure core (`prepareCompaction`,
+ * `summarizeAndApply`) runs against the stored transcript, with three deliberate
+ * differences from the automatic path:
+ *
+ *  1. it ignores `compaction.enabled`, which governs when compaction happens BY
+ *     ITSELF; asking for it is not the same decision;
+ *  2. it dispatches no `before_compaction` loop event, so a plugin handler sees
+ *     only proactive and overflow compactions and cannot veto or rewrite a
+ *     summary the person asked for;
+ *  3. it does not pin the first message. `applyCompaction` keeps `messages[0]`
+ *     so a run's task prompt survives every compaction (design §Pinning, and its
+ *     cache-prefix rationale); a chat exploration has no such prompt worth
+ *     keeping, and the next request must BEGIN with the summary (AC-2), so the
+ *     summary takes that position instead — see `applyManualCompaction`. The
+ *     opening message is then part of the span (`pinFirstMessage: false`), so
+ *     what it said is summarized rather than discarded with the pin.
+ *
+ * A summarizer failure propagates and NOTHING is written: the loaded array is a
+ * fresh copy, so a rejection leaves the stored history exactly as it was.
+ */
+import type { Client } from "@nathapp/nax-ai";
+import type { CompactResult } from "#src/session/agent-session-types";
+import type { SessionHandle } from "#src/session/session-types";
+import type { TurnDeadline } from "#src/session/turn-deadline";
+import { type CompactionPlan, type TranscriptMessage } from "./compaction.ts";
+import type { NativeSessionState } from "./session.ts";
+export interface ManualCompactionRequest {
+    /** The adapter's per-session state: transcript, model identity and saved settings all live there. */
+    readonly state: NativeSessionState;
+    readonly handle: SessionHandle;
+    /** The session's client, supplied by the adapter that owns it. */
+    readonly client: Client;
+    /** The facade's budget for this call, consulted per summarizer call. */
+    readonly deadline: TurnDeadline;
+    /** Aborts on that deadline or on `close()`; a summarizer throw propagates instead. */
+    readonly signal: AbortSignal;
+}
+/**
+ * The manual compacted array: the summary first, then the kept window.
+ *
+ * Built from the plan rather than by post-processing `applyCompaction`'s array:
+ * slicing its first element would be wrong the moment `applyCompaction` itself
+ * drops a pin — which it does for a transcript this path already compacted.
+ */
+export declare function applyManualCompaction(messages: readonly TranscriptMessage[], plan: CompactionPlan, summary: string): TranscriptMessage[];
+/**
+ * Compact one session's stored history now.
+ *
+ * Nothing is written until a plan exists and the summary has come back, so
+ * "nothing to drop" costs no model call and no I/O, and a failed summary costs
+ * the history nothing beyond the failed call itself.
+ */
+export declare function compactHistory(request: ManualCompactionRequest): Promise<CompactResult>;

package/dist/native/session/manual-compaction.js

@@ -0,0 +1,72 @@
+import { NaxError } from "#src/infra/index";
+import { estimateContextTokens, keepBudget, prepareCompaction, summaryMessage, } from "./compaction.js";
+import { sessionTranscriptFor } from "./session.js";
+import { createSessionSummarizer, resolveSessionModel } from "./session-summarizer.js";
+import { historyFromTranscript, transcriptDocFor, transcriptIdentityFor } from "./transcript-identity.js";
+import { summarizeAndApply } from "./turn-compaction-step.js";
+/** No model call was made, so zero spend is the honest answer. */
+const ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+/**
+ * The manual compacted array: the summary first, then the kept window.
+ *
+ * Built from the plan rather than by post-processing `applyCompaction`'s array:
+ * slicing its first element would be wrong the moment `applyCompaction` itself
+ * drops a pin — which it does for a transcript this path already compacted.
+ */
+export function applyManualCompaction(messages, plan, summary) {
+    return [summaryMessage(summary), ...messages.slice(plan.cutIndex)];
+}
+/**
+ * Compact one session's stored history now.
+ *
+ * Nothing is written until a plan exists and the summary has come back, so
+ * "nothing to drop" costs no model call and no I/O, and a failed summary costs
+ * the history nothing beyond the failed call itself.
+ */
+export async function compactHistory(request) {
+    const { state, handle, client, deadline, signal } = request;
+    const transcript = sessionTranscriptFor(state, handle.id);
+    if (transcript === undefined) {
+        throw new NaxError(`no transcript store for session "${handle.id}"`, "NATIVE_TRANSCRIPT_DIR_MISSING", {
+            stage: "native-session",
+        });
+    }
+    const identity = transcriptIdentityFor(state, handle);
+    // Reloaded from the store, never held in memory: the adapter keeps no
+    // conversation, so what is on disk is the only history there is.
+    const messages = [...historyFromTranscript(await transcript.store.load(handle.id), identity, handle.id)];
+    const tokensBefore = estimateContextTokens(messages, undefined, undefined);
+    const resolution = await resolveSessionModel(client, state, handle);
+    // `pinFirstMessage: false`: this path writes the summary where the pin would
+    // be, so the opening message has to be inside the span. Leaving it out would
+    // drop the opening requirements, constraints and images without summarizing
+    // them — they would reach neither the model nor the compacted transcript.
+    const plan = prepareCompaction(messages, keepBudget(resolution.contextWindow, resolution.compaction), {
+        pinFirstMessage: false,
+    });
+    if (plan === undefined) {
+        return { compacted: false, tokensBefore, tokensAfter: tokensBefore, usage: ZERO_USAGE, costUsd: 0 };
+    }
+    const applied = await summarizeAndApply(messages, plan, {
+        summarize: createSessionSummarizer({ resolution, deadline, signal }),
+        contextWindow: resolution.contextWindow,
+        compaction: resolution.compaction,
+    });
+    const compacted = applyManualCompaction(messages, plan, applied.summary.text);
+    // Saved with the same owner and model identity a turn save uses, so the next
+    // turn — and a resume — reads this array as its own history, not a foreign
+    // one. A write failure propagates: continuing from a history that could not be
+    // stored is the silent degradation ADR-028 §4 removed.
+    await transcript.store.save(handle.id, transcriptDocFor(compacted, identity));
+    // The anchor describes the array the provider was last charged for. Against
+    // the compacted one it is meaningless, and leaving it would make the next turn
+    // estimate from the OLD size and compact again straight away (AC-16).
+    state.lastUsage.delete(handle.id);
+    return {
+        compacted: true,
+        tokensBefore,
+        tokensAfter: estimateContextTokens(compacted, undefined, undefined),
+        usage: applied.summary.usage,
+        costUsd: applied.summary.costUsd,
+    };
+}