@volter/twin-cohere 0.1.0

package/src/cohere-models.ts

@@ -0,0 +1,79 @@
+// The STATIC Cohere model catalog the twin serves at `GET /v1/models` and `GET /v1/models/{id}`.
+//
+// This is REAL vendor data, not a stub: the ids, context lengths and endpoint compatibility below
+// were read from Cohere's own published models page (https://docs.cohere.com/docs/models, read
+// 2026-08-31) and cross-checked against the model ids that appear in cohere-ai@8.1.0's own
+// `reference.md` usage examples (`command-a-plus-05-2026`, `command-a-03-2025`,
+// `command-a-vision-07-2025`, `embed-v4.0`, `rerank-v4.0-pro`).
+//
+// `endpoints` uses Cohere's own `CompatibleEndpoint` closed set (chat | embed | classify |
+// summarize | rerank | rate | generate — `api/types/CompatibleEndpoint.d.ts`). That closed set is
+// an ORACLE, not decoration: `cohere-twin.test.ts` asserts every catalog entry's endpoints are a
+// subset of it, so an invented endpoint name cannot slip in.
+import { COHERE_ENDPOINTS, type CohereEndpoint, type CohereModelCard } from './cohere-types.ts';
+
+/**
+ * The catalog. `tokenizer_url` is DERIVED from Cohere's published tokenizer URL pattern
+ * (`storage.googleapis.com/cohere-public/tokenizers/<model>.json`) and is NOT individually verified
+ * per model — several of these (the rerank and embed cards especially) may have no such artifact,
+ * and neither SDK carries the per-model URLs to check against. Saying so is the honest scope: an
+ * earlier note called this "Cohere's real published artifacts", which overstated what was read
+ * (§9 round two, m-R2.6). The twin never FETCHES it either way — that would be request-time egress
+ * and would break serve-path determinism.
+ */
+export const COHERE_MODELS: CohereModelCard[] = [
+  // ── chat ──────────────────────────────────────────────────────────────────────────────
+  card('command-a-plus-05-2026', ['chat'], 128_000),
+  card('command-a-03-2025', ['chat'], 256_000),
+  card('command-a-reasoning-08-2025', ['chat'], 256_000),
+  card('command-a-vision-07-2025', ['chat'], 128_000),
+  card('command-a-translate-08-2025', ['chat'], 8_000),
+  card('command-r7b-12-2024', ['chat'], 128_000),
+  card('command-r-plus-08-2024', ['chat'], 128_000),
+  card('command-r-08-2024', ['chat'], 128_000),
+  card('c4ai-aya-expanse-32b', ['chat'], 128_000),
+  card('c4ai-aya-vision-32b', ['chat'], 16_000),
+  // ── embed ─────────────────────────────────────────────────────────────────────────────
+  card('embed-v4.0', ['embed'], 128_000),
+  card('embed-english-v3.0', ['embed'], 512),
+  card('embed-english-light-v3.0', ['embed'], 512),
+  card('embed-multilingual-v3.0', ['embed'], 512),
+  card('embed-multilingual-light-v3.0', ['embed'], 512),
+  // ── rerank ────────────────────────────────────────────────────────────────────────────
+  card('rerank-v4.0-pro', ['rerank'], 32_000),
+  card('rerank-v4.0-fast', ['rerank'], 32_000),
+  card('rerank-v3.5', ['rerank'], 4_000),
+  card('rerank-english-v3.0', ['rerank'], 4_000),
+  card('rerank-multilingual-v3.0', ['rerank'], 4_000),
+];
+
+function card(name: string, endpoints: CohereEndpoint[], contextLength: number): CohereModelCard {
+  return {
+    name,
+    endpoints,
+    finetuned: false,
+    context_length: contextLength,
+    tokenizer_url: `https://storage.googleapis.com/cohere-public/tokenizers/${name}.json`,
+    default_endpoints: [],
+  };
+}
+
+const BY_NAME = new Map(COHERE_MODELS.map((m) => [m.name, m]));
+
+/** Look a model up by its exact id. Cohere has no alias resolution on this endpoint. */
+export function findModel(name: string): CohereModelCard | undefined {
+  return BY_NAME.get(name);
+}
+
+/**
+ * Does `name` name a model that serves `endpoint`? Used to reject `POST /v2/chat` with an embed
+ * model (and vice versa) the way the vendor does, rather than happily generating from it — an
+ * unmodeled-op-fails-like-the-vendor property that is TESTABLE.
+ */
+export function modelServes(name: string, endpoint: CohereEndpoint): boolean {
+  const m = BY_NAME.get(name);
+  return m !== undefined && m.endpoints.includes(endpoint);
+}
+
+/** The closed `CompatibleEndpoint` set, re-exported so tests can assert against it by name. */
+export { COHERE_ENDPOINTS };

package/src/cohere-scenario.ts

@@ -0,0 +1,194 @@
+// The cohere pack's HALF of the scenario system: vocabulary + realization. The GRAMMAR
+// (ordering, once/scope/phase, extractors, strict parsing, miss records, twin.use) is the
+// kernel's ONE engine — @volter/world-core scenario.ts; see company-repo
+// BRIEFS/TWIN-PROGRAMMING-MODEL.md (LOCKED). There is deliberately NO bespoke engine here.
+// This module declares:
+//   • the `on` vocabulary a handler may match (model/userText/toolResult/hasTool …),
+//   • what a `respond` payload may contain (text / thinking / toolPlan / toolCalls / error),
+//   • how a fired handler's respond REALIZES into a vendor-faithful Cohere assistant turn
+//     (content items, `tool_plan`, `tool_calls`, and Cohere's UPPER-CASE finish reason).
+// It deliberately declares NO `scopeKey`: `/v2/chat` carries no end-user discriminator of the kind
+// anthropic's `metadata.user_id` or mistral's `user` provides, so there is nothing honest to key a
+// session on and every handler runs in the WORLD scope. The kernel enforces that — a handler
+// written with `scope: "session"` is REFUSED at load rather than silently sharing world state.
+// (§9 round 1 caught this header claiming the key anyway.)
+// The handler FILE (handlers/cohere.json in a world dir) is the only write surface.
+//
+// Scenario support is TWIN-ONLY SCAFFOLDING for eval worlds, not vendor surface, so it is
+// deliberately KEPT OUT of the capability manifest (the same rule as twin-only seed routes) and
+// gated by cohere-scenario.test.ts instead.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, lastUserText, toolCallId, toolNames } from './cohere-stub.ts';
+import { COHERE_FINISH_REASONS, type CohereAssistantContentItem, type CohereFinishReason, type CohereMessageV2, type CohereToolCallV2 } from './cohere-types.ts';
+
+/** The request slice the scenario system sees — built by the `/v2/chat` route from validated
+ *  args. */
+export type CohereScenarioRequest = {
+  model: string;
+  messages: CohereMessageV2[];
+  tools?: unknown;
+};
+
+export type CohereScenarioEngine = ScenarioEngine<CohereScenarioRequest>;
+
+/** A scripted tool call — the full argument payload is emitted verbatim (and streamed as a
+ *  `tool-call-start` / `tool-call-delta` / `tool-call-end` triple on the streaming path). */
+export type ScenarioToolCall = { name: string; arguments: Record<string, unknown>; id?: string };
+
+/** What the assistant says when a handler fires. */
+export type CohereScenarioRespond = {
+  text?: string;
+  /** A `thinking` content item, emitted BEFORE the text item — Cohere's own block ordering. */
+  thinking?: string;
+  /** Cohere's `tool_plan`: the chain-of-thought reflection that accompanies tool calls. */
+  toolPlan?: string;
+  toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+  /** Defaults to 'TOOL_CALL' when any tool call is present, else 'COMPLETE'. UPPER-CASE, from
+   *  Cohere's own `ChatFinishReason` set — not OpenAI's lower-case values. */
+  finishReason?: CohereFinishReason;
+  /** Scripted API error instead of a body: 429 rate limit (with retry-after), 500 api_error,
+   *  503 service_unavailable. Exclusive of the content forms. */
+  error?: { type: 'rate_limit' | 'api_error' | 'service_unavailable'; retryAfter?: number };
+};
+
+/** What a fired handler yields — the assistant turn for the envelope. */
+export type ScriptedResult = {
+  content: CohereAssistantContentItem[];
+  toolCalls: CohereToolCallV2[];
+  toolPlan?: string;
+  finishReason: CohereFinishReason;
+};
+
+const RESPOND_KEYS = new Set(['text', 'thinking', 'toolPlan', 'toolCalls', 'finishReason', 'error']);
+const FINISH_REASONS = new Set<string>(COHERE_FINISH_REASONS);
+const ERROR_TYPES = new Set(['rate_limit', 'api_error', 'service_unavailable']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+/**
+ * The tool NAMES the trailing `role:'tool'` messages answer — resolved through the
+ * `tool_call_id` of earlier assistant turns. Cohere's tool result is a `role:'tool'` message
+ * carrying `tool_call_id` (`ChatMessageV2.Tool`), and the id lives on the assistant turn's
+ * `tool_calls[].id`.
+ */
+function lastToolResultNames(messages: CohereMessageV2[]): Set<string> {
+  const names = new Set<string>();
+  const last = messages[messages.length - 1];
+  if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string') return names;
+  for (const m of messages) {
+    if (m.role !== 'assistant' || !Array.isArray(m.tool_calls)) continue;
+    for (const tc of m.tool_calls) {
+      if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string') names.add(tc.function.name);
+    }
+  }
+  return names;
+}
+
+/** The pack's scenario vocabulary + feature bag. One adapter instance, shared. */
+export const cohereScenarioAdapter: PackScenarioAdapter<CohereScenarioRequest> = {
+  vendor: 'cohere',
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageIsToolResult: (req.messages[req.messages.length - 1]?.role ?? '') === 'tool',
+    toolResultFor: [...lastToolResultNames(req.messages)],
+  }),
+  matchers: {
+    modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+    userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+    anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+    lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && ((req.messages[req.messages.length - 1]?.role ?? '') === 'tool') === cond,
+    toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+    hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+  },
+  text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+  validateOn: (on) => {
+    for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'] as const) {
+      if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k])) return `on.${k} is a non-empty string`;
+    }
+    if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean') return 'on.lastMessageIsToolResult is a boolean';
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { text?, thinking?, toolPlan?, toolCalls?, finishReason?, error? }';
+    const r = respond as Record<string, unknown>;
+    for (const k of Object.keys(r)) if (!RESPOND_KEYS.has(k)) return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+    if (r.text !== undefined && typeof r.text !== 'string') return 'respond.text is a string';
+    if (r.thinking !== undefined && typeof r.thinking !== 'string') return 'respond.thinking is a string';
+    if (r.toolPlan !== undefined && typeof r.toolPlan !== 'string') return 'respond.toolPlan is a string';
+    if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason))) {
+      return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+    }
+    if (r.toolCalls !== undefined) {
+      for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+        const t = tc as Record<string, unknown>;
+        if (!t || typeof t !== 'object' || Array.isArray(t)) return 'respond.toolCalls entries are objects';
+        if (typeof t.name !== 'string' || !t.name) return 'respond.toolCalls[].name is a non-empty string';
+        if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments)) return 'respond.toolCalls[].arguments is an object';
+        if (t.id !== undefined && typeof t.id !== 'string') return 'respond.toolCalls[].id is a string';
+      }
+    }
+    if (r.error !== undefined) {
+      const e = r.error as Record<string, unknown>;
+      if (!e || typeof e !== 'object' || Array.isArray(e)) return 'respond.error is an object { type, retryAfter? }';
+      if (typeof e.type !== 'string' || !ERROR_TYPES.has(e.type)) return `respond.error.type is one of ${[...ERROR_TYPES].join(', ')}`;
+      if (e.retryAfter !== undefined && (typeof e.retryAfter !== 'number' || e.retryAfter <= 0)) return 'respond.error.retryAfter is a positive number of seconds';
+      for (const k of Object.keys(e)) if (!['type', 'retryAfter'].includes(k)) return `respond.error: unknown key "${k}"`;
+    }
+    const hasBody = r.text !== undefined || r.thinking !== undefined || r.toolPlan !== undefined || r.toolCalls !== undefined;
+    if (r.error !== undefined && hasBody) return 'respond.error stands alone (no content forms beside it)';
+    if (!hasBody && r.error === undefined) return 'respond needs text, thinking, toolPlan, toolCalls, or error';
+    return null;
+  },
+};
+
+/** Load + strictly validate a handlers document (handlers/cohere.json). A broken file fails
+ *  server startup loudly; it never falls back or misfires silently. */
+export function loadCohereScenarioDocument(path: string): ScenarioDocument {
+  let parsed: unknown;
+  try {
+    // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+    // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+    // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+    // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+    // so the loud load-time failure reads byte-identically to the read it replaces.
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new ScenarioError(`cohere scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, cohereScenarioAdapter);
+}
+
+export function createCohereScenarioEngine(document?: ScenarioDocument): CohereScenarioEngine {
+  return new ScenarioEngine(cohereScenarioAdapter, document);
+}
+
+/**
+ * Realize a fired handler's respond payload into a vendor-faithful Cohere assistant turn.
+ *
+ * Scripted tool-call ids are derived from the CALL ITSELF (name + arguments + position), so they
+ * are stable across runs and distinct between different scripted calls. A module-level counter
+ * would make them depend on how many engines had run in the process — not a property a replay can
+ * rely on. An explicit `id` on the handler always wins.
+ */
+export function realizeCohereRespond(respond: CohereScenarioRespond): ScriptedResult {
+  const toolCalls: CohereToolCallV2[] = [];
+  for (const tc of respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : []) {
+    toolCalls.push({
+      id: tc.id ?? toolCallId(`scripted|${tc.name}|${JSON.stringify(tc.arguments)}|${toolCalls.length}`),
+      type: 'function',
+      function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+    });
+  }
+  const content: CohereAssistantContentItem[] = [];
+  if (respond.thinking !== undefined) content.push({ type: 'thinking', thinking: respond.thinking });
+  if (respond.text !== undefined) content.push({ type: 'text', text: respond.text });
+  return {
+    content,
+    toolCalls,
+    ...(respond.toolPlan !== undefined ? { toolPlan: respond.toolPlan } : {}),
+    finishReason: respond.finishReason ?? (toolCalls.length ? 'TOOL_CALL' : 'COMPLETE'),
+  };
+}

package/src/cohere-server.ts

@@ -0,0 +1,195 @@
+// Cohere twin HTTP server — serve the full Cohere twin handler over HTTP so the real `cohere-ai`
+// client (`new CohereClientV2({ token, environment: 'http://127.0.0.1:<port>' })`) and the real
+// `@ai-sdk/cohere` provider (`createCohere({ baseURL: 'http://127.0.0.1:<port>/v2' })`) work
+// UNMODIFIED. Writable by default; pass readOnly to reject mutations (D3).
+//
+// ── TWO STREAM WIRES, because Cohere has two ────────────────────────────────────────────
+// `POST /v2/chat` with `stream:true` is SSE: `data: <json>\n\n` frames terminated by
+// `data: [DONE]\n\n` — cohere-ai constructs its `core.Stream` for this endpoint with
+// `responseType: "sse"` and `eventShape: { type: "sse", streamTerminator: "[DONE]" }`.
+// `POST /v1/chat` with `stream:true` is NEWLINE-DELIMITED JSON — a different wire on the same
+// host, which is why the framing is chosen per endpoint rather than globally.
+//
+// Multipart: `POST /v1/datasets` is `multipart/form-data` with the dataset name and type in the
+// QUERY string. The server folds the form into the handler's JSON contract so the handler stays a
+// pure JSON function (offline-testable).
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createCohereTwinFetch` and the
+// SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): the two stream wires and the multipart adaptation genuinely
+// exceed the common shape — openai-server.ts is the reference for that lane.
+import { serveHttp } from '@volter/world-core';
+import { twinManifest, worldNow } from '@volter/world-core';
+import { createCohereScenarioEngine, loadCohereScenarioDocument, type CohereScenarioEngine } from './cohere-scenario.ts';
+import { handleCohereTwinRequest } from './cohere-twin.ts';
+import type { SseEvent } from './cohere-types.ts';
+
+function wantsStream(body: string): boolean {
+  if (!body) return false;
+  try {
+    return (JSON.parse(body) as { stream?: unknown })?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+/** v2's SSE framing. */
+function encodeSse(event: SseEvent): string {
+  if (event.done) return 'data: [DONE]\n\n';
+  return `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+/** v1's newline-delimited-JSON framing. There is no `[DONE]` sentinel on this wire — the final
+ *  object's `is_finished: true` is the terminator. */
+function encodeNdjson(event: SseEvent): string {
+  if (event.done) return '';
+  return `${JSON.stringify(event.data)}\n`;
+}
+
+async function multipartToJson(request: Request): Promise<string> {
+  try {
+    const form = await request.formData();
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of form.entries()) {
+      if (typeof value === 'string') out[key] = value;
+    }
+    const file = form.get('data') ?? form.get('file');
+    if (file instanceof File) {
+      out.filename = file.name || 'upload';
+      out.content = await file.text();
+    } else if (typeof file === 'string') {
+      // A multipart part is a `File` only when its Content-Disposition carries a `filename`.
+      // cohere-ai's `appendFile` omits it whenever the value is not a named value (a Buffer, a
+      // `fs.createReadStream`, an unnamed Blob), in which case Bun yields a plain STRING. Before
+      // the required-file rule that was harmless; after it, the twin would 400 "the data file is
+      // required" on a create the vendor accepts — a leniency turned into a false refusal
+      // (§9 round two, m-R2.4).
+      out.filename = 'upload';
+      out.content = file;
+    }
+    return JSON.stringify(out);
+  } catch {
+    return '{}';
+  }
+}
+
+/** Options every Cohere-twin HTTP surface needs, independent of who owns the socket. */
+export interface CohereTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+export function createCohereTwinFetch(options: CohereTwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  // Scenario scripting (cohere-scenario.ts): a JSON handlers file — via the scenarioPath option or
+  // the TWIN_COHERE_SCENARIO env var — scripts `POST /v2/chat`. Loaded ONCE at construction (a
+  // malformed file fails loudly here, never silently); the session (call counter + fired `once`
+  // handlers) lives for the fetch's lifetime.
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_COHERE_SCENARIO;
+  const scenarioEngine: CohereScenarioEngine | undefined = scenarioPath ? createCohereScenarioEngine(loadCohereScenarioDocument(scenarioPath)) : undefined;
+  return async function cohereTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, unauthenticated —
+    // education ships inside the twin; an in-world agent has only HTTP. Read-only by design:
+    // the handler FILE is the only write surface, so a running world is never mutated.
+    if (request.method === 'GET' && cleanPath === '/twin') {
+      return Response.json(twinManifest({
+        vendor: 'cohere',
+        twinOf: 'Cohere API (v1 + v2)',
+        stateSentence: 'Seed datasets, connectors and embed jobs through the ordinary API with any bearer token; the tokenizer vocabulary is learned by POST /v1/tokenize.',
+        behaviorSentence: "Chat completions are scripted by MSW-shaped handlers in the world dir (handlers/cohere.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|nthCall}, respond:{text|thinking|toolPlan|toolCalls, finishReason? | error:{type:rate_limit|api_error|service_unavailable}}, once?, scope?, phase?}. Unmatched requests answer a labeled stub and ledger the miss with its features.",
+        exampleHandler: { on: { userTextIncludes: 'refund', hasTool: 'create_job' }, respond: { toolCalls: { name: 'create_job', arguments: { title: 'Refund order' } } }, once: true },
+        engine: scenarioEngine as never,
+      }));
+    }
+    if (request.method === 'GET' && cleanPath === '/twin/scenario') {
+      return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'cohere', handlers: [], misses: 0, recentMisses: [] });
+    }
+
+    const path = url.pathname + (url.search || '');
+    const contentType = request.headers.get('content-type') ?? '';
+
+    // Pass the (lower-cased) request headers through so the handler can model auth (401)
+    // exactly as the real API sees it.
+    const headers: Record<string, string> = {};
+    request.headers.forEach((v, k) => { headers[k.toLowerCase()] = v; });
+
+    let body = '';
+    if (request.method !== 'GET') {
+      body = contentType.includes('multipart/form-data') ? await multipartToJson(request) : await request.text();
+    }
+
+    try {
+      // Streaming POST → RUN FIRST, THEN CHOOSE THE RESPONSE.
+      //
+      // The handler is deliberately socket-free (it writes into an injected sink), so buffering
+      // its events costs nothing and buys the thing that matters: the STATUS is known BEFORE the
+      // response is constructed. Opening a 200 `text/event-stream` and only then discovering a
+      // 400 would push the error body out as a lone SSE frame, and cohere-ai's `core.Stream`
+      // would try to parse a `{message}` error as a `V2ChatStreamResponse` instead of raising
+      // the typed `BadRequestError` the caller catches. Real Cohere sends response headers
+      // before any body and returns a genuine 4xx here.
+      const isV2Stream = request.method.toUpperCase() === 'POST' && cleanPath === '/v2/chat' && wantsStream(body);
+      const isV1Stream = request.method.toUpperCase() === 'POST' && cleanPath === '/v1/chat' && wantsStream(body);
+      if (!readOnly && (isV2Stream || isV1Stream)) {
+        const events: SseEvent[] = [];
+        const { status, body: out, headers: extra } = await handleCohereTwinRequest({
+          method: request.method, path, body, readOnly, headers, occurredAt: worldNow(),
+          ...(options.root !== undefined ? { root: options.root } : {}), sseSink: (e) => events.push(e),
+          ...(scenarioEngine ? { scenarioEngine } : {}),
+        });
+        if (status >= 400) {
+          // A real, catchable HTTP error — never a 200 stream carrying an error payload.
+          return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(extra ?? {}) } });
+        }
+        const enc = new TextEncoder();
+        const frame = isV2Stream ? encodeSse : encodeNdjson;
+        const stream = new ReadableStream<Uint8Array>({
+          start(controller) {
+            for (const e of events) {
+              const text = frame(e);
+              if (text) controller.enqueue(enc.encode(text));
+            }
+            controller.close();
+          },
+        });
+        return new Response(stream, {
+          status,
+          headers: {
+            'content-type': isV2Stream ? 'text/event-stream; charset=utf-8' : 'application/stream+json; charset=utf-8',
+            'cache-control': 'no-cache',
+            ...(extra ?? {}),
+          },
+        });
+      }
+
+      const { status, body: out, headers: extra } = await handleCohereTwinRequest({
+        method: request.method, path, body, readOnly, headers,
+        occurredAt: worldNow(),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+      });
+      return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(extra ?? {}) } });
+    } catch (error) {
+      // Never let an exception escape the fetch callback: under `bun test` a thrown handler error
+      // is reported as "unhandled between tests" and can prevent later test registration,
+      // obscuring the original defect. Answer the vendor's own error envelope.
+      return new Response(JSON.stringify({ message: `twin handler error: ${error instanceof Error ? error.message : String(error)}` }), {
+        status: 500,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+  };
+}
+
+export async function createCohereTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createCohereTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}