@gaunt-sloth/core 2.0.0-beta.4 → 2.0.0-beta.6

package/dist/core/compactionThreshold.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @packageDocumentation
+ * EXT-161 — **the preventive compaction threshold: one number, one place it is decided.**
+ *
+ * `contextWindow.ts` answers "how big is the window". This module answers the question that
+ * actually gates a compaction: **at what prompt size do we fold the conversation, and who said
+ * so.** Three things can say so, in this order:
+ *
+ * 1. **the running session** — `/autocompact 300K`, which wins for the rest of the session;
+ * 2. **the user's config** — the `autocompact` key;
+ * 3. **the default** — derived from the resolved window by the guard, which is the only place that
+ *    knows how many tokens are being held back for the answer.
+ *
+ * **Compaction is ON BY DEFAULT.** That is a ruling, and it is a deliberate exception to the rule
+ * that a default-on middleware must not touch `state.messages` — compaction changes what the model
+ * sees by construction, which is the whole feature. The exception is paid for the way the rule
+ * demands: the shape of the history a compaction leaves behind is pinned per provider by
+ * `compaction.ts`'s invariants (a)–(d), a compaction announces itself in the transcript, the
+ * resolved number and its provenance are readable with `/status`, and the off switch is one key —
+ * `autocompact: false`.
+ *
+ * **Why the provenance is carried rather than recomputed.** A threshold that is wrong is diagnosed
+ * by knowing where the number came from; a `/status` that reports a models.dev-derived number after
+ * a human typed `/autocompact 50000` would send the next diagnosis to the wrong place entirely. So
+ * a session override re-labels the provenance, and {@link AutocompactController} is the single
+ * object both the guard and `/status` read, over one memoised window resolution.
+ */
+import { type TokenBudget } from '#src/config/tokenBudget.js';
+import type { ContextWindowOrigin, ResolvedContextWindow } from '#src/core/contextWindow.js';
+/**
+ * The share of a model's context window that `gth init` seeds as an explicit threshold.
+ *
+ * Init writes an **absolute number** derived from this rather than the percentage itself, because
+ * the point of seeding is that the user opens their config and sees the number that will actually
+ * be enforced. A percentage would leave them one lookup away from it.
+ *
+ * 0.8 leaves a fifth of the window for the answer and the tool round that follows it — comfortably
+ * more than the flat answer reserve on any real cloud window, which is what makes the seeded number
+ * the binding one rather than a decoration.
+ */
+export declare const DEFAULT_AUTOCOMPACT_SEED_FRACTION = 0.8;
+/**
+ * The `autocompact` config value, in every form the key accepts.
+ *
+ * `false` disables it; `true` (and an absent key) is on with the derived default; a bare count or
+ * suffixed string is on with that threshold; the object form spells both out. The shorthand union
+ * mirrors `toolLoopGuard`, which is the shape a reader of this config already knows.
+ */
+export type AutocompactConfig = boolean | number | string | {
+    enabled?: boolean;
+    threshold?: number | string;
+};
+/** The `autocompact` key as the read site sees it, after defaulting and parsing. */
+export interface ResolvedAutocompactConfig {
+    /** Whether preventive compaction may fire at all. On by default — ruled. */
+    enabled: boolean;
+    /** The configured budget, or `null` when the user named none and the default applies. */
+    budget: TokenBudget | null;
+}
+/**
+ * Read the `autocompact` config key.
+ *
+ * Defaulting happens **here, at the read site**, not in `DEFAULT_CONFIG`, so an absent key stays
+ * absent in the effective-config snapshot and the snapshot does not churn — the same placement
+ * `injectModelContext` and `toolLoopGuard` use.
+ *
+ * A malformed threshold raises the `TokenBudgetError` from the shared parser, which config
+ * validation turns into a field-scoped issue naming the offending text. It must never resolve to a
+ * number: `NaN`, `0` and 4097 are all thresholds the user cannot see and did not choose.
+ */
+export declare function resolveAutocompactConfig(raw: unknown): ResolvedAutocompactConfig;
+/** Where the threshold number in force came from — what `/status` names. */
+export type AutocompactThresholdOrigin = 
+/** A `/autocompact` typed in this session; outranks the config for the rest of it. */
+'session'
+/** The `autocompact` key in the user's config. */
+ | 'config'
+/** Derived from the resolved window, holding back room for the answer. */
+ | 'default'
+/** Nothing will fire: switched off, or no window and no absolute threshold to fall back on. */
+ | 'none';
+/** The whole picture, as `/status` prints it and the guard enforces it. */
+export interface AutocompactStatus {
+    /** Whether preventive compaction may fire at all (the config off switch). */
+    enabled: boolean;
+    /**
+     * The prompt size, in tokens, at which the conversation is folded — or `null` when nothing will
+     * fire preventively, which is what an unknown window with no absolute threshold must produce.
+     */
+    thresholdTokens: number | null;
+    /** Where that number came from. */
+    thresholdOrigin: AutocompactThresholdOrigin;
+    /** The resolved context window, or `null` when no source knew it. */
+    window: number | null;
+    /** Which source the window came from. */
+    windowOrigin: ContextWindowOrigin;
+    /** The budget exactly as written, when one was written — so `/status` can echo `80%` as `80%`. */
+    budget: TokenBudget | null;
+}
+/** What {@link AutocompactController} needs to build a status. */
+export interface AutocompactControllerOptions {
+    /** The `autocompact` key, already read through {@link resolveAutocompactConfig}. */
+    config: ResolvedAutocompactConfig;
+    /** The one memoised window resolution this session uses — shared with the guard. */
+    window: Pick<ResolvedContextWindow, 'read'>;
+    /**
+     * The threshold to use when the user named none, given a known window: the guard's
+     * `window − reserve`. Supplied as a callback because only the guard knows the reserve, and
+     * duplicating that arithmetic here is how the two would come to disagree about what "full" means.
+     */
+    defaultThreshold: (_window: number) => number;
+}
+/**
+ * **The single object the guard and `/status` both read.**
+ *
+ * Holds the session override — the write half of `/autocompact` — and resolves it against the
+ * config and the window on demand. It is mutable by design and the guard reads it through a
+ * closure rather than capturing a value, because `createContextGuardMiddleware` runs its factory
+ * once per session and its hook holds no state: a captured threshold could never be changed by a
+ * command typed later, which is precisely what `/autocompact` has to do.
+ */
+export declare class AutocompactController {
+    private readonly options;
+    private sessionBudget;
+    constructor(options: AutocompactControllerOptions);
+    /**
+     * Set the threshold for the rest of this session, overriding the config.
+     *
+     * Deliberately takes an already-parsed {@link TokenBudget} rather than raw text: parsing is the
+     * shared parser's job, and a second entry point that took a string would be a second place the
+     * grammar could drift.
+     *
+     * **Refused while the config has compaction off.** `autocompact: false` means nothing fires,
+     * whatever number is named, so recording the budget would only make the next {@link status}
+     * describe a threshold that can never trigger. Nothing is recorded and the status is unchanged;
+     * the surface reads `enabled: false` off the status that comes back and says so. Turning it back
+     * on is a config edit — removing the key, or setting a threshold there — not a session command.
+     */
+    setSessionBudget(budget: TokenBudget): void;
+    /** The session override in force, or `null`. Read by `/autocompact` with no argument. */
+    get sessionOverride(): TokenBudget | null;
+    /** Whether the config off switch leaves anything to do at all. */
+    get enabled(): boolean;
+    /** The full picture — the one call `/status` makes. */
+    status(): Promise<AutocompactStatus>;
+    /** The number the guard compares against, or `null` for "never fire". */
+    threshold(): Promise<number | null>;
+}
+/**
+ * The absolute threshold `gth init` writes for a model whose window it resolved — a plain number,
+ * because the point of seeding is that the user can read the enforced value straight out of their
+ * config.
+ *
+ * Returns `null` when the window is unknown, and the caller then writes **no key at all**: seeding
+ * a guess would put a number in the user's config that looks chosen and was not, which is worse
+ * than the absent key that leaves the runtime default in charge.
+ */
+export declare function seedAutocompactThreshold(window: number | null): number | null;

package/dist/core/compactionThreshold.js

@@ -0,0 +1,183 @@
+/**
+ * @packageDocumentation
+ * EXT-161 — **the preventive compaction threshold: one number, one place it is decided.**
+ *
+ * `contextWindow.ts` answers "how big is the window". This module answers the question that
+ * actually gates a compaction: **at what prompt size do we fold the conversation, and who said
+ * so.** Three things can say so, in this order:
+ *
+ * 1. **the running session** — `/autocompact 300K`, which wins for the rest of the session;
+ * 2. **the user's config** — the `autocompact` key;
+ * 3. **the default** — derived from the resolved window by the guard, which is the only place that
+ *    knows how many tokens are being held back for the answer.
+ *
+ * **Compaction is ON BY DEFAULT.** That is a ruling, and it is a deliberate exception to the rule
+ * that a default-on middleware must not touch `state.messages` — compaction changes what the model
+ * sees by construction, which is the whole feature. The exception is paid for the way the rule
+ * demands: the shape of the history a compaction leaves behind is pinned per provider by
+ * `compaction.ts`'s invariants (a)–(d), a compaction announces itself in the transcript, the
+ * resolved number and its provenance are readable with `/status`, and the off switch is one key —
+ * `autocompact: false`.
+ *
+ * **Why the provenance is carried rather than recomputed.** A threshold that is wrong is diagnosed
+ * by knowing where the number came from; a `/status` that reports a models.dev-derived number after
+ * a human typed `/autocompact 50000` would send the next diagnosis to the wrong place entirely. So
+ * a session override re-labels the provenance, and {@link AutocompactController} is the single
+ * object both the guard and `/status` read, over one memoised window resolution.
+ */
+import { parseTokenBudget, resolveTokenBudget } from '#src/config/tokenBudget.js';
+/**
+ * The share of a model's context window that `gth init` seeds as an explicit threshold.
+ *
+ * Init writes an **absolute number** derived from this rather than the percentage itself, because
+ * the point of seeding is that the user opens their config and sees the number that will actually
+ * be enforced. A percentage would leave them one lookup away from it.
+ *
+ * 0.8 leaves a fifth of the window for the answer and the tool round that follows it — comfortably
+ * more than the flat answer reserve on any real cloud window, which is what makes the seeded number
+ * the binding one rather than a decoration.
+ */
+export const DEFAULT_AUTOCOMPACT_SEED_FRACTION = 0.8;
+/**
+ * Read the `autocompact` config key.
+ *
+ * Defaulting happens **here, at the read site**, not in `DEFAULT_CONFIG`, so an absent key stays
+ * absent in the effective-config snapshot and the snapshot does not churn — the same placement
+ * `injectModelContext` and `toolLoopGuard` use.
+ *
+ * A malformed threshold raises the `TokenBudgetError` from the shared parser, which config
+ * validation turns into a field-scoped issue naming the offending text. It must never resolve to a
+ * number: `NaN`, `0` and 4097 are all thresholds the user cannot see and did not choose.
+ */
+export function resolveAutocompactConfig(raw) {
+    if (raw === undefined || raw === null)
+        return { enabled: true, budget: null };
+    if (typeof raw === 'boolean')
+        return { enabled: raw, budget: null };
+    if (typeof raw === 'number' || typeof raw === 'string') {
+        return { enabled: true, budget: parseTokenBudget(raw) };
+    }
+    if (typeof raw === 'object') {
+        const value = raw;
+        const enabled = value.enabled !== false;
+        const budget = value.threshold === undefined || value.threshold === null
+            ? null
+            : parseTokenBudget(value.threshold);
+        return { enabled, budget };
+    }
+    return { enabled: true, budget: null };
+}
+/**
+ * **The single object the guard and `/status` both read.**
+ *
+ * Holds the session override — the write half of `/autocompact` — and resolves it against the
+ * config and the window on demand. It is mutable by design and the guard reads it through a
+ * closure rather than capturing a value, because `createContextGuardMiddleware` runs its factory
+ * once per session and its hook holds no state: a captured threshold could never be changed by a
+ * command typed later, which is precisely what `/autocompact` has to do.
+ */
+export class AutocompactController {
+    options;
+    sessionBudget = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Set the threshold for the rest of this session, overriding the config.
+     *
+     * Deliberately takes an already-parsed {@link TokenBudget} rather than raw text: parsing is the
+     * shared parser's job, and a second entry point that took a string would be a second place the
+     * grammar could drift.
+     *
+     * **Refused while the config has compaction off.** `autocompact: false` means nothing fires,
+     * whatever number is named, so recording the budget would only make the next {@link status}
+     * describe a threshold that can never trigger. Nothing is recorded and the status is unchanged;
+     * the surface reads `enabled: false` off the status that comes back and says so. Turning it back
+     * on is a config edit — removing the key, or setting a threshold there — not a session command.
+     */
+    setSessionBudget(budget) {
+        if (!this.options.config.enabled)
+            return;
+        this.sessionBudget = budget;
+    }
+    /** The session override in force, or `null`. Read by `/autocompact` with no argument. */
+    get sessionOverride() {
+        return this.sessionBudget;
+    }
+    /** Whether the config off switch leaves anything to do at all. */
+    get enabled() {
+        return this.options.config.enabled;
+    }
+    /** The full picture — the one call `/status` makes. */
+    async status() {
+        const reading = await this.options.window.read();
+        const budget = this.sessionBudget ?? this.options.config.budget;
+        const budgetOrigin = this.sessionBudget
+            ? 'session'
+            : this.options.config.budget
+                ? 'config'
+                : 'default';
+        if (!this.options.config.enabled) {
+            return {
+                enabled: false,
+                thresholdTokens: null,
+                thresholdOrigin: 'none',
+                window: reading.tokens,
+                windowOrigin: reading.origin,
+                budget,
+            };
+        }
+        // A named budget resolves against the window — which an absolute count does not need, so an
+        // explicit `300K` still fires on a model nothing knows the window of. A PERCENTAGE without a
+        // window cannot resolve, and falls through to the same "nothing fires" answer as no threshold
+        // at all rather than to a guess.
+        const named = budget ? resolveTokenBudget(budget, reading.tokens) : null;
+        if (named !== null) {
+            return {
+                enabled: true,
+                thresholdTokens: named,
+                thresholdOrigin: budgetOrigin === 'default' ? 'config' : budgetOrigin,
+                window: reading.tokens,
+                windowOrigin: reading.origin,
+                budget,
+            };
+        }
+        if (reading.tokens === null) {
+            return {
+                enabled: true,
+                thresholdTokens: null,
+                thresholdOrigin: 'none',
+                window: null,
+                windowOrigin: reading.origin,
+                budget,
+            };
+        }
+        return {
+            enabled: true,
+            thresholdTokens: this.options.defaultThreshold(reading.tokens),
+            thresholdOrigin: 'default',
+            window: reading.tokens,
+            windowOrigin: reading.origin,
+            budget,
+        };
+    }
+    /** The number the guard compares against, or `null` for "never fire". */
+    async threshold() {
+        return (await this.status()).thresholdTokens;
+    }
+}
+/**
+ * The absolute threshold `gth init` writes for a model whose window it resolved — a plain number,
+ * because the point of seeding is that the user can read the enforced value straight out of their
+ * config.
+ *
+ * Returns `null` when the window is unknown, and the caller then writes **no key at all**: seeding
+ * a guess would put a number in the user's config that looks chosen and was not, which is worse
+ * than the absent key that leaves the runtime default in charge.
+ */
+export function seedAutocompactThreshold(window) {
+    if (window === null || !Number.isFinite(window) || window <= 0)
+        return null;
+    return Math.max(1, Math.floor(window * DEFAULT_AUTOCOMPACT_SEED_FRACTION));
+}
+//# sourceMappingURL=compactionThreshold.js.map

package/dist/core/compactionThreshold.js.map

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

package/dist/core/contextWindow.d.ts

@@ -0,0 +1,146 @@
+import { type CatalogOptions, type ProviderCatalog } from '#src/providers/modelCatalog.js';
+import type { ProviderId } from '#src/providers/modelDiscovery.js';
+/**
+ * GS2-59 — default context window (`num_ctx`) for Ollama models. Ollama's OWN default is 4096, but
+ * gaunt-sloth's agentic prompt (system + full lean toolset + a tool result) already lands ~4000
+ * tokens; at 4096 a thinking model (e.g. gemma4:31b) spends its entire remaining budget on the
+ * reasoning field and emits EMPTY `content` on the turn after a tool executes — the GS2-59
+ * blank-answer regression. The OpenAI-compat `/v1` shim IGNORES `num_ctx`; the native `/api/chat`
+ * path honors it.
+ *
+ * 16384 is chosen as the largest window that is BOTH safely above the ~4000-token starvation point
+ * (4× headroom for reasoning + a few tool results) AND fits constrained consumer VRAM: Ollama
+ * preallocates the KV cache at `num_ctx`, so on a box where a large model already spills partly to
+ * CPU (e.g. a 19GB model on ~18GB of GPU), a 32768 cache tips the GPU allocation into an
+ * out-of-memory error. 16384 was verified live to run the agentic tool→synthesis turn on such a
+ * box; 32768 OOM'd it. Overridable per config via `llm.numCtx` — raise it if you have the VRAM and
+ * run long sessions, lower it on very tight hardware. NOTE: a per-request `num_ctx` overrides the
+ * daemon's `OLLAMA_CONTEXT_LENGTH`, so a user who tuned their server window higher should set
+ * `llm.numCtx` to match rather than rely on the server default.
+ *
+ * It lives here rather than in the provider module because two things now need it — the client the
+ * provider builds and the guard that has to know what that client will send — and a second copy is
+ * how the guard would come to reason about a window the request does not use.
+ */
+export declare const DEFAULT_OLLAMA_NUM_CTX = 16384;
+/**
+ * The model's context window in tokens, or `null` when it is not known.
+ *
+ * Asynchronous because a source may have to ask the provider. Called on every model call, so an
+ * implementation that does I/O is expected to memoise; {@link resolveContextWindowSource} does.
+ */
+export type ContextWindowSource = () => Promise<number | null>;
+/** A source that never knows — the honest answer for every provider no source is wired for. */
+export declare const UNKNOWN_CONTEXT_WINDOW: ContextWindowSource;
+/**
+ * The fields the window resolver reads off a chat model, without depending on its class.
+ *
+ * Structural rather than a `ChatOllama` import on purpose: the provider module loads
+ * `@langchain/ollama` dynamically so a session that never uses ollama never pays for it, and typing
+ * against the class here would undo that.
+ */
+export interface OllamaLikeModel {
+    _llmType?: () => string;
+    numCtx?: number;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * **The ollama window: what we send, capped by what the model can hold.**
+ *
+ * The effective window is `numCtx` — the number gaunt-sloth puts on every native `/api/chat`
+ * request, which overrides the daemon's own `OLLAMA_CONTEXT_LENGTH` — and never the daemon default,
+ * because the request is what decides. It is then capped by the model's own `context_length` from
+ * `/api/show`: asking for more than the model has does not buy more room, so guarding against the
+ * larger number would let exactly the truncation this guard exists to prevent happen anyway.
+ *
+ * **Fail-soft in one direction only.** No daemon, a slow daemon, an unreadable answer — the
+ * configured number stands, because that is still the number the request will carry. Nothing here
+ * throws, and nothing here degrades a known window to unknown.
+ */
+export declare function createOllamaContextWindowSource(llm: OllamaLikeModel): ContextWindowSource;
+/** Where a resolved context window came from — carried so `/status` can say, and a wrong one is
+ * diagnosable instead of mysterious. */
+export type ContextWindowOrigin = 'ollama' | 'models.dev' | 'profile' | 'unknown';
+/** A resolved window and its provenance. `tokens: null` means "not known", and never "zero". */
+export interface ContextWindowReading {
+    tokens: number | null;
+    origin: ContextWindowOrigin;
+}
+/** How each origin is described to a user, in a sentence that says where to go to change it. */
+export declare const CONTEXT_WINDOW_ORIGIN_LABELS: Readonly<Record<ContextWindowOrigin, string>>;
+/**
+ * The model's window as the LangChain provider package declares it: `llm.profile.maxInputTokens`.
+ *
+ * A getter on `BaseLanguageModel` that the base class answers with `{}` and each provider package
+ * overrides, so an id its table has never heard of yields `undefined` rather than an error —
+ * measured: `gpt-4o-mini` gives 128000 and `mistralai/mistral-7b-instruct` gives nothing. Wrapped
+ * in a `try` because it is a getter on someone else's object and a throw here would take down a
+ * resolution that has a perfectly good answer to fall back to.
+ */
+export declare function readProfileContextWindow(llm: unknown): number | null;
+/** What {@link resolveContextWindow} needs beyond the model itself — all of it injectable. */
+export interface ContextWindowResolutionOptions {
+    /**
+     * The gth provider namespace (`anthropic`, `google-genai`, …) — `config.modelProviderType`, NOT
+     * the model class's `_llmType()`. The two disagree exactly where it matters: `huggingface`
+     * reports `openai`, and both Gemini providers report `google`, so keying the catalog on the
+     * class's own label would read the wrong provider's slice or none at all.
+     */
+    providerId?: string;
+    /** The model id as models.dev keys it — `llm.model`, e.g. `claude-sonnet-4-5`. */
+    modelId?: string;
+    /**
+     * Options threaded to {@link getProviderCatalog} (cache dir, TTL, fetch impl) for hermetic tests.
+     *
+     * **`cacheOnly` defaults to `true` here and nowhere else.** This resolution sits in front of the
+     * first model call of a session, and a cold `api.json` fetch is a few MB behind a 10 s timeout —
+     * a delay the user would experience as the agent hanging before it said anything, to decide a
+     * threshold that already has a fallback. `gth init` passes `cacheOnly: false` because it is an
+     * explicit, interactive step that can afford to wait, and filling the cache there is what makes
+     * the runtime read a hit.
+     */
+    catalogOptions?: CatalogOptions;
+    /** Catalog reader override; {@link getProviderCatalog} when omitted. Injected by the tests. */
+    catalogReader?: (_providerId: ProviderId, _options: CatalogOptions) => Promise<ProviderCatalog | null>;
+    /** Profile reader override; {@link readProfileContextWindow} when omitted. Injected by the tests. */
+    profileReader?: (_llm: unknown) => number | null;
+}
+/**
+ * One resolution, read two ways: {@link ResolvedContextWindow.source} for the guard, which wants
+ * only the number, and {@link ResolvedContextWindow.read} for `/status`, which also wants the
+ * provenance.
+ *
+ * They are handed out as a pair from a single factory call, over a single memoised promise, so the
+ * number `/status` prints is by construction the number the guard enforced. Two independent
+ * resolvers could disagree — a stale catalog on one and a fresh fetch on the other — and a
+ * `/status` that describes a threshold nobody is using is worse than no `/status` line at all.
+ */
+export interface ResolvedContextWindow {
+    /** The window in tokens, or `null` for unknown. Memoised; safe to call before every model call. */
+    source: ContextWindowSource;
+    /** The same resolution with its provenance attached. Shares the memoised promise. */
+    read: () => Promise<ContextWindowReading>;
+}
+/**
+ * **The one place a model is matched to a context window.** Tries ollama, then models.dev, then the
+ * LangChain profile, and answers `{ tokens: null, origin: 'unknown' }` when none of them knows.
+ *
+ * **There is deliberately no `?? DEFAULT` anywhere on this path.** One fallback turns every unknown
+ * window into a confident wrong number, which is the 4097 failure this file opens by naming.
+ *
+ * The whole resolution is memoised as a PROMISE, for the reason the ollama source already gives:
+ * this runs before every model call, the answer cannot change during a session, and holding the
+ * promise rather than the value means concurrent calls share one catalog read instead of racing to
+ * make several.
+ */
+export declare function resolveContextWindow(llm: unknown, options?: ContextWindowResolutionOptions): ResolvedContextWindow;
+/**
+ * The window as a bare number, for a caller that does not need the provenance.
+ *
+ * A thin wrapper over {@link resolveContextWindow} rather than a second implementation, so the two
+ * cannot answer differently. With no options it consults only the sources that need no
+ * configuration — ollama and the profile — which is why a plain object with neither still answers
+ * `null`.
+ */
+export declare function resolveContextWindowSource(llm: unknown, options?: ContextWindowResolutionOptions): ContextWindowSource;