feat: per-model max output tokens and a conversation-time thinking level backed by agent settings (#28)

Co-authored-by: Alice <alice@prismshadow.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

packages/server/src/api/types.ts

@@ -206,6 +206,13 @@ export interface ModelInfo {
    * unset (= treated as supported).
    */
   vision?: boolean;
+  /**
+   * Per-model max output tokens (TOML `max_tokens` annotation; user-only, never preset by the
+   * built-in catalog): when set it wins over the Agent's `system_config.model.max_tokens`;
+   * unset = inherit the Agent value. Lets a small-context model cap its output below the
+   * seeded per-Agent default (32000), which cannot fit into e.g. a 32k context window.
+   */
+  maxTokens?: number;
   pricing?: ModelPricingDto;
   /** Environment variable name to fall back to when api_key is empty (e.g. ANTHROPIC_API_KEY); unset if no known fallback. */
   envKey?: string;
@@ -241,6 +248,8 @@ export interface ModelUpdateEntry {
   clientType?: string;
   /** Whether image input (vision/multimodal) is supported; omitted = supported (not persisted). */
   vision?: boolean;
+  /** Per-model max output tokens, a positive integer (wins over the Agent config); omitted = inherit the Agent value (the annotation is cleared). */
+  maxTokens?: number;
   pricing?: ModelPricingDto;
   /** Providing it overwrites and updates createdAt; omitting it keeps the existing value. */
   apiKey?: string;

packages/server/src/http/routes/models.ts

@@ -76,6 +76,12 @@ function parseModelsUpdate(body: Record<string, unknown>): ModelsUpdateRequest {
       }
       entry.vision = m.vision;
     }
+    if (m.maxTokens !== undefined) {
+      if (typeof m.maxTokens !== "number" || !Number.isInteger(m.maxTokens) || m.maxTokens <= 0) {
+        throw badRequest(`models[${i}].maxTokens must be a positive integer.`);
+      }
+      entry.maxTokens = m.maxTokens;
+    }
     if (m.pricing !== undefined) {
       const p = m.pricing as Record<string, unknown>;
       if (p === null || typeof p !== "object" || Array.isArray(p)) {

packages/server/src/services/project-config-service.ts

@@ -350,6 +350,8 @@ export class ProjectConfigService {
         // routed has no fallback (no envKey, and AgentHub will reject that id).
         const envKey = resolveModelEnv(modelId, clientType)?.envKey;
         const vision = typeof m.vision === "boolean" ? m.vision : cat?.supportsVision;
+        // Output cap: TOML annotation only (user-owned; the built-in catalog never presets it).
+        const maxTokens = optNum(m.max_tokens);
         // Display name: the explicit TOML field (user-edited) takes priority, then the built-in catalog.
         const displayName = optStr(m.display_name) ?? cat?.displayName;
         // credential is inlined on the entry: a credential block is emitted if either api_key or base_url is present.
@@ -369,6 +371,7 @@ export class ProjectConfigService {
             : {}),
           ...(clientType ? { clientType } : {}),
           ...(vision !== undefined ? { vision } : {}),
+          ...(maxTokens !== undefined ? { maxTokens } : {}),
           ...(envKey ? { envKey } : {}),
           ...(pricingDto ? { pricing: pricingDto } : {}),
           ...(apiKey !== undefined || credBaseUrl !== undefined
@@ -443,6 +446,7 @@ export class ProjectConfigService {
       delete next.context_window;
       delete next.client_type;
       delete next.vision;
+      delete next.max_tokens;
       delete next.pricing;
       delete next.display_name;
       // Leftover key from the old concatenated format (request_model_id): defensively stripped, never written to disk again.
@@ -460,6 +464,8 @@ export class ProjectConfigService {
       if (entry.clientType) next.client_type = entry.clientType;
       // Treated as supported by default: only written to disk when explicitly annotated (both true/false are kept; false drives a frontend blocking hint).
       if (entry.vision !== undefined) next.vision = entry.vision;
+      // Inherit-the-Agent-value by default: only written to disk when explicitly annotated (omitted on a full-table PUT = the annotation is cleared).
+      if (entry.maxTokens !== undefined) next.max_tokens = entry.maxTokens;
       if (entry.pricing !== undefined) {
         next.pricing = {
           unit: "usd_per_mtok",