opencode-swarm 7.154.2 → 7.154.3

package/dist/services/compaction-service.d.ts

@@ -7,9 +7,15 @@
  *  - Reflection  (default 60%): re-summarise into tighter format
  *  - Emergency   (default 80%): hard truncation to system + current task + last N turns
  *
- * Consumes the per-session budget pct recorded by system-enhancer.ts after
- * each budget calc (`getSessionBudgetPct`).
- * Never throws. Advisory system message injection via callback.
+ * Consumes the per-session FINAL PROMPT PRESSURE recorded by the final
+ * context-accounting step (#2107 §3) after every injector has run
+ * (`getFinalPromptPressure`); before that step has run for a session it falls
+ * back to the legacy injection-footprint pct (`getSessionBudgetPct`) so the
+ * tiers never go dark.
+ * Never throws. Advisory system message injection via callback. These tiers
+ * ADVISE the model to compact — they never compact anything themselves and
+ * never claim a compaction was performed (only the physical pruning in
+ * src/hooks/context-budget.ts actually removes content).
  */
 import type { CompactionConfig } from '../config/schema';
 export type { CompactionConfig };

package/dist/services/context-budget-service.d.ts

@@ -74,10 +74,14 @@ export interface BudgetState {
  */
 export declare const DEFAULT_CONTEXT_BUDGET_CONFIG: ContextBudgetConfig;
 /**
- * Estimate token count for text using character-based approximation
+ * Estimate token count for text using the canonical character-based heuristic.
  *
- * @param text - The text to estimate tokens for
- * @returns Estimated token count (ceiling of chars / 3.5)
+ * Delegates to `estimateTokens` in src/hooks/utils.ts (issue #1616/#2107). This
+ * used to be an independent ÷3.5 formula, which made the user-facing budget
+ * report disagree ~15% with the injection-admission path (0.33 tok/char) on
+ * the same text. The export is kept for existing importers (capsule-builder,
+ * the services barrel); it is a heuristic — provider-reported token usage is
+ * authoritative when available.
  */
 export declare function estimateTokens(text: string): number;
 /**

package/dist/services/injection-budget.d.ts

@@ -1,8 +1,10 @@
 /**
  * Unified Injection Budget Service (FR-002).
  *
- * Pure, side-effect-free allocation function for the combined
- * system-enhancer + knowledge-injector injection ceiling.
+ * Two responsibilities: (1) the pure, side-effect-free FR-002 allocation
+ * function for the combined system-enhancer + knowledge-injector injection
+ * ceiling, and (2) the per-session/per-turn producer ledger (#2107 §2) that
+ * every model-visible producer claims from or records emissions into.
  *
  * Allocation strategy: proportional share.
  * - When combined demand fits within the budget, each component receives its
@@ -20,8 +22,8 @@
  * Priority-based allocation would require an arbitrary component ranking
  * not specified by the acceptance criteria.
  *
- * Char-to-token conversion uses the project's existing 0.33 tok/char ratio
- * (matches `estimateTokens` in src/hooks/utils.ts:200).
+ * Char-to-token conversion goes through the canonical estimator
+ * (`estimateTokensFromCharCount` in src/hooks/utils.ts — issue #1616/#2107).
  */
 /**
  * Allocation result for a single turn's unified injection budget.
@@ -59,40 +61,115 @@ export interface InjectionBudgetConfig {
  */
 export declare function allocateInjectionBudget(systemEnhancerDemandTokens: number, knowledgeInjectorDemandChars: number, config: InjectionBudgetConfig): InjectionBudgetAllocation;
 /**
- * Reset the budget for a session to the full unified ceiling.
- * Called by the first component to run for a given turn.
+ * Producers that contribute to the model-visible request surface. The
+ * `surface` on each accounting entry records WHERE the producer's bytes live:
+ * `'system'` entries are pushed to `output.system` in the system.transform
+ * chain (invisible to the messages chain and to final accounting's direct
+ * measurement of `output.messages` — they MUST be added to the final total via
+ * this ledger); `'messages'` entries are spliced into `output.messages` and are
+ * therefore already inside the final measurement (attribution only — adding
+ * them again would double-count).
  */
-export declare function resetUnifiedBudget(sessionID: string, totalBudget: number): void;
+export type InjectionProducer = 'system-enhancer' | 'knowledge-injector' | 'context-capsule' | 'memory-recall' | 'advisory-queue' | 'swarm-command-banner' | 'linked-cohort-advisory' | 'spec-drift-advisory' | 'final-accounting-warning';
+export type InjectionSurface = 'system' | 'messages';
+export interface ProducerAccounting {
+    /** Tokens the producer asked the ledger for this turn (claims only). */
+    requested: number;
+    /** Tokens the ledger granted under the ceiling + local max (claims only). */
+    granted: number;
+    /** Tokens actually emitted to the model-visible surface. */
+    emitted: number;
+    /** Tokens the producer wanted but did not emit (its own pruning). */
+    truncated: number;
+    surface: InjectionSurface;
+}
+export interface TurnLedgerSummary {
+    generation: number;
+    totalBudget: number;
+    /** Ceiling enforcement is only active when `unified_injection_tokens` is configured. */
+    ceilingActive: boolean;
+    used: number;
+    producers: Array<{
+        producer: InjectionProducer;
+    } & ProducerAccounting>;
+}
+/**
+ * Begin a new turn ledger for a session: reset exactly once at the start of
+ * composing that request (the system-enhancer is the first producer and calls
+ * this). Mints a fresh generation, so any stale claim from a prior composition
+ * is discarded. `ceilingActive` is only true when
+ * `context_budget.unified_injection_tokens` is configured; when false the
+ * ledger records accounting but never denies a claim (default configs keep
+ * their pre-#2107 behavior).
+ */
+export declare function beginTurnLedger(sessionID: string, totalBudget: number, ceilingActive: boolean): number;
+/**
+ * Claim tokens from the turn ledger. The grant is bounded by the producer's
+ * own local maximum (`localMaxTokens`) and, only when the ceiling is active,
+ * by what remains of the unified ceiling. When NO ledger exists for the session
+ * (system-enhancer never ran this turn — native agent, first turn, or hook
+ * disabled), the claim fails open to the local maximum and is not recorded,
+ * preserving #1617's fail-open contract; the caller is expected to report that
+ * the hard ceiling was unavailable.
+ */
+export declare function claimTurnBudget(sessionID: string, producer: InjectionProducer, requestedTokens: number, opts?: {
+    localMaxTokens?: number;
+    surface?: InjectionSurface;
+}): {
+    granted: number;
+    ledgerPresent: boolean;
+    ceilingActive: boolean;
+};
+/**
+ * Record a producer's grant without claiming through `claimTurnBudget`.
+ *
+ * The system-enhancer and knowledge-injector enforce their split through the
+ * pure `allocateInjectionBudget` (FR-002 contract, pinned by tests) rather than
+ * sequential claims; this books their allocator-derived grants into the shared
+ * ceiling so later claimants (capsule, memory recall) draw from what actually
+ * remains. When the ceiling is inactive the grant is recorded but deducts
+ * nothing. The deduction is clamped to the remaining budget so `used` can never
+ * exceed `totalBudget`.
+ */
+export declare function recordProducerGrant(sessionID: string, producer: InjectionProducer, requestedTokens: number, grantedTokens: number, surface: InjectionSurface): void;
 /**
- * Return the remaining unified budget for a session.
+ * Record what a producer actually emitted (and pruned itself) this turn.
+ * Producers that never claim (fixed/base content: advisory queue, banners,
+ * the context-budget warning, the final-accounting warning) still record their
+ * emission here so the final accounting can include them.
  */
-export declare function getUnifiedBudgetRemaining(sessionID: string): number;
+export declare function recordProducerEmission(sessionID: string, producer: InjectionProducer, emittedTokens: number, truncatedTokens: number, surface: InjectionSurface): void;
 /**
- * Request a slice of the unified budget. Returns the granted token count.
- * If the requester's need exceeds the remaining budget, it gets the remainder
- * and the other source is implicitly blocked (remaining drops to 0).
+ * Snapshot of the session's current turn ledger (null when absent).
  */
-export declare function requestUnifiedBudget(sessionID: string, requestedTokens: number): number;
 /**
- * Return the total unified budget configured for a session (or 0 if unset).
+ * Deduct tokens from a producer's recorded emission (#2107 §3): downstream
+ * system-chain mutators (the role filter) REMOVE strings after the producer
+ * recorded them, and the final accounting must not count bytes the model
+ * never sees. Floors at zero; no-op without a ledger or producer entry.
  */
-export declare function getUnifiedBudgetTotal(sessionID: string): number;
+export declare function deductProducerEmission(sessionID: string, producer: InjectionProducer, removedTokens: number): void;
+export declare function getTurnLedgerSummary(sessionID: string): TurnLedgerSummary | null;
 /**
- * Remove a session's budget entry. Used for cleanup in tests.
+ * Emitted tokens recorded for one producer this turn (0 when no ledger or the
+ * producer has not run). Replaces the old `getSystemEnhancerDemand` relay: the
+ * knowledge-injector reads the system-enhancer's actual emission from here.
  */
-export declare function clearUnifiedBudget(sessionID: string): void;
+export declare function getProducerEmission(sessionID: string, producer: InjectionProducer): number;
 /**
- * Ensure a budget entry exists for the session. Creates one with the full
- * budget if none exists; leaves an existing entry untouched.
+ * Advance the turn generation for a session: the current ledger is discarded so
+ * the next request composition starts from a fresh generation. Called when
+ * compaction changes the message surface (`experimental.session.compacting`)
+ * and at session teardown.
  */
-export declare function ensureSessionBudget(sessionID: string, totalBudget: number): void;
+export declare function advanceTurnGeneration(sessionID: string): void;
 /**
- * Store the system-enhancer's actual per-turn token demand so that
- * knowledge-injector can read it and compute its proportional share.
+ * Test/maintenance hook: clear one session's ledger.
  */
-export declare function setSystemEnhancerDemand(sessionID: string, demand: number): void;
+export declare function clearTurnLedger(sessionID: string): void;
 /**
- * Return the system-enhancer's actual per-turn token demand for a session.
- * Returns 0 if no budget entry exists or demand was not set.
+ * Clear every session's ledger. Called from `resetSwarmState` so the
+ * plugin-wide reset also resets per-turn producer accounting (zaxbysauce
+ * review on PR #2415: the reset pattern must cover ALL module-scoped maps).
  */
-export declare function getSystemEnhancerDemand(sessionID: string): number;
+export declare function clearAllTurnLedgers(): void;

package/dist/state.d.ts

@@ -723,6 +723,34 @@ export declare const swarmState: {
         pct: number;
         tokens: number;
     }>;
+    /**
+     * Final model-visible prompt pressure per session (#2107 §3) — the ONE
+     * truthful measurement taken after every injector has run and the system
+     * messages have been consolidated. Unlike `lastBudgetBySession` (the swarm
+     * INJECTION FOOTPRINT pct measured from an intermediate file surface),
+     * this is estimated total prompt tokens vs the same model limit physical
+     * pruning uses. Written by the final-context-accounting step; read by the
+     * compaction tiers, the CONTEXT PRESSURE advisory, and `/swarm status`.
+     * Bounded via {@link setFinalPromptPressure} (AGENTS.md invariant 8).
+     */
+    finalPromptPressureBySession: Map<string, {
+        pct: number;
+        usedTokens: number;
+        limitTokens: number;
+        estimatorSource: string;
+        providerReported: boolean;
+    }>;
+    /**
+     * Per-session final-accounting warning-band latch (#2107 §3): one bounded
+     * advisory per session per band (warn / critical). Kept here — not in the
+     * hook module — so `resetSwarmState` covers it like every other
+     * session-keyed map (AGENTS.md invariant 8). Bounded via
+     * {@link setFinalAccountingWarningBand}.
+     */
+    finalAccountingWarningBandsBySession: Map<string, {
+        warn: boolean;
+        critical: boolean;
+    }>;
     /**
      * Live `model.limit.context` per session — keyed by sessionID and bound to
      * the reporting model/provider identity. Recorded by the
@@ -1382,6 +1410,34 @@ export declare function getLiveContextModelIdentity(sessionID: string | undefine
  *  written together so `/swarm status` can never pair a pct from one report
  *  with a denominator from another. */
 export declare function setSessionBudget(sessionID: string, pct: number, tokens: number): void;
+/**
+ * Record this session's final prompt pressure (#2107 §3), FIFO-evicting the
+ *  oldest entry past {@link MAX_TRACKED_BUDGET_SESSIONS}. Written once per request
+ *  composition by the final-context-accounting step.
+ */
+export declare function setFinalPromptPressure(sessionID: string, snapshot: {
+    pct: number;
+    usedTokens: number;
+    limitTokens: number;
+    estimatorSource: string;
+    providerReported: boolean;
+}): void;
+/** The session's final prompt pressure snapshot, or undefined when the final
+ *  accounting step has not run for it (e.g. native-agent sessions). */
+export declare function getFinalPromptPressure(sessionID: string | undefined): {
+    pct: number;
+    usedTokens: number;
+    limitTokens: number;
+    estimatorSource: string;
+    providerReported: boolean;
+} | undefined;
+/** Record that this session's #2107 §3 advisory already fired for a band
+ *  (one advisory per session per band), FIFO-evicting past the cap. */
+export declare function setFinalAccountingWarningBand(sessionID: string, band: 'warn' | 'critical'): void;
+/** Whether this session already received the band's advisory. */
+export declare function getFinalAccountingWarningBand(sessionID: string | undefined, band: 'warn' | 'critical'): boolean;
+/** Clear all band latches (used by resetSwarmState and tests). */
+export declare function clearFinalAccountingWarningBands(): void;
 /** This session's last budget percentage, or 0 if it has not been measured.
  *  Consumers that ACT on a session (compaction, the context-pressure advisory)
  *  MUST use this rather than any cross-session aggregate. */
@@ -1397,6 +1453,19 @@ export declare function getDisplayBudget(): {
     pct: number;
     tokens: number;
 } | null;
+/**
+ * The most-pressured session's FINAL prompt pressure snapshot, for
+ * process-wide DISPLAY only (`/swarm status` has no single session in scope).
+ * The snapshot is returned whole so the pct, used tokens, limit, and estimator
+ * source shown together always come from one measurement (#2107 §3).
+ */
+export declare function getDisplayFinalPromptPressure(): {
+    pct: number;
+    usedTokens: number;
+    limitTokens: number;
+    estimatorSource: string;
+    providerReported: boolean;
+} | null;
 /** Set the critical shown ids for a session, FIFO-evicting the oldest entry
  * if the cap is exceeded. Re-setting an existing key keeps insertion order
  * fresh for that key (delete-then-set). */

package/dist/summaries/summarizer.d.ts

@@ -44,11 +44,40 @@ declare function summarizeJsonArray(parsed: unknown[]): string;
  */
 declare function extractCodeSignatures(code: string): string[];
 /**
- * Build a preview for code output that includes declaration signatures.
+ * Codepoint-safe truncation to a UTF-8 byte budget (#2107 §5).
+ *
+ * Iterates code points (never UTF-16 units) so a multibyte CJK/emoji run can
+ * never be split mid-codepoint, and the result is deterministic across Bun and
+ * Node (which disagree on `Buffer.byteLength` for unpaired surrogates — per
+ * code point, both agree). Returns the kept text and the exact number of bytes
+ * omitted.
+ */
+export declare function truncateToBytes(text: string, maxBytes: number): {
+    text: string;
+    omittedBytes: number;
+};
+/**
+ * Deterministic bounded head/tail preview (#2107 §5).
+ *
+ * Head: the leading non-blank identity lines (ceil half of the line budget).
+ * Tail: the trailing RAW outcome lines (floor half) — compiler, test, lint,
+ * and security verdicts live at the END of tool output, so the old head-only
+ * preview discarded exactly the decision-relevant evidence. Lines are never
+ * reordered within either segment, no outcome is invented, and every dropped
+ * region is disclosed with an accurate omitted-line count. When everything
+ * fits, the original text is returned unchanged (modulo per-line caps).
+ */
+declare function headTailPreview(output: string, maxLines: number): string;
+/**
+ * Build a preview for code output that includes declaration signatures plus
+ * the bounded head/tail policy (failure output at the end of a code blob is
+ * preserved).
  */
 declare function summarizeCode(output: string): string;
 /**
- * Build a preview for plain text output (leading non-blank lines).
+ * Build a preview for plain text output using the bounded head/tail policy
+ * (see headTailPreview). Previously head-only: the first `maxLines` non-blank
+ * lines, which silently discarded trailing failure/exit evidence.
  */
 declare function summarizeText(output: string, maxLines: number): string;
 /**
@@ -56,7 +85,7 @@ declare function summarizeText(output: string, maxLines: number): string;
  * @param output - The full tool output string
  * @param toolName - The name of the tool that produced the output
  * @param summaryId - Unique identifier for this summary
- * @param maxSummaryChars - Maximum characters allowed for the preview
+ * @param maxSummaryChars - Maximum bytes allowed for the preview
  * @returns Formatted summary string
  */
 export declare function createSummary(output: string, toolName: string, summaryId: string, maxSummaryChars: number): string;
@@ -64,6 +93,8 @@ export declare function createSummary(output: string, toolName: string, summaryI
  * Internal helpers exposed for testability.
  */
 export declare const _internals: {
+    truncateToBytes: typeof truncateToBytes;
+    headTailPreview: typeof headTailPreview;
     jsonTypeSignature: typeof jsonTypeSignature;
     summarizeJsonObject: typeof summarizeJsonObject;
     summarizeJsonArray: typeof summarizeJsonArray;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.154.2",
+	"version": "7.154.3",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -114,6 +114,7 @@
 		"check:trajectory-store": "bun run scripts/check-trajectory-store-usage.ts",
 		"check:mock-cleanup": "bun run scripts/check-mock-cleanup.ts",
 		"check:invariants": "bun run scripts/check-invariants.ts",
+		"check:token-formula": "bun run scripts/check-token-formula.ts",
 		"check:cross-contamination": "bun run scripts/check-cross-contamination.ts",
 		"check:test-clock": "bun run scripts/check-test-clock.ts",
 		"check:test-file-cap": "bun run scripts/check-test-file-cap.ts",