crewly 1.13.0 → 1.14.0

package/packages/crewly-agent/src/runtime/agent-runner.service.test.ts

@@ -93,7 +93,7 @@ describe('AgentRunnerService', () => {
 
       expect(result.text).toBe('Hello from agent');
       expect(result.steps).toBe(1);
-      expect(result.usage).toEqual({ input: 100, output: 50 });
+      expect(result.usage).toEqual({ input: 100, output: 50, cachedInput: 0 });
       expect(result.toolCalls).toEqual([]);
       expect(result.finishReason).toBe('stop');
     });
@@ -194,7 +194,7 @@ describe('AgentRunnerService', () => {
 
       const result = await runner.run('Test');
 
-      expect(result.usage).toEqual({ input: 0, output: 0 });
+      expect(result.usage).toEqual({ input: 0, output: 0, cachedInput: 0 });
     });
 
     it('should throw if not initialized', async () => {
@@ -614,18 +614,24 @@ describe('AgentRunnerService', () => {
   });
 
   describe('getContextBudget', () => {
-    it('should return normal level with zero usage', () => {
+    it('should return normal level before any request has been billed', () => {
       const budget = runner.getContextBudget();
 
-      expect(budget.totalTokensUsed).toBe(0);
-      expect(budget.usagePercent).toBe(0);
+      expect(budget.lifetimeTokensUsed).toBe(0);
+      // No provider measurement yet, so occupancy is estimated from the system
+      // prompt — small but non-zero, and it must not read as an empty context.
+      expect(budget.contextTokensUsed).toBeGreaterThan(0);
+      expect(budget.usagePercent).toBeLessThan(0.01);
       expect(budget.level).toBe('normal');
       expect(budget.messageCount).toBe(0);
       expect(budget.compactionPending).toBe(false);
       expect(budget.contextWindowSize).toBeGreaterThan(0);
     });
 
-    it('should track cumulative token usage', async () => {
+    it('separates context occupancy from lifetime spend', async () => {
+      // The two must diverge: history is re-sent every turn, so lifetime spend
+      // accumulates while occupancy only reflects the latest prompt. Conflating
+      // them drove `usagePercent` past 100% within a few turns.
       await runner.initialize();
       mockGenerateText.mockResolvedValueOnce({
         text: 'Response',
@@ -635,9 +641,41 @@ describe('AgentRunnerService', () => {
       });
       await runner.run('Hello');
 
+      expect(runner.getContextBudget().lifetimeTokensUsed).toBe(700);
+      expect(runner.getContextBudget().contextTokensUsed).toBe(700);
+
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'Response 2',
+        steps: [],
+        usage: { inputTokens: 800, outputTokens: 100 },
+        finishReason: 'stop',
+      });
+      await runner.run('Hello again');
+
       const budget = runner.getContextBudget();
-      expect(budget.totalTokensUsed).toBe(700);
-      expect(budget.messageCount).toBe(2); // user + assistant
+      expect(budget.lifetimeTokensUsed).toBe(1600); // 700 + 900, still climbing
+      expect(budget.contextTokensUsed).toBe(900);   // just the latest prompt
+      expect(budget.messageCount).toBe(4);
+    });
+
+    it('counts cache hits as occupying the window even though they bill cheaper', async () => {
+      // Cached tokens are served at a discount but are still part of the
+      // prompt. Dropping them would make a well-cached session look almost
+      // empty and defeat compaction entirely.
+      await runner.initialize();
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'Response',
+        steps: [],
+        usage: { inputTokens: 300, outputTokens: 100, cachedInputTokens: 20_000 },
+        finishReason: 'stop',
+      });
+      await runner.run('Hello');
+
+      const budget = runner.getContextBudget();
+      expect(budget.contextTokensUsed).toBe(20_400);
+      // Billing is unaffected — lifetime counts only what the provider charged
+      // as fresh input plus output.
+      expect(budget.lifetimeTokensUsed).toBe(400);
     });
 
     it('should return warning level when approaching threshold', async () => {
@@ -657,11 +695,13 @@ describe('AgentRunnerService', () => {
       }
 
       const budget = runner.getContextBudget();
-      // 10 * 9000 = 90,000 tokens. Context window = 200,000 (anthropic claude-sonnet-4-20250514)
-      // 90000/200000 = 0.45, threshold = 0.8, warning at 0.68
-      // Actually need more tokens. Let me check: the model is claude-sonnet-4-20250514 = 200,000
-      // So we'd need 136,000+ for warning (0.68 * 200000)
-      expect(budget.totalTokensUsed).toBe(90000);
+      // 10 turns × 9,000 billed = 90,000 lifetime tokens, but each individual
+      // prompt was only 9,000 — well under the 200,000 window. The budget must
+      // read the second number: measuring lifetime spend against the window is
+      // what pinned long sessions at 'critical' forever.
+      expect(budget.lifetimeTokensUsed).toBe(90000);
+      expect(budget.contextTokensUsed).toBe(9000);
+      expect(budget.level).toBe('normal');
     });
 
     it('should return critical level when at or above compaction threshold', async () => {
@@ -689,6 +729,43 @@ describe('AgentRunnerService', () => {
       expect(budget.summary).toContain('CRITICAL');
     });
 
+    // Regression: a long session used to settle into a state where EVERY
+    // message ran a compaction before its own request, doubling the model calls
+    // for the rest of the session and never recovering — compaction shrank the
+    // history but nothing reset the counter it was judged against. Reproduced
+    // at an orchestrator's real scale: a ~20k-token prompt on DeepSeek's 64k
+    // window crossed the 0.8 threshold by the third message.
+    it('does not fall into a permanent compact-before-every-message loop', async () => {
+      const config = {
+        ...baseConfig,
+        model: { provider: 'deepseek' as const, modelId: 'deepseek-chat', temperature: 0.3, maxTokens: 8192 },
+        maxHistoryMessages: 100,
+      };
+      const r = new AgentRunnerService(config, mockModelManager, mockApiClient);
+      r._generateTextFn = mockGenerateText;
+      await r.initialize();
+
+      mockGenerateText.mockResolvedValue({
+        text: 'ok',
+        steps: [],
+        usage: { inputTokens: 20_000, outputTokens: 300 },
+        finishReason: 'stop',
+      });
+
+      const TURNS = 12;
+      for (let i = 0; i < TURNS; i++) {
+        await r.run(`message ${i}`);
+      }
+
+      // One call per turn. A compaction would add a summarization call on top,
+      // so a count above TURNS means the loop is back.
+      expect(mockGenerateText).toHaveBeenCalledTimes(TURNS);
+      const budget = r.getContextBudget();
+      expect(budget.level).toBe('normal');
+      // The old formula reported ~380% here.
+      expect(budget.usagePercent).toBeLessThan(1);
+    });
+
     it('should set compactionPending when message count exceeds max', async () => {
       const config = {
         ...baseConfig,
@@ -824,22 +901,15 @@ describe('AgentRunnerService', () => {
       // Each run uses 150 tokens. After 6 runs: 900 tokens.
       // Context window for claude-sonnet-4-20250514 = 200,000
       // Set threshold to 0.004 (0.4%) = 800 tokens
-      // Runs 0-3 won't trigger (0,150,300,450 < 800). Run 4+ will trigger.
-      // But compaction needs >= 10 messages, so runs 4-5 trigger budget-critical
-      // but compactHistory returns early (8 and 10 messages respectively).
-      // Actually run 5 has 10 messages so compaction runs.
-      // Let's use threshold 0.005 = 1000 tokens, so 6 runs of 150 = 900 < 1000.
-      // Then the 7th run triggers at 900 + check >= 1000? No, budget is checked
-      // before the run with existing tokens. After 6 runs = 900 tokens < 1000 = normal.
-      // After 7th run = 900 + 150 = 1050. But check is before run with 900 tokens.
-      // We need threshold to trigger BEFORE a run. So set threshold = 0.004 = 800.
-      // After 5 runs = 750 < 800 (normal). After 6th run's execution → 900.
-      // 7th run check: 900/200000 = 0.0045 >= 0.004 → critical → compaction triggers.
-      // At that point we have 12 messages (6 runs × 2), >= 10, so compaction runs.
+      // Compaction must stay reachable on token pressure alone, with a message
+      // count nowhere near `maxHistoryMessages`. Pressure now comes from one
+      // large prompt rather than from many small ones adding up: occupancy is
+      // measured per request, so a long-but-light session no longer reads as
+      // full. Threshold 0.004 of a 200,000 window = 800 tokens.
       const config = {
         ...baseConfig,
         maxHistoryMessages: 1000, // high message limit, won't trigger by count
-        compactionThreshold: 0.004, // triggers after ~6 runs of 150 tokens each
+        compactionThreshold: 0.004,
       };
       const r = new AgentRunnerService(config, mockModelManager, mockApiClient);
       r._generateTextFn = mockGenerateText;
@@ -857,11 +927,22 @@ describe('AgentRunnerService', () => {
       }
 
       expect(r.getHistoryLength()).toBe(12);
-      // 900 / 200000 = 0.0045 >= 0.004 → critical
+      expect(r.getContextBudget().level).toBe('normal');
+
+      // A turn that actually fills the context — 950 tokens against an 800
+      // token threshold.
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'Big context turn',
+        steps: [],
+        usage: { inputTokens: 900, outputTokens: 50 },
+        finishReason: 'stop',
+      });
+      await r.run('Message with a large prompt');
+
       expect(r.getContextBudget().level).toBe('critical');
 
-      // Next run should trigger compaction due to token budget being critical
-      // AI summary call + actual run
+      // The next run sees a critical budget and compacts first:
+      // one summarization call, then the run itself.
       mockGenerateText.mockResolvedValueOnce({
         text: 'Compaction summary of state',
         steps: [],
@@ -878,12 +959,75 @@ describe('AgentRunnerService', () => {
       await r.run('Trigger compaction by budget');
 
       // Should have compacted: 1 summary + 10 recent + 1 user + 1 assistant
-      expect(r.getHistoryLength()).toBeLessThan(14);
+      expect(r.getHistoryLength()).toBeLessThan(16);
       const state = r.getState();
       expect(String(state.messages[0].content)).toContain('Compacted State');
     });
   });
 
+  // Prompt caching — the fixed prefix (system prompt + tool schemas) is
+  // byte-stable for the life of a session and was billed at full rate on every
+  // turn because no provider options were ever sent.
+  describe('prompt caching', () => {
+    const lastCallArgs = () =>
+      mockGenerateText.mock.calls[mockGenerateText.mock.calls.length - 1][0];
+
+    it('asks Anthropic to cache the request prefix', async () => {
+      await runner.initialize();
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'ok', steps: [], usage: { inputTokens: 10, outputTokens: 5 }, finishReason: 'stop',
+      });
+      await runner.run('Hello');
+
+      expect(lastCallArgs().providerOptions).toEqual({
+        anthropic: { cacheControl: { type: 'ephemeral' } },
+      });
+    });
+
+    it('sends no provider options for a non-Anthropic model', async () => {
+      // DeepSeek caches server-side with no opt-in and the others have no
+      // equivalent knob; an Anthropic-namespaced option there is just noise.
+      const config = {
+        ...baseConfig,
+        model: { provider: 'deepseek' as const, modelId: 'deepseek-chat', temperature: 0.3, maxTokens: 8192 },
+      };
+      const r = new AgentRunnerService(config, mockModelManager, mockApiClient);
+      r._generateTextFn = mockGenerateText;
+      await r.initialize();
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'ok', steps: [], usage: { inputTokens: 10, outputTokens: 5 }, finishReason: 'stop',
+      });
+      await r.run('Hello');
+
+      expect(lastCallArgs().providerOptions).toBeUndefined();
+    });
+
+    it('reports cache hits on the run result so the hit rate is observable', async () => {
+      await runner.initialize();
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'ok',
+        steps: [],
+        usage: { inputTokens: 400, outputTokens: 60, cachedInputTokens: 18_000 },
+        finishReason: 'stop',
+      });
+
+      const result = await runner.run('Hello');
+
+      expect(result.usage).toEqual({ input: 400, output: 60, cachedInput: 18_000 });
+    });
+
+    it('reports zero cache hits when the provider omits the field', async () => {
+      await runner.initialize();
+      mockGenerateText.mockResolvedValueOnce({
+        text: 'ok', steps: [], usage: { inputTokens: 400, outputTokens: 60 }, finishReason: 'stop',
+      });
+
+      const result = await runner.run('Hello');
+
+      expect(result.usage.cachedInput).toBe(0);
+    });
+  });
+
   describe('audit trail', () => {
     it('should return empty audit log initially', () => {
       const log = runner.getAuditLog();

package/packages/crewly-agent/src/runtime/agent-runner.service.ts

@@ -306,6 +306,7 @@ export class AgentRunnerService {
         messages: [],
         systemPrompt: this.effectiveSystemPrompt,
         totalTokens: { input: 0, output: 0 },
+        lastContextTokens: 0,
         createdAt: new Date(),
         lastActivityAt: new Date(),
       };
@@ -699,11 +700,19 @@ export class AgentRunnerService {
    * @returns ContextBudgetStatus with usage stats and level
    */
   getContextBudget(): ContextBudgetStatus {
-    const totalTokensUsed = this.state.totalTokens.input + this.state.totalTokens.output;
+    const lifetimeTokensUsed = this.state.totalTokens.input + this.state.totalTokens.output;
+    // Occupancy, NOT lifetime spend. The prompt is re-sent in full on every
+    // request, so the lifetime sum counts the same history once per turn and
+    // sails past the window within a handful of messages — which used to pin
+    // `level` at 'critical' forever and run a compaction before every single
+    // message, doubling the model calls for the rest of the session.
+    const contextTokensUsed = this.state.lastContextTokens > 0
+      ? this.state.lastContextTokens
+      : this.estimateContextTokens();
     const contextWindowSize = MODEL_CONTEXT_WINDOWS[this.config.model.modelId]
       ?? MODEL_CONTEXT_WINDOWS.default;
     const usagePercent = contextWindowSize > 0
-      ? totalTokensUsed / contextWindowSize
+      ? contextTokensUsed / contextWindowSize
       : 0;
 
     const threshold = this.config.compactionThreshold;
@@ -719,7 +728,7 @@ export class AgentRunnerService {
       || usagePercent >= threshold;
 
     const pct = (usagePercent * 100).toFixed(1);
-    let summary = `${pct}% of context budget used (${totalTokensUsed.toLocaleString()}/${contextWindowSize.toLocaleString()} tokens, ${this.state.messages.length} messages)`;
+    let summary = `${pct}% of context budget used (${contextTokensUsed.toLocaleString()}/${contextWindowSize.toLocaleString()} tokens, ${this.state.messages.length} messages, ${lifetimeTokensUsed.toLocaleString()} billed this session)`;
     if (level === 'critical') {
       summary += ' — CRITICAL: compaction recommended immediately';
     } else if (level === 'warning') {
@@ -727,7 +736,8 @@ export class AgentRunnerService {
     }
 
     return {
-      totalTokensUsed,
+      contextTokensUsed,
+      lifetimeTokensUsed,
       contextWindowSize,
       usagePercent,
       level,
@@ -737,6 +747,91 @@ export class AgentRunnerService {
     };
   }
 
+  /**
+   * Provider-specific request options.
+   *
+   * Turns on Anthropic prompt caching. Every request re-sends the same
+   * prefix — the system prompt (tens of KB for an orchestrator) followed by
+   * the tool schemas — and that prefix is byte-stable for the life of the
+   * session, which is exactly the shape caching is for. Without this the
+   * whole prefix is billed at full rate on every single turn.
+   *
+   * The top-level `cacheControl` places the breakpoint at the last cacheable
+   * block, so tools + system + settled history are covered by one marker and
+   * only the newest turn is uncached.
+   *
+   * Anthropic-only by design: DeepSeek caches server-side with no opt-in, and
+   * the other providers ignore an option namespaced to a provider that is not
+   * theirs — but sending it only where it means something keeps the request
+   * honest.
+   *
+   * @returns Provider options for the current model, or undefined when the
+   *          provider needs none
+   */
+  private buildProviderOptions(): Record<string, Record<string, unknown>> | undefined {
+    if (this.config.model.provider !== 'anthropic') return undefined;
+    return { anthropic: { cacheControl: { type: 'ephemeral' } } };
+  }
+
+  /**
+   * Record how full the context is after a completed request.
+   *
+   * The prompt the provider just billed IS the context size — `input` covers
+   * the system prompt, the tool schemas and the retained history, and
+   * `cachedInput` covers the part of that same prompt served from cache
+   * (billed cheaper, but still occupying the window, so it must be added
+   * back). The reply is included because the next request carries it forward.
+   *
+   * Assigns rather than accumulates: this is a snapshot of the current turn,
+   * and compaction shrinks it back down on the next measurement.
+   *
+   * @param usage - Token counts reported by the provider for the request
+   */
+  private recordContextOccupancy(
+    usage: { input: number; output: number; cachedInput: number },
+  ): void {
+    this.state.lastContextTokens = usage.input + usage.cachedInput + usage.output;
+  }
+
+  /**
+   * Estimate context occupancy from the text we are about to send.
+   *
+   * Only used before the first response of a conversation, when no provider
+   * measurement exists yet. A rough number is fine there — one turn later it
+   * is replaced by the provider's own count — but it must not be wildly low,
+   * because a 40KB system prompt already fills a meaningful slice of a small
+   * window before any history exists.
+   *
+   * CJK and Latin text are counted separately: a single chars-per-token ratio
+   * misjudges a Chinese prompt by more than 2x in whichever direction it is
+   * tuned for. Tool schemas are not included — they are unavailable here and
+   * the estimate is superseded immediately.
+   *
+   * @returns Estimated tokens currently occupying the context window
+   */
+  private estimateContextTokens(): number {
+    let text = this.state.systemPrompt ?? '';
+    for (const m of this.state.messages) {
+      text += typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+    }
+    let cjk = 0;
+    for (const ch of text) {
+      const code = ch.codePointAt(0) ?? 0;
+      // CJK ideographs, kana, Hangul, and full-width forms.
+      if ((code >= 0x3040 && code <= 0x9fff)
+        || (code >= 0xac00 && code <= 0xd7af)
+        || (code >= 0xf900 && code <= 0xfaff)
+        || (code >= 0xff00 && code <= 0xffef)) {
+        cjk++;
+      }
+    }
+    const latin = [...text].length - cjk;
+    return Math.ceil(
+      latin / CREWLY_AGENT_DEFAULTS.CHARS_PER_TOKEN_LATIN
+      + cjk / CREWLY_AGENT_DEFAULTS.CHARS_PER_TOKEN_CJK,
+    );
+  }
+
   /**
    * Process queued messages serially.
    */
@@ -1049,6 +1144,7 @@ export class AgentRunnerService {
       model: this.model!,
       system: this.state.systemPrompt,
       messages: this.state.messages,
+      providerOptions: this.buildProviderOptions(),
       tools: tools as any,
       stopWhen: stepCountIs(this.config.maxSteps),
       temperature: this.config.model.temperature,
@@ -1161,9 +1257,11 @@ export class AgentRunnerService {
       const usage = {
         input: resultUsage?.inputTokens ?? 0,
         output: resultUsage?.outputTokens ?? 0,
+        cachedInput: resultUsage?.cachedInputTokens ?? 0,
       };
       this.state.totalTokens.input += usage.input;
       this.state.totalTokens.output += usage.output;
+      this.recordContextOccupancy(usage);
 
       // Check budget after token update
       const postBudget = this.getContextBudget();
@@ -1277,6 +1375,7 @@ export class AgentRunnerService {
       model: this.model,
       system: this.state.systemPrompt,
       messages: this.state.messages,
+      providerOptions: this.buildProviderOptions(),
       tools,
       stopWhen: stepCountIs(this.config.maxSteps),
       temperature: this.config.model.temperature,
@@ -1345,9 +1444,11 @@ export class AgentRunnerService {
     const usage = {
       input: result.usage?.inputTokens ?? 0,
       output: result.usage?.outputTokens ?? 0,
+      cachedInput: result.usage?.cachedInputTokens ?? 0,
     };
     this.state.totalTokens.input += usage.input;
     this.state.totalTokens.output += usage.output;
+    this.recordContextOccupancy(usage);
 
     // Check budget after token update and attach warning if approaching limits
     const postBudget = this.getContextBudget();
@@ -1492,6 +1593,7 @@ export class AgentRunnerService {
         model: this.model,
         system: this.state.systemPrompt,
         messages: this.state.messages,
+        providerOptions: this.buildProviderOptions(),
         tools: tools as any,
         stopWhen: stepCountIs(20), // Limited steps for follow-up
         temperature: this.config.model.temperature,
@@ -1503,7 +1605,7 @@ export class AgentRunnerService {
       const followUpResult = followUp as unknown as Record<string, unknown>;
       const steps = (followUpResult.steps as Array<Record<string, unknown>>) ?? [];
       const text = (followUpResult.text as string) ?? '';
-      const followUpUsage = followUpResult.usage as { inputTokens?: number; outputTokens?: number } | undefined;
+      const followUpUsage = followUpResult.usage as { inputTokens?: number; outputTokens?: number; cachedInputTokens?: number } | undefined;
       const finishReason = (followUpResult.finishReason as string) ?? 'stop';
 
       const followUpToolCalls: ToolCallRecord[] = [];
@@ -1520,10 +1622,16 @@ export class AgentRunnerService {
         this.state.messages.push({ role: 'assistant', content: text });
       }
 
-      // Track follow-up token usage
+      // Track follow-up token usage. This is a later request in the same run,
+      // so its prompt is the most current picture of how full the context is.
       if (followUpUsage) {
         this.state.totalTokens.input += followUpUsage.inputTokens ?? 0;
         this.state.totalTokens.output += followUpUsage.outputTokens ?? 0;
+        this.recordContextOccupancy({
+          input: followUpUsage.inputTokens ?? 0,
+          output: followUpUsage.outputTokens ?? 0,
+          cachedInput: followUpUsage.cachedInputTokens ?? 0,
+        });
       }
 
       return {
@@ -1532,6 +1640,7 @@ export class AgentRunnerService {
         usage: {
           input: followUpUsage?.inputTokens ?? 0,
           output: followUpUsage?.outputTokens ?? 0,
+          cachedInput: followUpUsage?.cachedInputTokens ?? 0,
         },
         toolCalls: followUpToolCalls,
         finishReason,
@@ -1564,6 +1673,7 @@ export class AgentRunnerService {
         model: this.model,
         system: this.state.systemPrompt,
         messages: this.state.messages,
+        providerOptions: this.buildProviderOptions(),
         maxOutputTokens: resolveMaxOutputTokens(this.config.model),
         temperature: this.config.model.temperature,
       });
@@ -1578,6 +1688,11 @@ export class AgentRunnerService {
         if (fallbackUsage) {
           this.state.totalTokens.input += fallbackUsage.inputTokens ?? 0;
           this.state.totalTokens.output += fallbackUsage.outputTokens ?? 0;
+          this.recordContextOccupancy({
+            input: fallbackUsage.inputTokens ?? 0,
+            output: fallbackUsage.outputTokens ?? 0,
+            cachedInput: fallbackUsage.cachedInputTokens ?? 0,
+          });
         }
       }
 

package/packages/crewly-agent/src/runtime/types.ts

@@ -105,6 +105,20 @@ export interface ConversationState {
   systemPrompt: string;
   /** Cumulative token usage across all generateText calls */
   totalTokens: { input: number; output: number };
+  /**
+   * Tokens occupying the model's context as of the most recent request:
+   * the prompt that was actually sent (system + tools + retained history,
+   * cache hits included) plus the reply it produced, which the next request
+   * carries forward.
+   *
+   * This is a MEASUREMENT, not a running total — it is assigned, never
+   * accumulated. `totalTokens` answers "what has this session cost?";
+   * this answers "how full is the context?". Using the former for the
+   * latter conflates lifetime spend with occupancy and climbs past 100%
+   * of the window after a few turns, pinning the runner in permanent
+   * compaction. 0 until the first response lands.
+   */
+  lastContextTokens: number;
   /** Conversation creation time */
   createdAt: Date;
   /** Last activity timestamp */
@@ -156,8 +170,13 @@ export interface AgentRunResult {
   text: string;
   /** Number of steps taken in this run */
   steps: number;
-  /** Token usage for this run */
-  usage: { input: number; output: number };
+  /**
+   * Token usage for this run. `cachedInput` is the portion of `input` the
+   * provider served from its prompt cache — the number to watch when
+   * verifying caching actually engaged. It is 0 on providers that do not
+   * report cache hits.
+   */
+  usage: { input: number; output: number; cachedInput: number };
   /** Tool calls made during this run */
   toolCalls: ToolCallRecord[];
   /** Reason the generation finished */
@@ -322,8 +341,19 @@ export const WRITE_TOOLS: readonly string[] = [
  * Tracks token usage against the model's context window limit.
  */
 export interface ContextBudgetStatus {
-  /** Total tokens used so far (input + output) */
-  totalTokensUsed: number;
+  /**
+   * Tokens occupying the context window right now — measured from the last
+   * request, or estimated from the system prompt + history before the first
+   * one. This is the numerator of `usagePercent`.
+   */
+  contextTokensUsed: number;
+  /**
+   * Lifetime tokens billed for this session (input + output across every
+   * request). Reported for cost visibility only — it must never be compared
+   * against the context window, since re-sent history is counted once per
+   * request and the sum exceeds the window long before the context is full.
+   */
+  lifetimeTokensUsed: number;
   /** Estimated context window size for the current model */
   contextWindowSize: number;
   /** Usage as a fraction (0.0 - 1.0) */
@@ -343,7 +373,20 @@ export interface ContextBudgetStatus {
  * Used for budget tracking when the model doesn't report its own limit.
  */
 export const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
-  // Anthropic
+  // Anthropic — current generation. These were missing, so every model the
+  // fleet actually runs fell through to `default: 128_000` while its real
+  // window is 1M. An 8x under-estimate makes `compactionThreshold` fire
+  // roughly 8x too early, which is expensive: each premature compaction is a
+  // whole extra model call.
+  'claude-fable-5': 1_000_000,
+  'claude-opus-5': 1_000_000,
+  'claude-opus-4-8': 1_000_000,
+  'claude-opus-4-7': 1_000_000,
+  'claude-opus-4-6': 1_000_000,
+  'claude-sonnet-5': 1_000_000,
+  'claude-sonnet-4-6': 1_000_000,
+  'claude-haiku-4-5': 200_000,
+  // Anthropic — older dated snapshots, kept so pinned configs still resolve.
   'claude-opus-4-20250514': 200_000,
   'claude-sonnet-4-20250514': 200_000,
   'claude-haiku-4-20250506': 200_000,
@@ -493,6 +536,14 @@ export const CREWLY_AGENT_DEFAULTS = {
   MAX_HISTORY_MESSAGES: 100,
   /** Default compaction threshold (80% of context window) */
   COMPACTION_THRESHOLD: 0.8,
+  /**
+   * Characters per token, used ONLY to size the context before the first
+   * response gives us a real measurement. Latin text runs about 4 chars per
+   * token; CJK about 1.5, so the two are counted separately — a single ratio
+   * would misjudge a Chinese system prompt by more than 2x.
+   */
+  CHARS_PER_TOKEN_LATIN: 4,
+  CHARS_PER_TOKEN_CJK: 1.5,
   /** Default model configuration */
   DEFAULT_MODEL: {
     provider: 'google' as ModelProvider,

package/dist/backend/backend/src/controllers/knowledge/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * Knowledge controller barrel export.
- *
- * @module controllers/knowledge
- */
-export { createKnowledgeRouter } from './knowledge.routes.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/backend/backend/src/controllers/knowledge/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/controllers/knowledge/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/backend/backend/src/controllers/knowledge/index.js

@@ -1,7 +0,0 @@
-/**
- * Knowledge controller barrel export.
- *
- * @module controllers/knowledge
- */
-export { createKnowledgeRouter } from './knowledge.routes.js';
-//# sourceMappingURL=index.js.map

package/dist/backend/backend/src/controllers/knowledge/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../backend/src/controllers/knowledge/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}