@nathapp/nax-agent 0.1.0

package/dist/native/models.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Model reference, usage and cost for the native path.
+ *
+ * The provider travels inside the model string, not beside it: a multi-provider
+ * agent needs it there, and opencode's entries already encode it that way
+ * (ADR-027 section 1). Under acpx the same string stays opaque.
+ */
+import type { Pricing, ProviderOverride, ThinkingLevel } from "@nathapp/nax-ai";
+import type { ProviderCatalogOverride } from "#src/config/catalog-overrides";
+import { parseModelSpec } from "#src/cost/model-spec";
+/** The one agent name that routes to this transport. Defined once in the
+ *  `@/config/native-agent` leaf (config validates against it); re-exported
+ *  here, not in the barrel, so session-adapter.ts can import it without an
+ *  index -> session-adapter -> index cycle. */
+export { NATIVE_AGENT_NAME as NATIVE_AGENT } from "#src/config/native-agent/index";
+export { parseModelSpec };
+export interface NativeModelRef {
+    readonly provider: string;
+    readonly model: string;
+    /** Reasoning-effort suffix, when the config string carried one. Free-form —
+     *  validate with `toThinkingLevel` before sending it on the wire. */
+    readonly effort?: string;
+}
+/**
+ * Strip the nax-level `[effort]` suffix FIRST, then split on the FIRST slash: a
+ * provider id never contains one, a model id often does
+ * (`huggingface/MiniMaxAI/MiniMax-M2.7`). Order matters — the suffix is
+ * trailing, so splitting on the slash before stripping it would leave the
+ * suffix glued onto the model id (`"claude-opus-5[high]"`) and
+ * `client.model()` would throw its own unknown-model error instead of this
+ * function's clearer one.
+ *
+ * A suffix with no slash (`"claude-opus-5[high]"`) still fails malformed-model
+ * validation: `parseModelSpec` only removes the suffix, it does not supply a
+ * missing provider.
+ */
+export declare function parseNativeModel(raw: string): NativeModelRef;
+/**
+ * Every level nax-ai's `ThinkingLevel` union admits, as an exhaustive mapped
+ * type rather than a hand-rolled string array. `Record<ThinkingLevel, true>`
+ * only type-checks when every union member has an entry, so if nax-ai adds a
+ * level upstream, this fails to COMPILE — a real gate, not a comment that can
+ * silently drift out of sync with the union it mirrors.
+ */
+export declare const THINKING_LEVELS: Record<ThinkingLevel, true>;
+/**
+ * Translate nax's config-side "effort" suffix into nax-ai's request-side
+ * "thinking" field. Kept in this one place, named for the seam it crosses: nax
+ * calls the concept "effort", nax-ai calls the identical value "thinking".
+ *
+ * The suffix is a free-form string (see model-spec.ts), so a value outside
+ * nax-ai's ThinkingLevel union is possible from a typo'd profile. This
+ * mirrors applyReasoningEffort's stance in
+ * src/agents/acp/reasoning-effort.ts: "Best-effort: a failure leaves the
+ * session at the adapter default rather than failing the whole run. The
+ * warning is what keeps that downgrade visible." nax does not clamp against
+ * per-model capabilities here — that is nax-ai's clampThinkingLevel's job,
+ * run inside client.complete against the resolved model's own
+ * thinkingLevels.
+ */
+export declare function toThinkingLevel(effort: string | undefined): ThinkingLevel | undefined;
+/**
+ * Translate nax's config-side catalog overrides (agent.native.catalogOverrides,
+ * nax#1982) into nax-ai's declaration-data `ProviderOverride` records.
+ *
+ * The override is a COMPLETE entry, not a patch: nax-ai's `normaliseCatalog`
+ * applies it last through `setModel`, which replaces any same-id entry and
+ * lazily creates the provider bucket — that is what makes an id absent from
+ * the bundled pi-ai snapshot resolvable (verified against nax-ai 0.1.10).
+ * `provider` is stamped from the outer record because nax-ai's `ResolvedModel`
+ * carries it per model.
+ */
+export declare function toProviderOverrides(overrides: readonly ProviderCatalogOverride[]): ProviderOverride[];
+/**
+ * `estimateCostUsd` (and the tier-selection helper it relies on) was
+ * relocated to `src/agents/cost/` (US-001) so the ACP and native paths share
+ * one implementation. Native callers now import it from `@/agents/cost`.
+ */
+/**
+ * Turn nax-ai's catalog `Pricing` into the rate object `priceCall` prices from
+ * (nax#1843, nax#1847). Both call sites -- `nativeComplete()` (complete.ts)
+ * and `NativeSessionAdapter.sendTurn()` (session-adapter.ts) -- build the rate
+ * object this way, and both receive the override already converted by
+ * `toSessionModel`, so the fix cannot drift between them.
+ *
+ * An explicit `modelDef.pricing` override wins WHOLESALE: the caller converts
+ * the config override with `toPricing` (via `toSessionModel`), which fills
+ * the override's own missing cache rates from its input rate, but catalog
+ * values are never merged into an override -- that would silently rewrite
+ * rates the user configured on purpose.
+ *
+ * US-003 (#1817): reports which branch it took alongside the card, so the
+ * adapter can stamp `pricingSource` on the result without re-deriving the
+ * rate-card branch (US-003 retired the table-backed `MODEL_PRICING` lookup
+ * this resolver was the successor to). The card is the rate object; the
+ * source is the answer to "which one did we use".
+ */
+export declare function buildRateCard(catalog: Pricing, override: Pricing | undefined): {
+    rates: Pricing;
+    source: "config-override" | "catalog-rates";
+};
+/**
+ * Resolve the context window `runNativeTurn` compacts against: an explicit
+ * `ModelDef.contextWindow` override, falling back to nax-ai's
+ * `ResolvedModel.contextWindow` (nax#1848). Same override-then-fallback shape
+ * as `buildRateCard`, but with a direction guard that has no pricing
+ * equivalent: the window never reaches the provider, so it feeds only
+ * `shouldCompact` / `keepBudget` (`session/turn-loop.ts`). Lowering it is
+ * therefore safe -- compaction just fires earlier against an otherwise real
+ * request. Raising it above the real window would defeat compaction and
+ * reintroduce the overflow it exists to prevent, so that direction is
+ * rejected outright rather than clamped: this is a deliberate testing / cost
+ * lever, not a value set by accident, and a wrong value should be loud. An
+ * override equal to the real window is accepted -- it changes nothing.
+ */
+export declare function resolveContextWindow(override: number | undefined, realWindow: number): number;

package/dist/native/models.js

@@ -0,0 +1,183 @@
+/**
+ * Model reference, usage and cost for the native path.
+ *
+ * The provider travels inside the model string, not beside it: a multi-provider
+ * agent needs it there, and opencode's entries already encode it that way
+ * (ADR-027 section 1). Under acpx the same string stays opaque.
+ */
+import { parseModelSpec } from "#src/cost/model-spec";
+import { getSafeLogger, NaxError } from "#src/infra/index";
+/** The one agent name that routes to this transport. Defined once in the
+ *  `@/config/native-agent` leaf (config validates against it); re-exported
+ *  here, not in the barrel, so session-adapter.ts can import it without an
+ *  index -> session-adapter -> index cycle. */
+export { NATIVE_AGENT_NAME as NATIVE_AGENT } from "#src/config/native-agent/index";
+export { parseModelSpec };
+/**
+ * Strip the nax-level `[effort]` suffix FIRST, then split on the FIRST slash: a
+ * provider id never contains one, a model id often does
+ * (`huggingface/MiniMaxAI/MiniMax-M2.7`). Order matters — the suffix is
+ * trailing, so splitting on the slash before stripping it would leave the
+ * suffix glued onto the model id (`"claude-opus-5[high]"`) and
+ * `client.model()` would throw its own unknown-model error instead of this
+ * function's clearer one.
+ *
+ * A suffix with no slash (`"claude-opus-5[high]"`) still fails malformed-model
+ * validation: `parseModelSpec` only removes the suffix, it does not supply a
+ * missing provider.
+ */
+export function parseNativeModel(raw) {
+    const { model: withoutSuffix, effort } = parseModelSpec(raw);
+    const slash = withoutSuffix.indexOf("/");
+    const provider = slash === -1 ? "" : withoutSuffix.slice(0, slash);
+    const model = slash === -1 ? "" : withoutSuffix.slice(slash + 1);
+    if (provider === "" || model === "") {
+        throw new NaxError(
+        // Naming the sibling field is the point (nax#1851): a reader looking at
+        // `{ provider: "anthropic", model: "claude-sonnet-5" }` assumes the field
+        // right there is the one being used, and the old message said nothing to
+        // correct that. No suggested id is composed from it — on this path the
+        // value reaching us may be `resolveModel`'s inference rather than
+        // anything configured, and a guessed suggestion is worse than none.
+        `Native model "${raw}" must be written "provider/model" (e.g. "openai/gpt-5.4-mini"). There is no default provider. A "provider" field beside "model" in config is NOT used on the native path — the provider belongs in the model id itself.`, "NATIVE_MODEL_MALFORMED", { stage: "complete", model: raw });
+    }
+    return { provider, model, ...(effort !== undefined ? { effort } : {}) };
+}
+/**
+ * Every level nax-ai's `ThinkingLevel` union admits, as an exhaustive mapped
+ * type rather than a hand-rolled string array. `Record<ThinkingLevel, true>`
+ * only type-checks when every union member has an entry, so if nax-ai adds a
+ * level upstream, this fails to COMPILE — a real gate, not a comment that can
+ * silently drift out of sync with the union it mirrors.
+ */
+export const THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+function isThinkingLevel(value) {
+    return Object.hasOwn(THINKING_LEVELS, value);
+}
+/**
+ * Translate nax's config-side "effort" suffix into nax-ai's request-side
+ * "thinking" field. Kept in this one place, named for the seam it crosses: nax
+ * calls the concept "effort", nax-ai calls the identical value "thinking".
+ *
+ * The suffix is a free-form string (see model-spec.ts), so a value outside
+ * nax-ai's ThinkingLevel union is possible from a typo'd profile. This
+ * mirrors applyReasoningEffort's stance in
+ * src/agents/acp/reasoning-effort.ts: "Best-effort: a failure leaves the
+ * session at the adapter default rather than failing the whole run. The
+ * warning is what keeps that downgrade visible." nax does not clamp against
+ * per-model capabilities here — that is nax-ai's clampThinkingLevel's job,
+ * run inside client.complete against the resolved model's own
+ * thinkingLevels.
+ */
+export function toThinkingLevel(effort) {
+    if (effort === undefined)
+        return undefined;
+    if (isThinkingLevel(effort))
+        return effort;
+    getSafeLogger()?.warn("native-adapter", `Unknown effort "${effort}"; continuing at provider default`, { effort });
+    return undefined;
+}
+/**
+ * Translate nax's config-side catalog overrides (agent.native.catalogOverrides,
+ * nax#1982) into nax-ai's declaration-data `ProviderOverride` records.
+ *
+ * The override is a COMPLETE entry, not a patch: nax-ai's `normaliseCatalog`
+ * applies it last through `setModel`, which replaces any same-id entry and
+ * lazily creates the provider bucket — that is what makes an id absent from
+ * the bundled pi-ai snapshot resolvable (verified against nax-ai 0.1.10).
+ * `provider` is stamped from the outer record because nax-ai's `ResolvedModel`
+ * carries it per model.
+ */
+export function toProviderOverrides(overrides) {
+    return overrides.map((override) => ({
+        provider: override.provider,
+        // Omitted when undeclared, never passed as `undefined`: nax-ai reads
+        // `!== undefined` as a declaration and checks it against the protocol
+        // entries (nax#2019).
+        ...(override.baseUrl !== undefined ? { baseUrl: override.baseUrl } : {}),
+        // Copied, not aliased: nax-ai's client catalog assigns this reference
+        // straight onto ResolvedProvider.headers (providers/catalog.ts) without a
+        // copy of its own, so forwarding the live config object would let a later
+        // mutation reach an already-built client.
+        ...(override.headers !== undefined ? { headers: { ...override.headers } } : {}),
+        models: override.models.map((model) => ({
+            id: model.id,
+            provider: override.provider,
+            protocol: model.protocol,
+            pricing: model.pricing,
+            contextWindow: model.contextWindow,
+            // Omitted when the override declares none: nax-ai then falls back to the
+            // template sibling's ceiling, which is the only honest value available.
+            ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+            supportsTools: model.supportsTools,
+            thinkingLevels: model.thinkingLevels,
+            // nax#2191: forwarded verbatim. nax-ai's `assertOverrideModelRouting`
+            // rejects an empty `{}` (pi's check is truthiness, not emptiness — issue
+            // #43), so omission is the only safe absent shape. The protocol-side
+            // rejection on a non-`openai-completions` model is nax-ai's; nax's
+            // schema refuses an empty declaration at config load so the user gets
+            // the error there rather than on first dispatch.
+            ...(model.openRouterRouting !== undefined ? { openRouterRouting: model.openRouterRouting } : {}),
+        })),
+    }));
+}
+/**
+ * `estimateCostUsd` (and the tier-selection helper it relies on) was
+ * relocated to `src/agents/cost/` (US-001) so the ACP and native paths share
+ * one implementation. Native callers now import it from `@/agents/cost`.
+ */
+/**
+ * Turn nax-ai's catalog `Pricing` into the rate object `priceCall` prices from
+ * (nax#1843, nax#1847). Both call sites -- `nativeComplete()` (complete.ts)
+ * and `NativeSessionAdapter.sendTurn()` (session-adapter.ts) -- build the rate
+ * object this way, and both receive the override already converted by
+ * `toSessionModel`, so the fix cannot drift between them.
+ *
+ * An explicit `modelDef.pricing` override wins WHOLESALE: the caller converts
+ * the config override with `toPricing` (via `toSessionModel`), which fills
+ * the override's own missing cache rates from its input rate, but catalog
+ * values are never merged into an override -- that would silently rewrite
+ * rates the user configured on purpose.
+ *
+ * US-003 (#1817): reports which branch it took alongside the card, so the
+ * adapter can stamp `pricingSource` on the result without re-deriving the
+ * rate-card branch (US-003 retired the table-backed `MODEL_PRICING` lookup
+ * this resolver was the successor to). The card is the rate object; the
+ * source is the answer to "which one did we use".
+ */
+export function buildRateCard(catalog, override) {
+    if (override !== undefined)
+        return { rates: override, source: "config-override" };
+    return { rates: catalog, source: "catalog-rates" };
+}
+/**
+ * Resolve the context window `runNativeTurn` compacts against: an explicit
+ * `ModelDef.contextWindow` override, falling back to nax-ai's
+ * `ResolvedModel.contextWindow` (nax#1848). Same override-then-fallback shape
+ * as `buildRateCard`, but with a direction guard that has no pricing
+ * equivalent: the window never reaches the provider, so it feeds only
+ * `shouldCompact` / `keepBudget` (`session/turn-loop.ts`). Lowering it is
+ * therefore safe -- compaction just fires earlier against an otherwise real
+ * request. Raising it above the real window would defeat compaction and
+ * reintroduce the overflow it exists to prevent, so that direction is
+ * rejected outright rather than clamped: this is a deliberate testing / cost
+ * lever, not a value set by accident, and a wrong value should be loud. An
+ * override equal to the real window is accepted -- it changes nothing.
+ */
+export function resolveContextWindow(override, realWindow) {
+    if (override === undefined)
+        return realWindow;
+    if (override > realWindow) {
+        throw new NaxError(`configured contextWindow (${override}) exceeds the model's real context window (${realWindow}); ` +
+            "raising it above the real window would defeat compaction and risk a provider overflow", "CONTEXT_WINDOW_OVERRIDE_EXCEEDS_REAL_WINDOW", { configuredContextWindow: override, realContextWindow: realWindow });
+    }
+    return override;
+}

package/dist/native/session/ask-human.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The native human-Q&A channel.
+ *
+ * `AdapterInteraction` has always declared `{ kind: "question" }`, but the
+ * native loop routed only context-tools and coding-tools, so on native the
+ * operator could never be asked anything — while `agent.maxInteractionTurns`,
+ * the budget that names exactly this, was being spent as a round-trip cap.
+ *
+ * A declared tool rather than acpx's output parsing (acp/adapter.ts): the
+ * native protocol has a structured tool channel, and parsing prose for a
+ * question when a structured call is available is the weaker mechanism.
+ */
+import type { ToolDefinition } from "@nathapp/nax-ai";
+export declare const ASK_HUMAN_TOOL_NAME = "ask_human";
+export declare const askHumanToolDefinition: ToolDefinition;

package/dist/native/session/ask-human.js

@@ -0,0 +1,22 @@
+/**
+ * The native human-Q&A channel.
+ *
+ * `AdapterInteraction` has always declared `{ kind: "question" }`, but the
+ * native loop routed only context-tools and coding-tools, so on native the
+ * operator could never be asked anything — while `agent.maxInteractionTurns`,
+ * the budget that names exactly this, was being spent as a round-trip cap.
+ *
+ * A declared tool rather than acpx's output parsing (acp/adapter.ts): the
+ * native protocol has a structured tool channel, and parsing prose for a
+ * question when a structured call is available is the weaker mechanism.
+ */
+export const ASK_HUMAN_TOOL_NAME = "ask_human";
+export const askHumanToolDefinition = {
+    name: ASK_HUMAN_TOOL_NAME,
+    description: "Ask the human operator a question and wait for their reply. Use only when genuinely blocked: the budget is small and each call costs a round trip.",
+    inputSchema: {
+        type: "object",
+        properties: { text: { type: "string", description: "The question to put to the operator." } },
+        required: ["text"],
+    },
+};

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

@@ -0,0 +1,94 @@
+/**
+ * Context compaction for the native turn loop.
+ *
+ * Pure functions only: no file I/O, no model calls, no clock. turn-loop.ts owns
+ * the orchestration and the one model call. Keeping this half pure is what makes
+ * the cut-point rules testable directly rather than only end to end.
+ *
+ * See docs/superpowers/specs/2026-09-04-native-context-compaction-design.md.
+ */
+import type { ConversationMessage } from "@nathapp/nax-ai";
+import type { AdapterInteractionResponse } from "#src/session/interaction-handler";
+/**
+ * The transcript message nax stores: nax-ai's ConversationMessage widened with
+ * the coding-tool denial marker (ADR-029 s5). The marker is structural data the
+ * model must be able to act on — dropping it because the wire type does not
+ * know it yet is exactly the defect this widening exists to prevent.
+ *
+ * Lives here rather than in turn-loop.ts because both modules need it and this
+ * is the one without a dependency on the other.
+ */
+export type TranscriptMessage = ConversationMessage | {
+    readonly role: "tool-result";
+    readonly toolCallId: string;
+    readonly content: string;
+    readonly isError?: boolean;
+    readonly denied?: AdapterInteractionResponse["denied"];
+};
+/** Compaction settings after config resolution. Reaches the adapter as a primitive. */
+export interface ResolvedCompaction {
+    readonly enabled: boolean;
+    readonly compactAtPercent: number;
+    readonly keepRecentPercent: number;
+}
+/**
+ * Characters over four. Deliberately crude and deliberately high: over-estimating
+ * compacts slightly early, under-estimating overflows.
+ */
+export declare function estimateTokens(message: TranscriptMessage): number;
+/**
+ * Anchor on truth, guess only the tail.
+ *
+ * `lastUsage.promptTokens` is every token the provider counted for the prompt
+ * up to and including `anchorIndex` — uncached input plus cache reads plus
+ * cache writes (see `inputClassTokens`). It is deliberately not just the
+ * uncached input: under prompt caching the cached prefix is reported
+ * separately, and anchoring on that one field reads a 71k-token context as
+ * ~16 and silently disables compaction (nax#1852).
+ *
+ * With no anchor every message is estimated, which is the case the reactive
+ * backstop exists to cover.
+ */
+export declare function estimateContextTokens(messages: readonly TranscriptMessage[], lastUsage?: {
+    readonly promptTokens: number;
+}, anchorIndex?: number): number;
+/**
+ * The percentage governs; the floor only takes over when a percentage of the
+ * window would leave too little room for a reply. Both constants are a safety
+ * rail against a window smaller than the defaults assume, not tuning knobs —
+ * which is why they are not config.
+ */
+export declare function compactionThreshold(window: number, cfg: ResolvedCompaction): number;
+export declare function shouldCompact(tokens: number, window: number, cfg: ResolvedCompaction): boolean;
+/**
+ * How much recent conversation survives verbatim, in tokens.
+ * `aggressive` halves it — the reactive backstop's only difference.
+ */
+export declare function keepBudget(window: number, cfg: ResolvedCompaction, aggressive?: boolean): number;
+/**
+ * Marks the summary message. The summary carries no marker FIELD: transcript
+ * messages reach nax-ai structurally, so an extra property would travel to the
+ * wire (the existing `denied` marker already does). Position plus this prefix
+ * is how a later compaction finds the summary it must replace.
+ */
+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";
+/**
+ * Walk backwards accumulating estimated size; once `keepTokens` is reached, take
+ * the nearest valid cut at or after that point.
+ *
+ * Two passes on purpose. A single backwards pass that remembers the last valid
+ * index it saw returns `messages.length` whenever trailing tool-results consume
+ * the whole budget before any valid cut appears — an out-of-range index the
+ * caller then dereferences. Collecting the valid cuts first makes "the nearest
+ * cut at or after i" answerable without that hole, and `cuts[0]` is the honest
+ * default: keep everything, which `prepareCompaction` reads as "no plan".
+ */
+export declare function findCutPoint(messages: readonly TranscriptMessage[], startIndex: number, keepTokens: number): number;
+export interface CompactionPlan {
+    readonly cutIndex: number;
+    readonly toSummarize: readonly TranscriptMessage[];
+    readonly previousSummary?: string;
+}
+export declare function prepareCompaction(messages: readonly TranscriptMessage[], keepTokens: number): CompactionPlan | undefined;
+export declare function applyCompaction(messages: readonly TranscriptMessage[], plan: CompactionPlan, summary: string): TranscriptMessage[];

package/dist/native/session/compaction.js

@@ -0,0 +1,170 @@
+/**
+ * Context compaction for the native turn loop.
+ *
+ * Pure functions only: no file I/O, no model calls, no clock. turn-loop.ts owns
+ * the orchestration and the one model call. Keeping this half pure is what makes
+ * the cut-point rules testable directly rather than only end to end.
+ *
+ * See docs/superpowers/specs/2026-09-04-native-context-compaction-design.md.
+ */
+/** A reply needs room whatever the window is. */
+const MIN_HEADROOM_TOKENS = 4096;
+/** ...but never take a quarter of a small window for headroom. */
+const MAX_HEADROOM_FRACTION = 0.25;
+const CHARS_PER_TOKEN = 4;
+/**
+ * Characters over four. Deliberately crude and deliberately high: over-estimating
+ * compacts slightly early, under-estimating overflows.
+ */
+export function estimateTokens(message) {
+    let chars = 0;
+    switch (message.role) {
+        case "user":
+            chars = message.content.length;
+            break;
+        case "assistant":
+            chars = message.content.length;
+            for (const block of message.thinking ?? [])
+                chars += block.text.length;
+            for (const call of message.toolCalls ?? [])
+                chars += call.name.length + JSON.stringify(call.input).length;
+            break;
+        case "tool-result":
+            chars = message.content.length;
+            break;
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+/**
+ * Anchor on truth, guess only the tail.
+ *
+ * `lastUsage.promptTokens` is every token the provider counted for the prompt
+ * up to and including `anchorIndex` — uncached input plus cache reads plus
+ * cache writes (see `inputClassTokens`). It is deliberately not just the
+ * uncached input: under prompt caching the cached prefix is reported
+ * separately, and anchoring on that one field reads a 71k-token context as
+ * ~16 and silently disables compaction (nax#1852).
+ *
+ * With no anchor every message is estimated, which is the case the reactive
+ * backstop exists to cover.
+ */
+export function estimateContextTokens(messages, lastUsage, anchorIndex) {
+    if (lastUsage === undefined || anchorIndex === undefined) {
+        return messages.reduce((sum, m) => sum + estimateTokens(m), 0);
+    }
+    let trailing = 0;
+    for (let i = anchorIndex + 1; i < messages.length; i++)
+        trailing += estimateTokens(messages[i]);
+    return lastUsage.promptTokens + trailing;
+}
+/**
+ * The percentage governs; the floor only takes over when a percentage of the
+ * window would leave too little room for a reply. Both constants are a safety
+ * rail against a window smaller than the defaults assume, not tuning knobs —
+ * which is why they are not config.
+ */
+export function compactionThreshold(window, cfg) {
+    const headroom = Math.min(MIN_HEADROOM_TOKENS, Math.floor(window * MAX_HEADROOM_FRACTION));
+    return Math.min(Math.floor(window * (cfg.compactAtPercent / 100)), window - headroom);
+}
+export function shouldCompact(tokens, window, cfg) {
+    return cfg.enabled && tokens > compactionThreshold(window, cfg);
+}
+/**
+ * How much recent conversation survives verbatim, in tokens.
+ * `aggressive` halves it — the reactive backstop's only difference.
+ */
+export function keepBudget(window, cfg, aggressive = false) {
+    const budget = Math.floor(window * (cfg.keepRecentPercent / 100));
+    return aggressive ? Math.floor(budget / 2) : budget;
+}
+/**
+ * Marks the summary message. The summary carries no marker FIELD: transcript
+ * messages reach nax-ai structurally, so an extra property would travel to the
+ * wire (the existing `denied` marker already does). Position plus this prefix
+ * is how a later compaction finds the summary it must replace.
+ */
+export const COMPACTION_SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
+export const COMPACTION_SUMMARY_SUFFIX = "\n</summary>\n";
+/** Index of the pinned first message; never summarized, never dropped. */
+const PIN_INDEX = 0;
+/** Where the summary sits once written. */
+const SUMMARY_INDEX = 1;
+/**
+ * Valid cut points are user or assistant messages, NEVER a tool-result.
+ *
+ * That one rule carries both hard constraints: a tool-result can never become
+ * the first kept message (orphaning it from its tool_use, which the provider
+ * rejects), and cuts land between messages rather than inside an assistant
+ * message, so a kept thinking block keeps its exact text and signature.
+ */
+function isValidCut(message) {
+    return message.role === "user" || message.role === "assistant";
+}
+/**
+ * Walk backwards accumulating estimated size; once `keepTokens` is reached, take
+ * the nearest valid cut at or after that point.
+ *
+ * Two passes on purpose. A single backwards pass that remembers the last valid
+ * index it saw returns `messages.length` whenever trailing tool-results consume
+ * the whole budget before any valid cut appears — an out-of-range index the
+ * caller then dereferences. Collecting the valid cuts first makes "the nearest
+ * cut at or after i" answerable without that hole, and `cuts[0]` is the honest
+ * default: keep everything, which `prepareCompaction` reads as "no plan".
+ */
+export function findCutPoint(messages, startIndex, keepTokens) {
+    const cuts = [];
+    for (let i = startIndex; i < messages.length; i++) {
+        if (isValidCut(messages[i]))
+            cuts.push(i);
+    }
+    if (cuts.length === 0)
+        return messages.length;
+    let candidate = cuts[0];
+    let accumulated = 0;
+    for (let i = messages.length - 1; i >= startIndex; i--) {
+        accumulated += estimateTokens(messages[i]);
+        if (accumulated >= keepTokens) {
+            const at = cuts.find((c) => c >= i);
+            if (at !== undefined)
+                candidate = at;
+            break;
+        }
+    }
+    return candidate;
+}
+/** Reads a previous summary out of the message at SUMMARY_INDEX, if one is there. */
+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);
+}
+export function prepareCompaction(messages, keepTokens) {
+    const previousSummary = 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);
+    // 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)
+        return undefined;
+    return {
+        cutIndex,
+        toSummarize: messages.slice(spanStart, cutIndex),
+        ...(previousSummary !== undefined ? { previousSummary } : {}),
+    };
+}
+export function applyCompaction(messages, plan, summary) {
+    return [
+        messages[PIN_INDEX],
+        { role: "user", content: COMPACTION_SUMMARY_PREFIX + summary + COMPACTION_SUMMARY_SUFFIX },
+        ...messages.slice(plan.cutIndex),
+    ];
+}