aegis-desktop 0.5.3 → 0.5.4

package/lib/local/engine.js

@@ -47,6 +47,28 @@ const toolsModule = require('./tools.js');
 const promptModule = require('./prompt.js');
 const { ShellSession } = require('./shell.js');
 const { agentSystemPrompt, agentRoleLabel } = require('./agents.js');
+// Cooperative working-tree sharing (see each module's header). The lock
+// serialises two hosts that start a turn on one checkout close together; the
+// guard is the load-bearing half — it refuses a tree-wide git operation while
+// another session's uncommitted work is present, which is the operation that
+// destroyed a peer's file for real. Both live beside the engine because the
+// CLI vendors this directory wholesale (cli/scripts/predist.mjs), so the GUI
+// and the terminal get one implementation rather than two that drift.
+const { beginTurnGuard, recordWrite, blocksDestructive } = require('./turn-guard.js');
+const { acquireWorktreeLock, releaseWorktreeLock } = require('./worktree-lock.js');
+
+/**
+ * How long a turn waits for the working-tree lock before running anyway.
+ *
+ * Short on purpose. This engine serves interactive hosts — a desktop window
+ * and a terminal — where stalling for the lock's own 11-minute default would
+ * be a worse failure than contending: the user is watching a spinner. So the
+ * lock is best-effort mutual exclusion for turns that start near-simultaneously
+ * (the common overlap), and the turn guard covers everything after that. A
+ * non-interactive caller that can afford to queue should pass
+ * `payload.worktreeWaitMs` with the long DEFAULT_WORKTREE_WAIT_MS instead.
+ */
+const WORKTREE_LOCK_WAIT_MS = 1500;
 
 /** Classes whose transport is a user-supplied endpoint + credential. */
 const CUSTOM_CLASSES = Object.freeze(['openai-compat', 'anthropic']);
@@ -70,22 +92,30 @@ const CLASSES = [
 /**
  * Mirrors aegiscodex-dev's src/backend.js DEEPSEEK_REASONING_MODEL_RE +
  * EFFORT_TOKEN_BUDGET verbatim. DeepSeek's reasoning models (deepseek-flash,
- * deepseek-v4-pro, the deprecated deepseek-reasoner, and the legacy
- * v4-flash/v4.1-flash aliases some configs still carry) spend part of
- * max_tokens on hidden chain-of-thought before ever emitting visible
- * content — DeepSeek counts reasoning tokens against the same budget as
- * content. At the renderer's 4k default (index.html's max-tokens select),
- * any non-trivial question can burn the whole budget reasoning and finish
- * with empty content: no error, no tool calls, just a turn that "completes"
- * with nothing to show for it (the empty-response bug). A user pointing the
- * Custom OpenAI-compatible class straight at DeepSeek's API hits exactly
- * this, so the request floors to the same effort budget aegiscodex-dev uses
- * for its own direct DeepSeek calls instead of shipping whatever the
- * dropdown happens to have selected.
+ * i.e. "Flash 4.1", deepseek-v4-pro, the deprecated deepseek-reasoner, and the
+ * legacy v4-flash/v4.1-flash aliases some configs still carry) spend part of
+ * the budget on hidden chain-of-thought before ever emitting visible content —
+ * DeepSeek counts reasoning tokens against the same budget as content. Under
+ * the renderer's removed 4k dropdown default, any non-trivial question could
+ * burn the whole budget reasoning and finish with empty content: no error, no
+ * tool calls, just a turn that "completes" with nothing to show for it (the
+ * empty-response bug). A user pointing the Custom OpenAI-compatible class
+ * straight at DeepSeek's API hits exactly this, so the request is sized by the
+ * same effort budget aegiscodex-dev uses for its own direct DeepSeek calls.
+ *
+ * desktop/renderer/budget.js carries the renderer's copy of these two
+ * constants plus budgetFor() below; test/budget.test.mjs requires both and
+ * asserts they agree, so the mirror cannot drift silently.
  */
 const DEEPSEEK_REASONING_MODEL_RE = /^deepseek-(v4(\.\d+)?-(flash|pro)|flash|pro|reasoner)$/;
 const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 
+/** The one class whose wire format REQUIRES a stated `max_tokens`: Anthropic's
+ *  Messages API 400s without it, so that field is derived from the effort rung
+ *  rather than invented by the transport (which is what a blanket
+ *  `max_tokens: maxTokens || 4096` did — see providers.anthropicMessages). */
+const REQUIRES_STATED_BUDGET = new Set(['anthropic']);
+
 /**
  * Idle-stream budget for a pooled brain call ("work autonomously"). The
  * generic watchdog in vendor/aegis.js kills a stream that goes 60s without a
@@ -109,38 +139,38 @@ const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 const AUTONOMOUS_IDLE_TIMEOUT_MS = 15 * 60_000;
 
 /**
- * The budget a DeepSeek reasoning model runs on, resolved from EXACTLY ONE
- * authority per call.
- *
- * A caller-stated number IS the budget, and is returned verbatim. For the
- * non-pooled classes the renderer's max-tokens dropdown is the only budget
- * control on offer — updateBudgetControls hides the effort row for them — so
- * silently raising that number to an effort rung is precisely what made the
- * figure beside the dropdown untrustworthy. The old form was
- * `Math.max(stated, EFFORT_TOKEN_BUDGET[eff])`, which could only ever raise a
- * deliberate cap: a caller asking for 1024 ran on 32768, and the number the
- * UI displayed was never the number the call used.
+ * The budget a request travels with, resolved from EXACTLY ONE authority per
+ * call — the engine-side half of the rule desktop/renderer/budget.js mirrors
+ * and test/budget.test.mjs compares the two halves of, so neither can drift.
  *
- * The effort rung is the DEFAULT, consulted only when no number was stated at
- * all (the pooled class, which the renderer sends `effort` for and which the
- * server sizes itself). This is the same rule doubledBudget() follows for its
- * truncation retry: a stated cap is never overridden, by a rung or an order of
- * magnitude.
+ *   1. a caller-stated number IS the budget and is returned verbatim. It is a
+ *      deliberate liability ceiling (aegis1 pass_budgets honours it downward:
+ *      total = min(ladder, max_tokens x passes)) and no rung may raise it — the
+ *      old `Math.max(stated, EFFORT_TOKEN_BUDGET[eff])` form did exactly that,
+ *      so a caller asking for 1024 silently ran on 32768.
+ *   2. with nothing stated, a model that reasons against its own output budget
+ *      (DeepSeek bills hidden chain-of-thought against the SAME budget as the
+ *      answer) or a class whose wire format REQUIRES the field (Anthropic's
+ *      Messages API) gets the Effort rung. This is why the renderer's
+ *      max-tokens dropdown was removed rather than fixed: at its 4k default a
+ *      reasoning model spent the entire budget thinking and finished empty —
+ *      no error, no tool call, just a "completed" turn with nothing in it.
+ *   3. otherwise `undefined` — no `max_tokens` goes on the wire and the
+ *      provider's own output limit governs. The transport used to fill this
+ *      gap with an invented 4096 default, which is the defect in (2).
  *
- * Truncated and empty turns are handled where they belong — the doubled-budget
- * retry plus emptyTurnError — rather than by inflating the caller's ceiling up
- * front. Escalating on a demonstrated empty turn is strictly cheaper than
- * pre-emptively granting the top rung to every reasoning call.
- *
- * Everything else (non-DeepSeek models, non-reasoning DeepSeek ids like
- * deepseek-chat) passes through untouched.
+ * Truncated and empty turns are still handled where they belong — the
+ * doubled-budget retry plus emptyTurnError — rather than by inflating the
+ * caller's ceiling up front.
  */
-function reasoningBudget(model, maxTokens, effort) {
-  if (!DEEPSEEK_REASONING_MODEL_RE.test(String(model || ''))) return maxTokens;
+function reasoningBudget(cls, model, maxTokens, effort) {
   const stated = Number(maxTokens);
   if (Number.isFinite(stated) && stated > 0) return stated;
-  const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
-  return EFFORT_TOKEN_BUDGET[eff];
+  if (DEEPSEEK_REASONING_MODEL_RE.test(String(model || '')) || REQUIRES_STATED_BUDGET.has(cls)) {
+    const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
+    return EFFORT_TOKEN_BUDGET[eff];
+  }
+  return undefined;
 }
 
 /** Relay model entries arrive as ids or objects; keep only real model ids. */
@@ -279,6 +309,33 @@ function doubledBudget(maxTokens) {
   return n > 0 ? n * 2 : 8192;
 }
 
+/**
+ * The cap the CALLER stated, or `undefined` meaning "none was stated".
+ *
+ * The two branches resolve one question — whose number is this? — and the
+ * first is the fix. An internal re-entry (runSubagent's nested chat()) passes
+ * `statedMaxTokens` explicitly, because the `maxTokens` it holds is the rung
+ * reasoningBudget() derived from `effort`: a number the server is about to
+ * derive for itself. Re-reading that value as the caller's own is what put a
+ * guessed 32768 on the wire as a *ceiling over* aegis1's ladder
+ * (pass_budgets: total = min(ladder, max_tokens x passes)) — so a
+ * high-effort subagent silently ran at 8192 and the ladder the UI advertised
+ * was not the budget the call used.
+ *
+ * A non-numeric or non-positive value means "nothing stated" — never a 0- or
+ * NaN-token ceiling.
+ */
+function statedCapOf(payload) {
+  const asCap = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  };
+  if (payload && Object.prototype.hasOwnProperty.call(payload, 'statedMaxTokens')) {
+    return asCap(payload.statedMaxTokens);
+  }
+  return asCap(payload && payload.maxTokens);
+}
+
 /**
  * The follow-up shown to a model that ended its turn with neither text nor a
  * tool call. Sent as a plain user message (never as a tool result — there is
@@ -305,9 +362,9 @@ const EMPTY_TURN_NUDGE =
 function emptyTurnError({ cls, model, maxTokens, finishReason }) {
   const err = new Error(
     `The model returned no answer after ${cls}/${model} was asked to summarise its results ` +
-      `(stop reason: ${finishReason || 'none'}, max_tokens: ${maxTokens}). The token budget ` +
-      'was most likely consumed before any visible text — raise the max-tokens setting, ' +
-      'or lower effort.'
+      `(stop reason: ${finishReason || 'none'}, max_tokens: ${maxTokens || 'unstated'}). The token budget ` +
+      'was most likely consumed before any visible text — raise the Effort rung, which is ' +
+      'what sizes this call, or ask for a smaller piece of work.'
   );
   err.status = 502;
   return err;
@@ -484,11 +541,44 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
    * runs straight through exactly like a session-allowed one, so "don't ask"
    * is one switch rather than a per-tool blanket allow in every conversation.
    */
+  /**
+   * The single place a tool executor is called from the chat loop, so the
+   * turn guard cannot be bypassed by reaching a different branch (there are
+   * four `return`s in gatedExecuteTool below; all of them come through here).
+   *
+   * exec is *checked* before running and writeFile/editFile are *recorded*
+   * after, and the asymmetry is the point: a refusal has to happen before the
+   * command runs, while "this path is mine" is only true once the write
+   * actually happened — recording a denied or preview-failed write would hide
+   * a genuinely foreign file behind a claim of ownership.
+   *
+   * A refusal is returned as an ordinary tool error, so the model reads it and
+   * adapts (name the paths, or don't do it) with no new IPC or renderer
+   * channel — the same reason it works identically in the GUI and the CLI.
+   */
+  async function guardedExecute(name, args, toolCtx) {
+    const guard = toolCtx && toolCtx.guard;
+    if (guard && name === 'exec') {
+      const verdict = blocksDestructive(guard, args && args.command);
+      if (!verdict.ok) return { ok: false, error: verdict.reason };
+    }
+    // Awaited, not merely returned: "this path is mine" is only true once the
+    // write actually landed, and `executeTool` is async — inspecting `.ok` on
+    // an un-awaited promise would read undefined and record every write,
+    // including the ones that failed. Ownership is load-bearing in the other
+    // direction too: a path wrongly claimed stops being reported as foreign.
+    const result = await T.executeTool(name, args, toolCtx);
+    if (guard && (name === 'writeFile' || name === 'editFile') && result && result.ok !== false) {
+      recordWrite(guard, args && args.path);
+    }
+    return result;
+  }
+
   async function gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal }) {
     const { name, args } = call;
-    if (!T.MUTATING_TOOLS.has(name)) return T.executeTool(name, args, toolCtx);
-    if (!confirmModeEnabled()) return T.executeTool(name, args, toolCtx);
-    if (sessionAllows(rootSessionId, name)) return T.executeTool(name, args, toolCtx);
+    if (!T.MUTATING_TOOLS.has(name)) return guardedExecute(name, args, toolCtx);
+    if (!confirmModeEnabled()) return guardedExecute(name, args, toolCtx);
+    if (sessionAllows(rootSessionId, name)) return guardedExecute(name, args, toolCtx);
     // Already refused in this conversation: refuse again WITHOUT raising a
     // second card. Before this, the model's retry after a denial re-prompted
     // the user for the same tool — one "no" produced a card per round for up
@@ -521,8 +611,18 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     }
     if (decision === 'session') allowForSession(rootSessionId, name);
 
-    if (preview) return T.applyChecked(name, args, preview);
-    return T.executeTool(name, args, toolCtx);
+    if (preview) {
+      const res = T.applyChecked(name, args, preview);
+      // Recorded on the same condition as guardedExecute's path: only a write
+      // that landed is this session's. (The previous form returned here
+      // unconditionally, making every line below it unreachable — the
+      // approved-write path recorded nothing at all.)
+      if (res && res.ok !== false && toolCtx && toolCtx.guard) {
+        recordWrite(toolCtx.guard, args && args.path);
+      }
+      return res;
+    }
+    return guardedExecute(name, args, toolCtx);
   }
 
   /**
@@ -634,8 +734,9 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         // derived number states one decision twice — and the copies had already
         // drifted: 974adc5 doubled aegis1's ladder while this side stood still,
         // leaving the client capping below the budget it displayed. The cap was
-        // never the one the renderer showed either (updateBudgetControls hides
-        // the max-tokens dropdown for the pooled class). Omitting the field is
+        // never the one the renderer showed either (the Max tokens dropdown
+        // that used to claim a figure for the pooled class is gone — see
+        // desktop/renderer/budget.js). Omitting the field is
         // what tells aegis1 "no cap stated — let effort decide", the same
         // contract aegiscodex-dev sends.
         //
@@ -779,7 +880,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
   async function chat(payload, onDelta) {
     const cls = payload && payload.class;
     const model = payload && payload.model;
-    const maxTokens = reasoningBudget(model, payload && payload.maxTokens, payload && payload.effort);
+    const maxTokens = reasoningBudget(cls, model, payload && payload.maxTokens, payload && payload.effort);
     // The caller's OWN number, kept apart from `maxTokens` above. That one
     // collapses two different facts into a single value — "the caller stated
     // 4096" and "effort implies 32768" — and the pooled path must treat them
@@ -788,7 +889,10 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     // an effort-derived one is the server's own arithmetic stated twice, and
     // sending it is how the two copies came to disagree. So the pooled call
     // forwards only what the caller actually asked for.
-    const statedMaxTokens = Number(payload && payload.maxTokens) > 0 ? Number(payload.maxTokens) : undefined;
+    // ...and it is read through statedCapOf(), so a nested chat() that states
+    // the key overrides its own derived `maxTokens` instead of being mistaken
+    // for a caller who asked for that number (see statedCapOf).
+    const statedMaxTokens = statedCapOf(payload);
     // "Work autonomously" — routes this call through aegis1's pool_brain
     // worker fan-out (services/pool_brain.py: N reasoning workers + a
     // synthesis pass) instead of a single provider call. UI-gated to the
@@ -1105,7 +1209,8 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         for (const call of calls) {
           const result = call.name === T.SUBAGENT_TOOL
             ? await runSubagent(call.args, {
-                cls, model, maxTokens, mode: payload && payload.mode, parentSignal: signal, depth, rootSessionId, rootOnDelta,
+                cls, model, statedMaxTokens, effort: payload && payload.effort,
+                mode: payload && payload.mode, parentSignal: signal, depth, rootSessionId, rootOnDelta,
               })
             : await gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal });
           // A subagent's spend rides back on its tool result (see runSubagent).
@@ -1135,7 +1240,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
    */
   async function runSubagent(
     { description, subagent_type, prompt: subPrompt } = {},
-    { cls, model, maxTokens, mode, parentSignal, depth, rootSessionId, rootOnDelta } = {}
+    { cls, model, statedMaxTokens, effort, mode, parentSignal, depth, rootSessionId, rootOnDelta } = {}
   ) {
     const task = String(subPrompt || description || '').trim();
     if (!task) return { ok: false, error: 'task requires a prompt' };
@@ -1159,8 +1264,17 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       // silently hanging behind this call's no-op onDelta below.
       const res = await chat(
         {
-          class: cls, model, maxTokens, mode, system, prompt: task, sessionId: subSessionId, depth: (depth || 0) + 1,
+          class: cls, model, mode, system, prompt: task, sessionId: subSessionId, depth: (depth || 0) + 1,
           rootSessionId, rootOnDelta,
+          // The parent's budget AUTHORITY is forwarded, not the number it
+          // implies. `maxTokens` is deliberately absent: it is the rung this
+          // turn derived from `effort`, and a re-entry that hands it back gets
+          // read as the caller's own cap (statedCapOf). The rung itself rides
+          // along as `effort`, which is what aegis1 sizes the fan-out and its
+          // ladder from — so a subagent now runs at the effort the user chose
+          // instead of at a number that only meant anything for this model id.
+          statedMaxTokens,
+          effort,
         },
         () => {}
       );
@@ -1199,4 +1313,4 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
   };
 }
 
-module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs };
+module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs, reasoningBudget };

package/lib/local/git-scope.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Minimal git worktree introspection: where the repo root is, and what is
+ * dirty right now with a content hash per path.
+ *
+ * Ported from aegiscodex-dev/src/git-scope.js (ESM → CommonJS). Only the two
+ * functions `turn-guard.js` needs are carried over — `gitRoot` and
+ * `gitStatusSnapshot` (plus their `contentHash` helper). The source file's
+ * `foreignChanges` and `scopedCommit` belong to the autonomous queue's
+ * commit path, which the plugin does not host, so they are deliberately not
+ * vendored: a copy of code nothing calls is a copy that drifts unnoticed.
+ *
+ * The "dirty before AND byte-identical now" definition lives in
+ * `gitStatusSnapshot`'s hashes; `turn-guard.js` is the only consumer.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+/** The repo root for `cwd`, or null if it isn't inside a git work tree. */
+function gitRoot(cwd) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/**
+ * Hash a path's worktree content, so "already dirty before the task ran" can
+ * be told apart from "this task changed it". `absent` covers deletions;
+ * non-files (a submodule, a directory) compare by kind.
+ */
+function contentHash(cwd, rel) {
+  try {
+    const st = fs.lstatSync(path.join(cwd, rel));
+    if (!st.isFile()) return st.isDirectory() ? 'nonfile:dir' : 'nonfile:other';
+    return crypto.createHash('sha1').update(fs.readFileSync(path.join(cwd, rel))).digest('hex');
+  } catch {
+    return 'absent';
+  }
+}
+
+/**
+ * Every path git reports as dirty right now, mapped to its content hash.
+ * `--no-renames` matters: in `-z` porcelain a rename emits the old name as a
+ * second NUL-terminated token, which we would otherwise hash as a change.
+ * Untracked files are included, since that is exactly how concurrent work
+ * usually arrives. Returns null if `cwd` is not a usable git repo.
+ */
+function gitStatusSnapshot(cwd) {
+  // Run from the repo root: porcelain reports paths root-relative, so hashing
+  // must resolve them against the same directory.
+  const root = gitRoot(cwd);
+  if (!root) return null;
+  const r = spawnSync(
+    'git',
+    ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames'],
+    { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (r.status !== 0) return null;
+  const snap = new Map();
+  for (const rec of r.stdout.split('\0')) {
+    if (rec.length < 4) continue;
+    const p = rec.slice(3);
+    snap.set(p, contentHash(root, p));
+  }
+  return snap;
+}
+
+module.exports = { gitRoot, contentHash, gitStatusSnapshot };

package/lib/local/ollama.js

@@ -49,7 +49,7 @@ async function chat({
   messages,
   system,
   prompt,
-  maxTokens = 4096,
+  maxTokens,
   temperature,
   tools,
   toolChoice,

package/lib/local/providers.js

@@ -341,7 +341,7 @@ async function openaiCompatible({
   messages,
   system,
   prompt,
-  maxTokens = 4096,
+  maxTokens,
   temperature,
   tools,
   toolChoice,
@@ -356,9 +356,20 @@ async function openaiCompatible({
   const body = {
     model: modelId,
     messages: openAIMessages(messages, system, prompt),
-    max_tokens: maxTokens || 4096,
     stream: true,
   };
+  // `max_tokens` travels only when the caller actually stated one. Nothing is
+  // invented here — not even as a signature default (this parameter used to
+  // read `maxTokens = 4096`, so the field appeared even when engine.js passed
+  // undefined on purpose). The output length of a reasoning model is not
+  // predictable from the request: DeepSeek bills hidden chain-of-thought
+  // against the same budget, so a client-chosen 4096 never bounded the answer,
+  // it bounded the thinking and truncated turns that would otherwise have
+  // finished. engine.js's reasoningBudget() supplies a value when the /effort
+  // rung is the only lever the provider exposes; for everything else the
+  // provider's own default is the number it was tuned for, and omitting the
+  // key is how you ask for it.
+  if (Number(maxTokens) > 0) body.max_tokens = Number(maxTokens);
   if (temperature != null) body.temperature = temperature;
   // Only advertise tools when the caller passes a non-empty list — an empty
   // `tools: []` is a 400 on some gateways.
@@ -485,7 +496,7 @@ async function anthropicMessages({
   messages,
   system,
   prompt,
-  maxTokens = 4096,
+  maxTokens,
   temperature,
   tools,
   toolChoice,
@@ -505,10 +516,24 @@ async function anthropicMessages({
 
   const body = {
     model: modelId,
-    max_tokens: maxTokens || 4096,
     stream: true,
     messages: buildAnthropicMessages(messages, prompt),
   };
+  // State the field only when the caller actually gave a number — the same rule
+  // the OpenAI-compatible transport below follows, and for the same reason.
+  //
+  // There is no client-side floor or ceiling constant here, deliberately. The
+  // Messages API does require `max_tokens`, but a number this side can only
+  // guess at is exactly what used to truncate reasoning turns: the budget is
+  // spent on hidden chain-of-thought before the first visible token, so the
+  // request "completed" having answered nothing. The size of a call belongs to
+  // whoever owns the model — engine.js's reasoningBudget() (the /effort rung,
+  // which is what the caller is passing here) or the platform itself, which
+  // sizes the pooled class from `effort` server-side and reads a body
+  // max_tokens as a ceiling OVER that ladder. So an unstated budget goes out
+  // unstated and the platform's value applies; this transport does not
+  // substitute one of its own.
+  if (Number(maxTokens) > 0) body.max_tokens = Number(maxTokens);
   if (system) body.system = system;
   if (temperature != null) body.temperature = temperature;
   // Anthropic wants {name, description, input_schema} — an OpenAI-shaped list