agent-nuvira 3.3.11 → 3.3.13

package/dist/learning/model-selection.js

@@ -68,9 +68,28 @@ export function hasCredentials(configManager, provider) {
  * failed outright.
  */
 export const MODEL_HEALTH_CEILING = 0.6;
+/**
+ * How much a verification SOURCE is worth when ranking models of equal health.
+ * Lower = more trustworthy, so it sorts first.
+ *
+ * A `spot-check` is a single 1-token generation: it proves the model NAME
+ * exists and accepts a request — it does NOT prove the model can hold a task.
+ * `telemetry` is real traffic (hundreds of samples), so it is the strongest
+ * evidence we have. Ranking them as equals let a model with six probe samples
+ * (observed live: `deepseek-v4-pro`, 6 samples) sit at errorRate 0 beside a
+ * model with 290 real calls (`deepseek-flash`) — and whenever the configured
+ * pin was dead, the fallback walk could then hand a caller a model that had
+ * never actually done a task. Real evidence must win.
+ */
+const SOURCE_CONFIDENCE = {
+    telemetry: 0,
+    'spot-check': 1,
+    probe: 2,
+};
 /**
  * Verified working models for a provider, ranked by learned health:
- * lowest error rate first, then lowest latency, then most recently verified.
+ * strongest verification source first, then lowest error rate, then lowest
+ * latency, then most recently verified.
  * Empty when nothing has been verified yet (cold start / no keys).
  *
  * MODELS AT/ABOVE `MODEL_HEALTH_CEILING` SORT AFTER THE HEALTHY ONES but are
@@ -96,6 +115,13 @@ export function preferredModelsFor(provider) {
         .sort((a, b) => {
         const ea = registry.getEntry(provider, a);
         const eb = registry.getEntry(provider, b);
+        // 1. Evidence strength. A model proven by real traffic must outrank one
+        //    that only ever answered a 1-token probe — they are NOT equivalent
+        //    evidence, and treating them as such is how an unproven model won.
+        const sa = SOURCE_CONFIDENCE[ea?.source ?? 'probe'] ?? 2;
+        const sb = SOURCE_CONFIDENCE[eb?.source ?? 'probe'] ?? 2;
+        if (sa !== sb)
+            return sa - sb;
         const ra = ea?.errorRate ?? 0;
         const rb = eb?.errorRate ?? 0;
         if (ra !== rb)
@@ -156,8 +182,10 @@ export function rankAvailableProviders(configManager) {
     // providers join routing the moment they appear in config. Nothing is
     // hardcoded to the 6 built-ins anymore.
     let configuredIds = [];
+    let providerConfig = {};
     try {
-        configuredIds = Object.keys(configManager.getAll?.()?.providers ?? {});
+        providerConfig = configManager.getAll?.()?.providers ?? {};
+        configuredIds = Object.keys(providerConfig);
     }
     catch {
         // Best-effort.
@@ -165,6 +193,11 @@ export function rankAvailableProviders(configManager) {
     const candidates = [...new Set([...CATALOG_PROVIDER_IDS, ...configuredIds])].filter((p) => {
         if (blocked.has(p))
             return false;
+        // The dashboard's per-provider On/Off switch. Off removes the provider from
+        // the AUTO pool only; credentials stay on disk, and an explicit `--provider`
+        // pin is a user decision the router does not second-guess.
+        if (providerConfig[p]?.enabled === false)
+            return false;
         // Keyless runners BEYOND `local` (nuvira, lmstudio, vllm) only join when the
         // registry has VERIFIED them or the user explicitly configured them — a
         // not-running localhost endpoint must never out-rank running local on a

package/dist/learning/model-selection.js.map

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

package/dist/learning/project-docs.d.ts

@@ -0,0 +1,83 @@
+/**
+ * PROJECT DOCUMENTATION (software deliverables).
+ *
+ * The gap this closes: a software build produced CODE and stopped. The
+ * documents a real project ships — a README, a changelog that grows with each
+ * change, a short architecture note with a diagram, and (for a library/service)
+ * usage + API docs — were only produced when the user named them, which is
+ * exactly backwards: a user should not have to ask a "world-class developer" to
+ * write down what it built.
+ *
+ * Two rules keep this from becoming noise:
+ *
+ *   1. **Software only.** This module is consulted ONLY for a `code` deliverable
+ *      that is not authored (`deliverable-class.ts` already separates a poem
+ *      from a program). Nobody wants a README and an ARCHITECTURE.md for
+ *      "write me a poem about rain" — the classifier decides, and this guidance
+ *      is never appended to an authored ask.
+ *   2. **Proportionate.** A README and a CHANGELOG are expected of every
+ *      software deliverable; the heavier documents (architecture, API reference,
+ *      contributing guide) are asked for only when the shape warrants them —
+ *      a multi-component or library/service build, or an explicit request for
+ *      docs. A one-file script still gets a README; it is not asked to invent an
+ *      architecture diagram.
+ *
+ * It also encodes the maintenance rule the user cares about: an EXISTING
+ * document is UPDATED in place (CHANGELOG gets a new entry at the top), never
+ * shadowed by a second file — a project with two changelogs is worse than one
+ * with none.
+ *
+ * Pure and side-effect free: every input is data, so it is unit-testable and can
+ * be appended to any prompt without touching the filesystem.
+ */
+/** The canonical documents a software project ships, in priority order. */
+export interface ProjectDocArtifact {
+    /** Project-relative path the document lives at. */
+    path: string;
+    /** What it is FOR — handed to the model so the document has a job. */
+    purpose: string;
+    /** Required of every software deliverable (README, CHANGELOG). */
+    always: boolean;
+}
+export declare const PROJECT_DOC_ARTIFACTS: readonly ProjectDocArtifact[];
+/** What we know about the deliverable, from the goal + project assessment. */
+export interface ProjectDocShape {
+    /**
+     * True when the workspace has no project yet (a scaffold). A greenfield build
+     * gets the full proportionate set rather than only the always-on pair.
+     */
+    greenfield?: boolean;
+    /**
+     * A library, package, SDK or service — a thing other code CONSUMES — rather
+     * than an end-user app. Its public surface must be documented.
+     */
+    isLibraryOrService?: boolean;
+    /** The project already exposes tests (or the agent is expected to write them). */
+    hasTests?: boolean;
+    /** Names the user explicitly asked for docs ("with documentation", "API docs"). */
+    docsRequested?: boolean;
+    /**
+     * Documents that ALREADY exist in the workspace (project-relative paths).
+     * These are UPDATED in place, never duplicated.
+     */
+    existingDocs?: readonly string[];
+}
+/** The always-on pair, plus the heavier docs a bigger build warrants. */
+export declare function requiredProjectDocs(shape?: ProjectDocShape): string[];
+/**
+ * Does the goal name something other code CONSUMES (a library, package, SDK,
+ * CLI, service, plugin) rather than an end-user app? A consumed surface has a
+ * public API worth documenting; an app does not need an API reference.
+ */
+export declare function looksLikeLibraryOrService(goal: string): boolean;
+/** The required docs that do NOT yet exist on disk (the ones to CREATE). */
+export declare function missingProjectDocs(shape?: ProjectDocShape): string[];
+/** The required docs that already exist (the ones to UPDATE, not recreate). */
+export declare function existingProjectDocs(shape?: ProjectDocShape): string[];
+/**
+ * The instruction appended to the reasoner/planner prompt for a SOFTWARE
+ * deliverable. Returns `''` for a non-software (authored) ask, so callers can
+ * append it unconditionally without a poem ever being asked for a CHANGELOG.
+ */
+export declare function softwareProjectGuidance(verdictClass: string, authored: boolean, shape?: ProjectDocShape): string;
+//# sourceMappingURL=project-docs.d.ts.map

package/dist/learning/project-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-docs.d.ts","sourceRoot":"","sources":["../../src/learning/project-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAqC9D,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAU/D;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAGxE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,MAAM,EAAE,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,OAAO,EACjB,KAAK,GAAE,eAAoB,GAC1B,MAAM,CAmCR"}

package/dist/learning/project-docs.js

@@ -0,0 +1,132 @@
+/**
+ * PROJECT DOCUMENTATION (software deliverables).
+ *
+ * The gap this closes: a software build produced CODE and stopped. The
+ * documents a real project ships — a README, a changelog that grows with each
+ * change, a short architecture note with a diagram, and (for a library/service)
+ * usage + API docs — were only produced when the user named them, which is
+ * exactly backwards: a user should not have to ask a "world-class developer" to
+ * write down what it built.
+ *
+ * Two rules keep this from becoming noise:
+ *
+ *   1. **Software only.** This module is consulted ONLY for a `code` deliverable
+ *      that is not authored (`deliverable-class.ts` already separates a poem
+ *      from a program). Nobody wants a README and an ARCHITECTURE.md for
+ *      "write me a poem about rain" — the classifier decides, and this guidance
+ *      is never appended to an authored ask.
+ *   2. **Proportionate.** A README and a CHANGELOG are expected of every
+ *      software deliverable; the heavier documents (architecture, API reference,
+ *      contributing guide) are asked for only when the shape warrants them —
+ *      a multi-component or library/service build, or an explicit request for
+ *      docs. A one-file script still gets a README; it is not asked to invent an
+ *      architecture diagram.
+ *
+ * It also encodes the maintenance rule the user cares about: an EXISTING
+ * document is UPDATED in place (CHANGELOG gets a new entry at the top), never
+ * shadowed by a second file — a project with two changelogs is worse than one
+ * with none.
+ *
+ * Pure and side-effect free: every input is data, so it is unit-testable and can
+ * be appended to any prompt without touching the filesystem.
+ */
+export const PROJECT_DOC_ARTIFACTS = [
+    {
+        path: 'README.md',
+        purpose: 'what the project is, how to install it, and a copy-pasteable quick start — the FIRST thing a ' +
+            'newcomer reads',
+        always: true,
+    },
+    {
+        path: 'CHANGELOG.md',
+        purpose: 'Keep a Changelog format, newest section first (Added / Changed / Fixed / Removed) — every ' +
+            'meaningful change appends an entry here',
+        always: true,
+    },
+    {
+        path: 'ARCHITECTURE.md',
+        purpose: 'the components, how data flows between them, and a diagram (a Mermaid `flowchart` or ' +
+            '`sequenceDiagram` block renders on GitHub with no tooling)',
+        always: false,
+    },
+    {
+        path: 'docs/usage.md',
+        purpose: 'task-oriented guides: "how do I do X", with working examples',
+        always: false,
+    },
+    {
+        path: 'docs/api.md',
+        purpose: 'the public API reference — every exported symbol, its signature and an example',
+        always: false,
+    },
+    {
+        path: 'CONTRIBUTING.md',
+        purpose: 'how to build, test and submit a change (the commands a contributor needs)',
+        always: false,
+    },
+];
+/** The always-on pair, plus the heavier docs a bigger build warrants. */
+export function requiredProjectDocs(shape = {}) {
+    const paths = PROJECT_DOC_ARTIFACTS.filter((a) => a.always).map((a) => a.path);
+    if (shape.isLibraryOrService || shape.docsRequested)
+        paths.push('docs/api.md', 'docs/usage.md');
+    if (shape.greenfield || shape.isLibraryOrService || shape.docsRequested)
+        paths.push('ARCHITECTURE.md');
+    if (shape.hasTests)
+        paths.push('CONTRIBUTING.md');
+    // De-dupe while preserving priority order.
+    return [...new Set(paths)];
+}
+/**
+ * Does the goal name something other code CONSUMES (a library, package, SDK,
+ * CLI, service, plugin) rather than an end-user app? A consumed surface has a
+ * public API worth documenting; an app does not need an API reference.
+ */
+export function looksLikeLibraryOrService(goal) {
+    const consumed = /\b(library|lib|package|npm\s+package|sdk|module|cli|command[- ]?line|api|service|server|daemon|plugin|extension|framework|toolkit)\b/i.test(goal);
+    const endUserApp = /\b(website|web\s?app|webapp|landing\s+page|game|mobile\s+app|desktop\s+app|swiftui|android\s+app|ios\s+app)\b/i.test(goal);
+    return consumed && !endUserApp;
+}
+/** The required docs that do NOT yet exist on disk (the ones to CREATE). */
+export function missingProjectDocs(shape = {}) {
+    const existing = new Set((shape.existingDocs ?? []).map((p) => p.replace(/^\.\//, '')));
+    return requiredProjectDocs(shape).filter((p) => !existing.has(p));
+}
+/** The required docs that already exist (the ones to UPDATE, not recreate). */
+export function existingProjectDocs(shape = {}) {
+    const existing = new Set((shape.existingDocs ?? []).map((p) => p.replace(/^\.\//, '')));
+    return requiredProjectDocs(shape).filter((p) => existing.has(p));
+}
+/**
+ * The instruction appended to the reasoner/planner prompt for a SOFTWARE
+ * deliverable. Returns `''` for a non-software (authored) ask, so callers can
+ * append it unconditionally without a poem ever being asked for a CHANGELOG.
+ */
+export function softwareProjectGuidance(verdictClass, authored, shape = {}) {
+    if (authored || verdictClass !== 'code')
+        return '';
+    const create = missingProjectDocs(shape);
+    const update = existingProjectDocs(shape);
+    if (create.length === 0 && update.length === 0)
+        return '';
+    const purposeOf = (path) => PROJECT_DOC_ARTIFACTS.find((a) => a.path === path)?.purpose ?? 'project documentation';
+    const lines = [
+        '',
+        '## ⚠️ PROJECT DOCUMENTATION (this is a SOFTWARE deliverable)',
+        'Code is not the whole deliverable. A project is not finished until the',
+        'documents below exist and are current — include them as REAL plan steps with',
+        '`expectedFiles`, not as an afterthought.',
+        '',
+        'Create:',
+    ];
+    for (const path of create)
+        lines.push(`- \`${path}\` — ${purposeOf(path)}`);
+    if (update.length > 0) {
+        lines.push('', 'Update IN PLACE (do NOT create a second copy or a parallel file):');
+        for (const path of update)
+            lines.push(`- \`${path}\` — add the new state of the project (for a CHANGELOG, a new top section)`);
+    }
+    lines.push('', 'Rules:', '- Every document must reflect what was ACTUALLY built — never invent features,', '  flags or files that do not exist.', '- A document you cannot fill honestly gets a shorter honest version, not filler.', '- If the project already has these documents, UPDATING them is the task; a', '  duplicate CHANGELOG or a shadow architecture file is a defect.', '- Keep the CHANGELOG append-only going forward: each change adds an entry, and', '  old entries are never rewritten.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=project-docs.js.map

package/dist/learning/project-docs.js.map

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

package/dist/learning/prompt-budget.d.ts

@@ -0,0 +1,91 @@
+/**
+ * PROMPT BUDGET (Workstream D1).
+ *
+ * Context is a finite resource with diminishing marginal returns ("context
+ * rot"): as the prompt grows, recall and long-range reasoning get worse, so the
+ * harness must manage what it SENDS, not just what it stores. Industry practice
+ * converges on: a stable cached prefix + just-in-time retrieval + per-source
+ * caps + measurement at assembly time + deterministic degradation. This module
+ * provides the measurement and the degradation PLAN; the caller applies it.
+ *
+ * It is deliberately dependency-light and pure, so it can be unit tested without
+ * a provider, a project, or a terminal.
+ *
+ * NOTE: this is distinct from `context-budget.ts`, which resolves a model's
+ * WINDOW and output-token budget. `MAX_SYSTEM_PROMPT_CHARS` in reasoning-trace.ts
+ * bounds what the TRACE stores. This module's thresholds bound what the MODEL is
+ * SENT — the previously ungated thing (the 3.3.11 bloat was 7.6K → 32.8K chars
+ * sent with no guard).
+ */
+/** Character budgets for the outbound context (estimates, not token counts). */
+export interface PromptBudget {
+    /** Note once the whole thread exceeds this many chars. */
+    noteTotal: number;
+    /** Warn once the whole thread exceeds this many chars. */
+    warnTotal: number;
+    /** Hard ceiling: trim optional contributors until under this. */
+    maxTotal: number;
+    /** Note once the stable SYSTEM layer exceeds this. */
+    noteSystem: number;
+    /** Warn once the stable SYSTEM layer exceeds this. */
+    warnSystem: number;
+}
+export declare const DEFAULT_PROMPT_BUDGET: PromptBudget;
+interface ConfigLike {
+    getAll?: () => {
+        routing?: {
+            promptBudget?: Partial<PromptBudget>;
+        };
+    } | undefined;
+}
+/**
+ * Resolve the budget: `routing.promptBudget` overrides the defaults per key.
+ * Unknown/invalid values fall through rather than throwing.
+ */
+export declare function resolvePromptBudget(configManager?: ConfigLike): PromptBudget;
+/** How far over budget the outbound context is. */
+export type PromptBudgetLevel = 'ok' | 'note' | 'warn' | 'over';
+/** One contributor to the outbound context. */
+export interface PromptContribution {
+    /** Stable name (`system:identity+tool-contract`, `skill-hint`, …). */
+    name: string;
+    /** Size in chars. */
+    chars: number;
+    /**
+     * Degradation order: lower drops FIRST. `undefined` = never dropped (the
+     * identity/tool contract and safety clauses must survive any trim).
+     */
+    dropPriority?: number;
+}
+export interface PromptBudgetReport {
+    /** Total outbound chars across every contribution. */
+    totalChars: number;
+    /** The stable SYSTEM layer's chars. */
+    systemChars: number;
+    /** Budget band the total fell into. */
+    level: PromptBudgetLevel;
+    /** Contributions, largest first. */
+    contributions: PromptContribution[];
+    /** The single largest contributor (the one to attack first). */
+    biggest?: PromptContribution;
+    /**
+     * Names to drop, lowest value first, until the total fits under `maxTotal`.
+     * Empty when already under. Never includes a contribution without a
+     * `dropPriority`.
+     */
+    trims: string[];
+}
+/**
+ * Measure the outbound context and decide, deterministically, what to trim.
+ *
+ * The `system:`-prefixed contributions (identity/tool-contract, channel policy)
+ * are treated as the stable layer for the system budget.
+ */
+export declare function measurePromptBudget(parts: PromptContribution[], opts?: {
+    budget?: PromptBudget;
+    systemName?: string;
+}): PromptBudgetReport;
+/** A compact one-line breakdown for the console / trace summary. */
+export declare function formatPromptBudgetBreakdown(report: PromptBudgetReport): string;
+export {};
+//# sourceMappingURL=prompt-budget.d.ts.map

package/dist/learning/prompt-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-budget.d.ts","sourceRoot":"","sources":["../../src/learning/prompt-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,qBAAqB,EAAE,YAMnC,CAAC;AAOF,UAAU,UAAU;IAClB,MAAM,CAAC,EAAE,MAAM;QAAE,OAAO,CAAC,EAAE;YAAE,YAAY,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACnF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,UAAU,GAAG,YAAY,CAe5E;AAED,mDAAmD;AACnD,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,KAAK,EAAE,iBAAiB,CAAC;IACzB,oCAAoC;IACpC,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,gEAAgE;IAChE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EAAE,EAC3B,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,kBAAkB,CAsCpB;AAED,oEAAoE;AACpE,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAG9E"}

package/dist/learning/prompt-budget.js

@@ -0,0 +1,99 @@
+/**
+ * PROMPT BUDGET (Workstream D1).
+ *
+ * Context is a finite resource with diminishing marginal returns ("context
+ * rot"): as the prompt grows, recall and long-range reasoning get worse, so the
+ * harness must manage what it SENDS, not just what it stores. Industry practice
+ * converges on: a stable cached prefix + just-in-time retrieval + per-source
+ * caps + measurement at assembly time + deterministic degradation. This module
+ * provides the measurement and the degradation PLAN; the caller applies it.
+ *
+ * It is deliberately dependency-light and pure, so it can be unit tested without
+ * a provider, a project, or a terminal.
+ *
+ * NOTE: this is distinct from `context-budget.ts`, which resolves a model's
+ * WINDOW and output-token budget. `MAX_SYSTEM_PROMPT_CHARS` in reasoning-trace.ts
+ * bounds what the TRACE stores. This module's thresholds bound what the MODEL is
+ * SENT — the previously ungated thing (the 3.3.11 bloat was 7.6K → 32.8K chars
+ * sent with no guard).
+ */
+export const DEFAULT_PROMPT_BUDGET = {
+    noteTotal: 24_000,
+    warnTotal: 40_000,
+    maxTotal: 48_000,
+    noteSystem: 8_000,
+    warnSystem: 12_000,
+};
+function positiveInt(v, fallback) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? Math.round(n) : fallback;
+}
+/**
+ * Resolve the budget: `routing.promptBudget` overrides the defaults per key.
+ * Unknown/invalid values fall through rather than throwing.
+ */
+export function resolvePromptBudget(configManager) {
+    let overrides;
+    try {
+        overrides = configManager?.getAll?.()?.routing?.promptBudget;
+    }
+    catch {
+        overrides = undefined;
+    }
+    const o = overrides ?? {};
+    return {
+        noteTotal: positiveInt(o.noteTotal, DEFAULT_PROMPT_BUDGET.noteTotal),
+        warnTotal: positiveInt(o.warnTotal, DEFAULT_PROMPT_BUDGET.warnTotal),
+        maxTotal: positiveInt(o.maxTotal, DEFAULT_PROMPT_BUDGET.maxTotal),
+        noteSystem: positiveInt(o.noteSystem, DEFAULT_PROMPT_BUDGET.noteSystem),
+        warnSystem: positiveInt(o.warnSystem, DEFAULT_PROMPT_BUDGET.warnSystem),
+    };
+}
+const SYSTEM_NAME_PREFIX = 'system:';
+/**
+ * Measure the outbound context and decide, deterministically, what to trim.
+ *
+ * The `system:`-prefixed contributions (identity/tool-contract, channel policy)
+ * are treated as the stable layer for the system budget.
+ */
+export function measurePromptBudget(parts, opts) {
+    const budget = opts?.budget ?? DEFAULT_PROMPT_BUDGET;
+    const clean = parts
+        .filter((p) => Number.isFinite(p.chars) && p.chars > 0)
+        .map((p) => ({ ...p, chars: Math.round(p.chars) }));
+    const totalChars = clean.reduce((n, p) => n + p.chars, 0);
+    const systemChars = clean
+        .filter((p) => p.name.startsWith(SYSTEM_NAME_PREFIX) || p.name === opts?.systemName)
+        .reduce((n, p) => n + p.chars, 0);
+    const level = totalChars > budget.maxTotal
+        ? 'over'
+        : totalChars > budget.warnTotal || systemChars > budget.warnSystem
+            ? 'warn'
+            : totalChars > budget.noteTotal || systemChars > budget.noteSystem
+                ? 'note'
+                : 'ok';
+    const contributions = [...clean].sort((a, b) => b.chars - a.chars);
+    const biggest = contributions[0];
+    // Deterministic ladder: drop optional contributors by ascending dropPriority
+    // (lowest value = least valuable = dropped first) until under the ceiling.
+    const trims = [];
+    if (totalChars > budget.maxTotal) {
+        const droppable = clean
+            .filter((p) => p.dropPriority !== undefined)
+            .sort((a, b) => (a.dropPriority ?? 0) - (b.dropPriority ?? 0));
+        let running = totalChars;
+        for (const p of droppable) {
+            if (running <= budget.maxTotal)
+                break;
+            trims.push(p.name);
+            running -= p.chars;
+        }
+    }
+    return { totalChars, systemChars, level, contributions, biggest, trims };
+}
+/** A compact one-line breakdown for the console / trace summary. */
+export function formatPromptBudgetBreakdown(report) {
+    const top = report.contributions.slice(0, 5).map((c) => `${c.name} ${c.chars}`);
+    return `context ${report.totalChars} chars (${report.level}) — ${top.join(', ')}`;
+}
+//# sourceMappingURL=prompt-budget.js.map

package/dist/learning/prompt-budget.js.map

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

package/dist/learning/quota-ledger.d.ts

@@ -215,6 +215,19 @@ export declare class QuotaLedger {
      * Effective quota limits for a provider from config (`routing.quota`).
      */
     private limitsFor;
+    /**
+     * ADMIN-BUDGET exhaustion ONLY: is this provider over the window budget the
+     * user DECLARED in `routing.quota.<provider>`?
+     *
+     * Deliberately ignores transient parks/cooldowns. A rate-limit park is a
+     * provider hiccup that may clear in seconds and says nothing about the user's
+     * plan; the admin budget is a control the user set, so the two must be
+     * separable. The pinned-run preflight reads THIS (a declared limit) — never
+     * the blended `getRouterQuotaStatus()` — so an explicit selection is refused
+     * only when it genuinely exceeds the budget the user configured, and is still
+     * given its shot after a transient 429.
+     */
+    isOverConfiguredLimit(configManager: ConfigManager | undefined, provider: string): boolean;
     /**
      * Build the router's "parked providers" feed — providers that must sink
      * below healthy candidates because they are exhausted or in cooldown.

package/dist/learning/quota-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quota-ledger.d.ts","sourceRoot":"","sources":["../../src/learning/quota-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAK5C,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CACzD;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;CAC9B;AAED,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/E,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAiCD;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkB;IAC/B,kFAAkF;IAClF,OAAO,CAAC,aAAa,CAAqB;;IAM1C,0CAA0C;IAC1C,OAAO,CAAC,IAAI;IAYZ,OAAO,CAAC,IAAI;IASZ,2EAA2E;IAC3E,OAAO,CAAC,WAAW;IAkBnB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,YAAY;IAsBpB;;;;;;;;;;OAUG;IACH,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI;IAaP;;;;;;;;;OASG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IA6BpE;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAmBhF;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAW7C,oEAAoE;IACpE,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAqBvC,8EAA8E;IAC9E,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAgBtF,gFAAgF;IAChF,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAczD,mEAAmE;IACnE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAS7D,oEAAoE;IACpE,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAchD;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAa1E;;;OAGG;IACH,UAAU,CAAC,KAAK,SAAK,GAAG,UAAU,EAAE;IAoBpC,yEAAyE;IACzE,WAAW,IAAI,IAAI;IASnB;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO;IA0B1E;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;;;OAOG;IACH,oBAAoB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;IAgD3G;;;;;;;;;OASG;IACH,mBAAmB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;IAyBzH;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,MAAM,EAAE;IAM9E,gEAAgE;IAChE,SAAS,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,WAAW,EAAE;IA4BvD;;;;;;;;;OASG;IACH,cAAc,IAAI;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B;IA8BD,yCAAyC;IACzC,QAAQ,IAAI,eAAe;IAiB3B,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAMb,2CAA2C;IAC3C,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOrC,oCAAoC;IACpC,YAAY,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,MAAM;CAuBpD;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOnD;AAMD,+CAA+C;AAC/C,wBAAgB,cAAc,IAAI,WAAW,CAK5C;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,iEAAiE;AACjE,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"quota-ledger.d.ts","sourceRoot":"","sources":["../../src/learning/quota-ledger.ts"],"names":[],"mappings":"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"}

package/dist/learning/quota-ledger.js

@@ -437,6 +437,34 @@ export class QuotaLedger {
     limitsFor(configManager, provider) {
         return configManager?.getAll().routing?.quota?.[provider];
     }
+    /**
+     * ADMIN-BUDGET exhaustion ONLY: is this provider over the window budget the
+     * user DECLARED in `routing.quota.<provider>`?
+     *
+     * Deliberately ignores transient parks/cooldowns. A rate-limit park is a
+     * provider hiccup that may clear in seconds and says nothing about the user's
+     * plan; the admin budget is a control the user set, so the two must be
+     * separable. The pinned-run preflight reads THIS (a declared limit) — never
+     * the blended `getRouterQuotaStatus()` — so an explicit selection is refused
+     * only when it genuinely exceeds the budget the user configured, and is still
+     * given its shot after a transient 429.
+     */
+    isOverConfiguredLimit(configManager, provider) {
+        const limit = this.limitsFor(configManager, provider);
+        if (!limit)
+            return false;
+        let requests = 0;
+        let tokens = 0;
+        for (const entry of Object.values(this.state.entries)) {
+            if (entry.provider !== provider)
+                continue;
+            this.rotateWindow(entry);
+            requests += entry.requests;
+            tokens += entry.tokensConsumed;
+        }
+        return ((limit.requestsPerWindow !== undefined && requests >= limit.requestsPerWindow) ||
+            (limit.tokensPerWindow !== undefined && tokens >= limit.tokensPerWindow));
+    }
     /**
      * Build the router's "parked providers" feed — providers that must sink
      * below healthy candidates because they are exhausted or in cooldown.