fix(llm): stop sending stage OUTPUT_RATIO as max_tokens

Each LLM stage was passing floor(input_tokens * OUTPUT_RATIO) as the chat completions max_tokens, hard-capping clean output server-side (e.g. CLEAN_OUTPUT_RATIO=0.5 truncated clean output at half input). OUTPUT_RATIO now only reserves output budget for context-window eligibility, as documented.

Author: sousekd

.env.example

@@ -66,7 +66,7 @@ CLEAN_ENABLED=true
 CLEAN_MIN_INPUT_CHARS=500
 # Hard cap on clean input size. 0 means no cap.
 CLEAN_MAX_INPUT_CHARS=75000
-# Output token budget as a fraction of input tokens.
+# Output token budget reserved as a fraction of input tokens for context-window eligibility.
 CLEAN_OUTPUT_RATIO=0.5
 # Per-call timeout in seconds.
 CLEAN_TIMEOUT_SECONDS=60
@@ -82,7 +82,7 @@ SUMMARIZE_ENABLED=false
 SUMMARIZE_MIN_INPUT_CHARS=25000
 # Hard cap on summarize input size. 0 means no cap.
 SUMMARIZE_MAX_INPUT_CHARS=0
-# Output token budget as a fraction of input tokens.
+# Output token budget reserved as a fraction of input tokens for context-window eligibility.
 SUMMARIZE_OUTPUT_RATIO=0.15
 # Per-call timeout in seconds.
 SUMMARIZE_TIMEOUT_SECONDS=60

AGENTS.md

@@ -106,8 +106,7 @@ The LLM provider should work with local OpenAI-compatible servers such as llama.
   "messages": [
     {"role": "system", "content": "..."},
     {"role": "user", "content": "..."}
-  ],
-  "max_tokens": 8192
+  ]
 }
 ```
 

README.md

@@ -235,15 +235,13 @@ The tables below list only the **commonly tuned** keys. Open `.env.example` for
 | `LLM_CONCURRENCY` | `1`                               | Max concurrent per-URL LLM workflows.                   |
 | `LLM_EXTRA_BODY`  | empty                             | Example: `{"temperature":0.7, ...}`. Any key wins.      |
 
-LLM calls intentionally use the lowest common denominator: Chat Completions, `system` and `user` messages only, and `max_tokens` derived from the stage output ratio. No sampler defaults are sent; operators set them through `LLM_EXTRA_BODY` when needed. No Responses API. No `developer` role. This keeps the provider usable with llama.cpp, vLLM, SGLang, and similar local servers.
-
 ### Stages
 
-| Variable                | Default | Notes                                                                                              |
-| ----------------------- | ------- | -------------------------------------------------------------------------------------------------- |
-| `CLEAN_ENABLED`         | `true`  | Enables the clean stage.                                                                           |
-| `SUMMARIZE_ENABLED`     | `false` | Enables the summarize stage.                                                                       |
-| `TRUNCATE_TARGET_CHARS` | `25000` | Final body cap before footer is appended. `0` disables truncation.                                 |
+| Variable                | Default | Notes                                                                 |
+| ----------------------- | ------- | ----------------------------------------------------------------------|
+| `CLEAN_ENABLED`         | `true`  | Enables the clean stage.                                              |
+| `SUMMARIZE_ENABLED`     | `false` | Enables the summarize stage.                                          |
+| `TRUNCATE_TARGET_CHARS` | `25000` | Final body cap before footer is appended. `0` disables truncation.    |
 
 Each stage exposes the same knobs under a shared naming convention: `<STAGE>_ENABLED`, `<STAGE>_MIN_INPUT_CHARS`, `<STAGE>_MAX_INPUT_CHARS`, `<STAGE>_OUTPUT_RATIO`, `<STAGE>_TIMEOUT_SECONDS`, `<STAGE>_QUALITY_MIN_RATIO`, `<STAGE>_CHECK_URLS`. See `.env.example` for the full list and per-stage defaults.
 

src/config/config.ts

@@ -149,7 +149,7 @@ const EnvSchema = z.object({
   // Units: characters. Range: integer >= 0; 0 means no limit. Default: 75000.
   CLEAN_MAX_INPUT_CHARS: intish(75000).pipe(z.number().int().min(0)),
 
-  // Output token budget ratio used for clean stage max_tokens and eligibility.
+  // Output token budget ratio reserved for the clean stage in context-window eligibility projection.
   // Units: ratio. Range: number >= 0. Default: 0.5.
   CLEAN_OUTPUT_RATIO: numberish(0.5).pipe(z.number().min(0)),
 
@@ -177,7 +177,7 @@ const EnvSchema = z.object({
   // Units: characters. Range: integer >= 0; 0 means no limit. Default: 0.
   SUMMARIZE_MAX_INPUT_CHARS: intish(0).pipe(z.number().int().min(0)),
 
-  // Output token budget ratio used for summarize-stage max_tokens and eligibility.
+  // Output token budget ratio reserved for the summarize stage in context-window eligibility projection.
   // Units: ratio. Range: number >= 0. Default: 0.15.
   SUMMARIZE_OUTPUT_RATIO: numberish(0.15).pipe(z.number().min(0)),
 

src/core/ports/llm-provider.ts

@@ -10,10 +10,7 @@ export interface LlmMessage {
 }
 
 export interface LlmChatOptions {
-  /** Max output tokens budget for the request. */
-  maxTokens?: number;
-
-  /** Request timeout in milliseconds. */
+  /** Request timeout in milliseconds. Hard `max_tokens` caps belong in `LLM_EXTRA_BODY`. */
   timeoutMs?: number;
 }
 

src/core/use-cases/llm-stage/llm-stage.ts

@@ -4,7 +4,7 @@ import type { QualityRejectReason } from "../../cleanup/quality-gate.js";
 import type { TemplateRenderer } from "../../cleanup/templates.js";
 import type { LlmProvider } from "../../ports/llm-provider.js";
 
-import { checkEligibility, compactChars, estimateTokens } from "../../cleanup/length-policy.js";
+import { checkEligibility, compactChars } from "../../cleanup/length-policy.js";
 import { assessQuality } from "../../cleanup/quality-gate.js";
 import { reasonFromError } from "../../util/errors.js";
 
@@ -120,9 +120,6 @@ export class LlmStage {
       };
     }
 
-    const inputTokens = estimateTokens(inputChars, this.deps.app.LLM_CHARS_PER_TOKEN);
-    const maxTokens = Math.max(1, Math.floor(inputTokens * config.outputRatio));
-
     let text: string;
     let model: string | undefined;
     try {
@@ -132,7 +129,6 @@ export class LlmStage {
           { role: "user", content: userPrompt }
         ],
         {
-          maxTokens,
           timeoutMs: config.timeoutMs
         }
       );

src/providers/llm/openai-chat/openai-chat-llm.ts

@@ -13,7 +13,6 @@ import { joinUrl } from "../../../core/util/urls.js";
 // Handles untrusted external content at the response parsing security boundary.
 
 const DEFAULT_TIMEOUT_MS = 60_000;
-const DEFAULT_MAX_TOKENS = 4096;
 
 /** Slugify upstream error codes before interpolating them in AppError codes. */
 function sanitizeUpstreamCode(value: unknown): string {
@@ -57,7 +56,6 @@ export class OpenAiChatLlmProvider implements LlmProvider {
   /** Execute one chat request and return normalized model text output. */
   async chat(messages: LlmMessage[], options: LlmChatOptions = {}): Promise<LlmChatResult> {
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
 
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -71,7 +69,6 @@ export class OpenAiChatLlmProvider implements LlmProvider {
       const body = {
         model: this.config.LLM_MODEL,
         messages,
-        max_tokens: maxTokens,
         ...this.config.LLM_EXTRA_BODY
       };