@mycadet/cli 0.12.6-dev.202610080102.d7d1bec → 0.12.6-dev.202610082233.54244ee

package/README.md

@@ -57,7 +57,7 @@ cadet hatch [options]
 
 - **`local`** -- Starts the local assistant and local gateway. Gateway source resolution order is: repo source tree, then installed `@mycadet/gateway` package.
 - **`docker`** -- Starts the assistant, gateway, and credential service in Docker containers.
-- **`cadet`** -- Hatches an assistant on the Cadet Cloud.
+- **`cadet`** -- Hatches an assistant on Cadet Cloud.
 - **`custom`** -- Recognized but not yet implemented.
 
 #### Environment Variables

package/knip.json

@@ -4,15 +4,21 @@
     "src/**/__tests__/**/*.ts",
     "src/lib/version-compat.ts",
     "src/lib/platform-releases.ts",
-    "src/lib/cli-error.ts"
+    "src/lib/cli-error.ts",
+    "scripts/**/*.ts"
+  ],
+  "project": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
   ],
-  "project": ["src/**/*.ts", "src/**/*.tsx"],
   "ignoreDependencies": [
+    "@mycadet/assistant-api",
     "@mycadet/avatar-manifest",
     "@mycadet/environments",
     "@mycadet/ipc-server-utils",
     "@mycadet/local-mode",
     "@mycadet/service-contracts",
+    "@mycadet/shared",
     "@mycadet/web"
   ]
 }

package/node_modules/@mycadet/assistant-api/README.md

@@ -0,0 +1,133 @@
+# @mycadet/assistant-api
+
+Public API surface for consumers of the assistant runtime — web client, gateway,
+evals, future external clients. This directory is the **source of truth** for
+the wire contracts the assistant exposes: schemas, types, and pure helpers.
+
+Internal assistant code imports the files in this directory via relative paths
+(e.g. `../../api/events/open-url.js`). External consumers import it as the
+workspace package `@mycadet/assistant-api`, a `workspace:*` symlink to this
+directory, so an edit here reaches them immediately. The generated HTTP
+client is separate: it comes from `assistant/openapi.yaml`, regenerated with
+`cd assistant && bun run generate:openapi` and consumed by
+`cd clients/web && bun run openapi-ts`.
+
+## Architecture
+
+A single discriminated-union schema, `AssistantEventSchema`, covers every event
+type whose wire contract is canonical. The web parser (`event-parser.ts`) tries
+this schema first; events not yet covered fall through to a hand-rolled legacy
+switch. The migration goal is to drain the switch — each event moved here
+shrinks the legacy surface and makes wire-shape drift a compile error.
+
+`AssistantEvent` (re-exported alongside the schema) is `z.infer<typeof
+AssistantEventSchema>`. Consumers reference this single type rather than
+re-listing the individual member types: as new events migrate in, they appear
+in `AssistantEvent` automatically.
+
+## Migration recipe
+
+Each batch follows the same shape. Group cohesive event families (lifecycle,
+streaming, document-comment, ui-surface, etc.) rather than migrating events
+one at a time — the per-batch overhead is the same regardless of count.
+
+### 1. Add the canonical schema
+
+One file per event under `./events/`. Schemas use Zod's default strip
+mode — unknown fields are silently discarded during parsing so the
+server can add transport-level metadata (e.g. `seq`) without breaking
+client validation.
+
+```ts
+// assistant/src/api/events/my-event.ts
+import { z } from "zod";
+
+export const MyEventSchema = z.object({
+  type: z.literal("my_event"),
+  conversationId: z.string(),
+  // …
+});
+
+export type MyEvent = z.infer<typeof MyEventSchema>;
+```
+
+Add the type/schema re-export pair to `./index.ts`, alphabetically, and append
+the schema to the `AssistantEventSchema` discriminated union. No other changes
+to the canonical package are needed — `AssistantEvent` picks the new member
+up automatically.
+
+### 2. Adopt the canonical type in daemon code
+
+In `assistant/src/daemon/message-types/<domain>.ts`, delete the local
+`interface MyEvent { … }` declaration and import the canonical `MyEvent`
+type from `../../api/events/my-event.js`. The domain-level
+`_<Domain>ServerMessages` union alias (consumed by `message-protocol.ts`)
+keeps its existing shape — it just references the canonical types now.
+
+**Do not add `export type MyEventLocalName = MyEvent` alias bridges in the
+daemon message-types files.** They shadow the canonical name and create a
+second name for the same thing — exactly the drift this directory exists to
+prevent. Reference the canonical `*Event` name directly inside the
+`_<Domain>ServerMessages` aggregator union, and have downstream daemon
+consumers import the canonical type from `../../api/events/<name>.js` at the
+use site. The only thing that should live in `message-types/<domain>.ts` for
+a migrated event is the import and the union membership.
+
+### 3. Cut over web consumers
+
+`clients/web/src/domains/chat/api/event-types.ts` no longer needs to list the
+migrated event in its `AssistantEvent` union — `APIAssistantEvent` covers it.
+Drop the per-event member, leaving the union to peel off legacy entries one
+at a time as each event migrates.
+
+Local handler modules (e.g. `document-comment-events.ts`) keep their handler
+functions but import the wire types directly from `@mycadet/assistant-api`.
+Do **not** re-export the canonical types from intermediate modules — consumers
+import them straight from the canonical package.
+
+### 4. Delete the legacy parser cases
+
+Remove the matching `case "my_event":` blocks from
+`clients/web/src/domains/chat/api/event-parser.ts`. Any per-event helper
+(`parseFooBase`, etc.) goes with them.
+
+### 5. Tests
+
+Add parser tests for each migrated event covering:
+
+- happy path with all fields
+- minimal required only
+- missing required field → `UnknownEvent`
+- unknown extra field is silently stripped, event still parses
+
+For happy-path tests, inline the discriminator literal in both the input and
+the expected object. `const data = { type: "my_event", … }` widens
+`data.type` to `string`, breaking the discriminated-union match when the
+result is compared with `toEqual(data)`.
+
+Handler-level tests in the consuming domain modules typically need no change
+— the canonical types are wire-compatible with the previous local interfaces.
+
+### 6. Local greenlight gate
+
+Run before push, in order:
+
+```bash
+# Regenerate the OpenAPI spec and the web client from it
+( cd assistant && bun run generate:openapi )
+( cd clients/web && bun run openapi-ts )
+
+# Type-check both packages
+( cd assistant && bunx tsc --noEmit )
+( cd clients/web && bunx tsc --noEmit )
+
+# Targeted tests
+( cd clients/web && bun test src/domains/chat/api/event-parser.test.ts )
+
+# Lint + format the touched files
+bunx eslint <files>
+bunx prettier --write <files>
+```
+
+`format:check` is a distinct CI gate from `lint`; format the touched files
+before push.

package/node_modules/@mycadet/assistant-api/ask-question-tool.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+/**
+ * The `ask_question` tool's input as a recorded call carries it, for a client
+ * reading one back.
+ *
+ * The tool's own schema (`askQuestionInputSchema`) is the authority on what a
+ * model may send: it caps the batch, bounds the options, carries the
+ * descriptions the model reads, and refuses a call that passes both shapes.
+ * This one only has to read what was already accepted, so it validates the
+ * shape and nothing else, and tolerates a recorded call from an assistant
+ * whose bounds differed.
+ *
+ * Both shapes are here because both are what was asked. `desktopHelp` becomes
+ * a one-question prompt inside the daemon, so a reader that only understood
+ * `questions` would have nothing to show for a recorded desktop-help call.
+ *
+ * Structured records win where they exist: the answered record a settled
+ * prompt carries (`AnsweredQuestion`) and the live entries an outstanding one
+ * has. This is the fallback for a call that has neither, which is any prompt
+ * recorded before those records existed, one that timed out, and one whose
+ * outstanding entries a reload could not tie back to it.
+ */
+
+const RecordedQuestionOptionSchema = z.looseObject({
+  id: z.string().optional().catch(undefined),
+  label: z.string(),
+  description: z.string().optional().catch(undefined),
+});
+
+const RecordedQuestionSchema = z.looseObject({
+  question: z.string(),
+  description: z.string().optional().catch(undefined),
+  options: z.array(RecordedQuestionOptionSchema).optional().catch(undefined),
+});
+
+export const AskQuestionInputSchema = z.looseObject({
+  questions: z.array(RecordedQuestionSchema).optional().catch(undefined),
+  desktopHelp: z
+    .looseObject({
+      message: z.string(),
+      doneLabel: z.string().optional().catch(undefined),
+      skipLabel: z.string().optional().catch(undefined),
+    })
+    .optional()
+    .catch(undefined),
+});
+
+export type AskQuestionInput = z.infer<typeof AskQuestionInputSchema>;
+export type RecordedQuestion = z.infer<typeof RecordedQuestionSchema>;

package/node_modules/@mycadet/assistant-api/attachment-provenance.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+
+import { AssistantOutboundAttachmentSchema } from "./events/assistant-outbound-attachment.js";
+import { ConversationMessageAttachmentSchema } from "./responses/conversation-message.js";
+
+const outboundFixture = {
+  id: "attachment-1",
+  filename: "screenshot.png",
+  mimeType: "image/png",
+  data: "c2NyZWVuc2hvdA==",
+  sourceType: "tool_block" as const,
+};
+
+const historyFixture = {
+  id: "attachment-1",
+  filename: "screenshot.png",
+  mimeType: "image/png",
+  sizeBytes: 10,
+  kind: "image",
+};
+
+describe("computer-use screenshot attachment provenance", () => {
+  test("new schemas accept the marker and its absence", () => {
+    expect(
+      AssistantOutboundAttachmentSchema.parse({
+        ...outboundFixture,
+        computerUseScreenshot: true,
+      }).computerUseScreenshot,
+    ).toBe(true);
+    expect(
+      AssistantOutboundAttachmentSchema.parse(outboundFixture)
+        .computerUseScreenshot,
+    ).toBeUndefined();
+
+    expect(
+      ConversationMessageAttachmentSchema.parse({
+        ...historyFixture,
+        computerUseScreenshot: true,
+      }).computerUseScreenshot,
+    ).toBe(true);
+    expect(
+      ConversationMessageAttachmentSchema.parse(historyFixture)
+        .computerUseScreenshot,
+    ).toBeUndefined();
+  });
+
+  test("legacy object parsers tolerate and strip the additive marker", () => {
+    const legacyOutbound = AssistantOutboundAttachmentSchema.omit({
+      computerUseScreenshot: true,
+    });
+    const legacyHistory = ConversationMessageAttachmentSchema.omit({
+      computerUseScreenshot: true,
+    });
+
+    expect(
+      legacyOutbound.parse({
+        ...outboundFixture,
+        computerUseScreenshot: true,
+      }),
+    ).toEqual(outboundFixture);
+    expect(
+      legacyHistory.parse({
+        ...historyFixture,
+        computerUseScreenshot: true,
+      }),
+    ).toEqual(historyFixture);
+  });
+});

package/node_modules/@mycadet/assistant-api/computer-use-tool.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isComputerUseToolCall,
+  resolveComputerUseToolName,
+} from "./computer-use-tool.js";
+
+describe("isComputerUseToolCall", () => {
+  test("recognizes direct and skill-wrapped computer-use calls", () => {
+    expect(isComputerUseToolCall("computer_use_click", {})).toBe(true);
+    expect(
+      isComputerUseToolCall("skill_execute", { tool: "computer_use_type" }),
+    ).toBe(true);
+  });
+
+  test("resolves the direct or wrapped computer-use tool name", () => {
+    expect(resolveComputerUseToolName("computer_use_click", {})).toBe(
+      "computer_use_click",
+    );
+    expect(
+      resolveComputerUseToolName("skill_execute", {
+        tool: "computer_use_scroll",
+      }),
+    ).toBe("computer_use_scroll");
+  });
+
+  test("rejects unrelated media tools and malformed skill input", () => {
+    expect(isComputerUseToolCall("browser_screenshot", {})).toBe(false);
+    expect(isComputerUseToolCall("file_read", {})).toBe(false);
+    expect(isComputerUseToolCall("image_generate", {})).toBe(false);
+    expect(isComputerUseToolCall("skill_execute", null)).toBe(false);
+    expect(isComputerUseToolCall("skill_execute", "computer_use_click")).toBe(
+      false,
+    );
+    expect(isComputerUseToolCall("skill_execute", { tool: 42 })).toBe(false);
+    expect(
+      isComputerUseToolCall("skill_execute", {
+        tool: "browser_screenshot",
+      }),
+    ).toBe(false);
+  });
+
+  test("does not classify raw-only recovered skill input", () => {
+    expect(
+      isComputerUseToolCall("skill_execute", {
+        _raw: '{"tool":"computer_use_click"}',
+      }),
+    ).toBe(false);
+    expect(
+      resolveComputerUseToolName("skill_execute", {
+        _raw: '{"tool":"computer_use_click"}',
+      }),
+    ).toBeUndefined();
+  });
+});

package/node_modules/@mycadet/assistant-api/computer-use-tool.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve the host computer-use tool behind a direct or skill-wrapped call.
+ *
+ * Skills expose their selected tool in structured input. Calls recovered only
+ * from `_raw` retain their legacy behavior because this helper deliberately
+ * does not parse a second input representation.
+ */
+export function resolveComputerUseToolName(
+  name: string,
+  input: unknown,
+): string | undefined {
+  if (name.startsWith("computer_use_")) {
+    return name;
+  }
+  if (name !== "skill_execute" || input === null || typeof input !== "object") {
+    return undefined;
+  }
+  const tool = (input as Record<string, unknown>).tool;
+  return typeof tool === "string" && tool.startsWith("computer_use_")
+    ? tool
+    : undefined;
+}
+
+/** True when a tool call is backed by the host computer-use capability. */
+export function isComputerUseToolCall(name: string, input: unknown): boolean {
+  return resolveComputerUseToolName(name, input) !== undefined;
+}

package/node_modules/@mycadet/assistant-api/constants/app-tools.ts

@@ -0,0 +1,34 @@
+/**
+ * The app tools that mutate the stored app set, and what each one leaves
+ * behind. Mirrors `document-tools.ts`: a single declaration both the daemon and
+ * the web client derive their tool sets from, so a new mutating app tool is
+ * added here once and every consumer picks it up.
+ *
+ * Tool names are the ones the runner sees. Calls arriving through the bundled
+ * `app-builder` skill reach the daemon already unwrapped to the inner tool
+ * name, and the web client unwraps the `skill_execute` envelope itself.
+ */
+
+export interface AppMutationTool {
+  /** The executed tool name. */
+  readonly name: string;
+  /**
+   * Whether the app is still openable once the tool has run. A deleted app has
+   * nothing to open, so it cannot anchor a card back to itself.
+   */
+  readonly reopenable: boolean;
+}
+
+export const APP_MUTATION_TOOLS: readonly AppMutationTool[] = [
+  { name: "app_create", reopenable: true },
+  { name: "app_update", reopenable: true },
+  { name: "app_delete", reopenable: false },
+];
+
+/**
+ * The mutating app tools that leave the app openable. The web transcript
+ * anchors its end-of-response app cards on these, so a delete never produces a
+ * card pointing at an app that is gone.
+ */
+export const APP_MUTATION_TOOL_NAMES: readonly string[] =
+  APP_MUTATION_TOOLS.filter((tool) => tool.reopenable).map((tool) => tool.name);

package/node_modules/@mycadet/assistant-api/constants/call-sites.ts

@@ -0,0 +1,39 @@
+/**
+ * Logical call-site identifiers stamped onto every `llm_request_log` row
+ * (column `call_site` — migration 264). The inspector branches on this
+ * value alone to distinguish real LLM calls (`mainAgent`,
+ * `compactionAgent`, …) from synthetic agent-error-message rows.
+ *
+ * The constants below are the wire contract; both backend (when writing
+ * a row) and frontend (when rendering one) must reference the same
+ * literal. Add new call sites here as new emit sites appear.
+ */
+
+/**
+ * Marks a synthetic assistant error-message row — one the agent loop
+ * emitted because something went wrong (budget yield, out of funds, …)
+ * with no underlying LLM call. All such events cause the loop to exit,
+ * so a single generic bucket plus the existing `agent_loop_exit_reason`
+ * column is enough to discriminate which kind of error fired
+ * (`budget_yield_unrecovered`, future out-of-funds, etc.).
+ *
+ * Intentionally *not* a member of the backend's `LLMCallSite` enum:
+ * that enum binds config lookup, not the shape of the `call_site`
+ * column. Compaction-route filters that match
+ * `call_site = 'compactionAgent'` already treat this value as a
+ * non-compaction call, which is the desired floor-lookup behavior.
+ */
+export const CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE =
+  "syntheticAgentErrorMessage";
+
+/**
+ * Marks the summarizer LLM call the agent loop makes to compact a
+ * conversation's history when it approaches the context limit. The row
+ * lands in the inspector rail like any other call, so the frontend
+ * branches on this value to tag it as a compaction rather than a
+ * main-agent call.
+ *
+ * Mirrors the `compactionAgent` member of the backend's `LLMCallSite`
+ * enum (the value stamped on the row at write time).
+ */
+export const CALL_SITE_COMPACTION_AGENT = "compactionAgent";

package/node_modules/@mycadet/assistant-api/constants/document-tools.ts

@@ -0,0 +1,55 @@
+/**
+ * The document tools that mutate the stored document set, and what each one
+ * leaves behind. This is the single declaration both the daemon and the web
+ * client derive their tool sets from, so a new mutating document tool is added
+ * here once and every consumer picks it up.
+ *
+ * Tool names are the ones the runner sees. Calls arriving through the bundled
+ * `document-editor` skill reach the daemon already unwrapped to the inner tool
+ * name, and the web client unwraps the `skill_execute` envelope itself.
+ */
+
+export interface DocumentMutationTool {
+  /** The executed tool name. */
+  readonly name: string;
+  /**
+   * Whether the document is still openable once the tool has run. A deleted
+   * document has nothing to open, so it cannot anchor a link back to itself.
+   */
+  readonly reopenable: boolean;
+  /**
+   * Whether the tool writes into an already-created document, as opposed to
+   * the create that opened it.
+   */
+  readonly edit: boolean;
+}
+
+export const DOCUMENT_MUTATION_TOOLS: readonly DocumentMutationTool[] = [
+  { name: "document_create", reopenable: true, edit: false },
+  { name: "document_update", reopenable: true, edit: true },
+  { name: "document_replace_text", reopenable: true, edit: true },
+  { name: "document_delete", reopenable: false, edit: false },
+];
+
+/**
+ * Every tool that changes the document list. The daemon hooks these to publish
+ * a documents-changed broadcast, because they carry no list-level change signal
+ * of their own and client asset lists would otherwise keep serving a cached
+ * list after an edit and a deleted document would linger as a ghost row.
+ */
+export const DOCUMENT_MUTATION_TOOL_NAMES: readonly string[] =
+  DOCUMENT_MUTATION_TOOLS.map((tool) => tool.name);
+
+/**
+ * The mutating tools that leave the document openable. The web transcript
+ * anchors its changed-document chips on these, so a delete never produces a
+ * chip pointing at a document that is gone.
+ */
+export const REOPENABLE_DOCUMENT_MUTATION_TOOL_NAMES: readonly string[] =
+  DOCUMENT_MUTATION_TOOLS.filter((tool) => tool.reopenable).map(
+    (tool) => tool.name,
+  );
+
+/** The mutating tools that write into an already-created document. */
+export const DOCUMENT_EDIT_TOOL_NAMES: readonly string[] =
+  DOCUMENT_MUTATION_TOOLS.filter((tool) => tool.edit).map((tool) => tool.name);

package/node_modules/@mycadet/assistant-api/constants/personality-sliders.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  PERSONALITY_AXIS_IDS,
+  PERSONALITY_DIRECTION_AXES,
+  PERSONALITY_SLIDER_DEFAULT,
+  PERSONALITY_SLIDERS_PATH,
+} from "./personality-sliders.js";
+
+describe("personality slider contract", () => {
+  test("sidecar path and default stay centered", () => {
+    expect(PERSONALITY_SLIDERS_PATH).toBe("data/personality-sliders.json");
+    expect(PERSONALITY_SLIDER_DEFAULT).toBe(50);
+  });
+
+  test("every slider axis has a left and right direction pole", () => {
+    expect(PERSONALITY_DIRECTION_AXES.map((axis) => axis.sliderId)).toEqual(
+      Object.values(PERSONALITY_AXIS_IDS),
+    );
+  });
+});

package/node_modules/@mycadet/assistant-api/constants/personality-sliders.ts

@@ -0,0 +1,64 @@
+/**
+ * Personality slider sidecar path, the five 0-100 axis ids, and the
+ * hosted-Qwen direction poles those sliders map onto.
+ *
+ * The web writes `data/personality-sliders.json`. The assistant reads the
+ * same path and maps each slider onto one left/right pole. Both import
+ * these constants from `@mycadet/assistant-api` so the ids cannot drift.
+ */
+
+/** Workspace-relative sidecar holding the five 0-100 slider values. */
+export const PERSONALITY_SLIDERS_PATH = "data/personality-sliders.json";
+
+/** Sliders start centered. Center is no steer on the hosted-Qwen route. */
+export const PERSONALITY_SLIDER_DEFAULT = 50;
+
+/**
+ * Axis ids the personality sliders key their values by. Each is 0-100 with
+ * 0 = the left label and 100 = the right label.
+ */
+export const PERSONALITY_AXIS_IDS = {
+  companionCoworker: "companion-coworker",
+  genzBoomer: "genz-boomer",
+  executeCollaborate: "execute-collaborate",
+  playfulSerious: "playful-serious",
+  politeUnfiltered: "polite-unfiltered",
+} as const;
+
+export type PersonalityAxisId =
+  (typeof PERSONALITY_AXIS_IDS)[keyof typeof PERSONALITY_AXIS_IDS];
+
+/**
+ * One-sided direction poles for each slider. Center (50) activates neither.
+ * Values below 50 activate `left`; values above 50 activate `right`.
+ */
+export const PERSONALITY_DIRECTION_AXES = [
+  {
+    sliderId: PERSONALITY_AXIS_IDS.companionCoworker,
+    left: "companion",
+    right: "coworker",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.genzBoomer,
+    left: "genz",
+    right: "boomer",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.executeCollaborate,
+    left: "independent",
+    right: "collaborative",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.playfulSerious,
+    left: "playful",
+    right: "serious",
+  },
+  {
+    sliderId: PERSONALITY_AXIS_IDS.politeUnfiltered,
+    left: "polite",
+    right: "unfiltered",
+  },
+] as const;
+
+export type PersonalityDirectionAxis =
+  (typeof PERSONALITY_DIRECTION_AXES)[number];

package/node_modules/@mycadet/assistant-api/constants/profile-config-validation.ts

@@ -0,0 +1,60 @@
+/**
+ * Static sanity check for a profile's explicit token budget against the
+ * model's catalog limits. Catches configurations that can never dispatch
+ * (the output budget consumes the model's entire context window, or exceeds
+ * its output cap) at save time instead of on the first chat message.
+ *
+ * Shared surface: the daemon's profile write routes enforce it as a blocking
+ * error, and the web profile editor mirrors the same judgment before its
+ * generic config PATCH, so the two paths cannot drift. Only fires when both
+ * sides of a judgment are known; unlisted models are covered by the live
+ * save-time probe instead.
+ */
+
+/**
+ * Input room a profile must leave when its output budget is judged against
+ * the model's total context window.
+ */
+export const MIN_INPUT_RESERVE_TOKENS = 4096;
+
+export interface ProfileConfigIssue {
+  field: "maxTokens";
+  /** Which judgment fired, so clients can compose surface-specific copy. */
+  code: "over_output_cap" | "no_input_room";
+  message: string;
+}
+
+export function validateInferenceProfileConfig(args: {
+  maxTokens?: number;
+  modelMaxOutputTokens?: number;
+  modelContextWindowTokens?: number;
+}): ProfileConfigIssue | null {
+  const { maxTokens, modelMaxOutputTokens, modelContextWindowTokens } = args;
+  if (maxTokens === undefined) {
+    return null;
+  }
+  if (modelMaxOutputTokens !== undefined && maxTokens > modelMaxOutputTokens) {
+    return {
+      field: "maxTokens",
+      code: "over_output_cap",
+      message:
+        `maxTokens (${maxTokens}) exceeds the model's maximum output of ` +
+        `${modelMaxOutputTokens} tokens. Requests would be rejected upstream; ` +
+        `reduce maxTokens to ${modelMaxOutputTokens} or less.`,
+    };
+  }
+  if (
+    modelContextWindowTokens !== undefined &&
+    maxTokens >= modelContextWindowTokens - MIN_INPUT_RESERVE_TOKENS
+  ) {
+    return {
+      field: "maxTokens",
+      code: "no_input_room",
+      message:
+        `maxTokens (${maxTokens}) reserves the entire ${modelContextWindowTokens}-token ` +
+        `context window for output, leaving no room for your messages. ` +
+        `Reduce maxTokens (e.g. 8000) so input fits.`,
+    };
+  }
+  return null;
+}