@volter/twin-cohere 0.1.0

package/dist/src/cohere-models.js

@@ -0,0 +1,73 @@
+// 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 } from "./cohere-types.js";
+/**
+ * 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 = [
+    // ── 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, endpoints, contextLength) {
+    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) {
+    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, endpoint) {
+    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/dist/src/cohere-scenario.d.ts

@@ -0,0 +1,57 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import { type CohereAssistantContentItem, type CohereFinishReason, type CohereMessageV2, type CohereToolCallV2 } from './cohere-types.js';
+/** 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;
+};
+/** The pack's scenario vocabulary + feature bag. One adapter instance, shared. */
+export declare const cohereScenarioAdapter: PackScenarioAdapter<CohereScenarioRequest>;
+/** Load + strictly validate a handlers document (handlers/cohere.json). A broken file fails
+ *  server startup loudly; it never falls back or misfires silently. */
+export declare function loadCohereScenarioDocument(path: string): ScenarioDocument;
+export declare function createCohereScenarioEngine(document?: ScenarioDocument): CohereScenarioEngine;
+/**
+ * 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 declare function realizeCohereRespond(respond: CohereScenarioRespond): ScriptedResult;

package/dist/src/cohere-scenario.js

@@ -0,0 +1,176 @@
+// 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, ScenarioError, ScenarioEngine } from '@volter/world-core';
+import { contentToText, lastUserText, toolCallId, toolNames } from "./cohere-stub.js";
+import { COHERE_FINISH_REASONS } from "./cohere-types.js";
+const RESPOND_KEYS = new Set(['text', 'thinking', 'toolPlan', 'toolCalls', 'finishReason', 'error']);
+const FINISH_REASONS = new Set(COHERE_FINISH_REASONS);
+const ERROR_TYPES = new Set(['rate_limit', 'api_error', 'service_unavailable']);
+const nonEmptyString = (cond) => 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) {
+    const names = new Set();
+    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 = {
+    vendor: 'cohere',
+    features: (req) => ({
+        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']) {
+            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;
+        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;
+                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;
+            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) {
+    let parsed;
+    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) {
+    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) {
+    const toolCalls = [];
+    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 = [];
+    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/dist/src/cohere-server.d.ts

@@ -0,0 +1,16 @@
+/** Options every Cohere-twin HTTP surface needs, independent of who owns the socket. */
+export interface CohereTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}
+export declare function createCohereTwinFetch(options: CohereTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createCohereTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/cohere-server.js

@@ -0,0 +1,184 @@
+// 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 } from "./cohere-scenario.js";
+import { handleCohereTwinRequest } from "./cohere-twin.js";
+function wantsStream(body) {
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body)?.stream === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** v2's SSE framing. */
+function encodeSse(event) {
+    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) {
+    if (event.done)
+        return '';
+    return `${JSON.stringify(event.data)}\n`;
+}
+async function multipartToJson(request) {
+    try {
+        const form = await request.formData();
+        const out = {};
+        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 '{}';
+    }
+}
+export function createCohereTwinFetch(options) {
+    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 = scenarioPath ? createCohereScenarioEngine(loadCohereScenarioDocument(scenarioPath)) : undefined;
+    return async function cohereTwinFetch(request) {
+        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,
+            }));
+        }
+        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 = {};
+        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 = [];
+                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({
+                    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) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createCohereTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/cohere-stub.d.ts

@@ -0,0 +1,119 @@
+import type { CohereMessageV2, CohereToolCallV2 } from './cohere-types.js';
+/** A small deterministic 32-bit hash (FNV-1a) of a string — the seed for every stub below. */
+export declare function fnv1a(text: string): number;
+/**
+ * A deterministic UUID-v4-SHAPED id. Cohere returns UUIDs for `id` / `generation_id` /
+ * `response_id`, so the twin returns something a caller parsing a UUID accepts — derived from the
+ * request rather than from `crypto.randomUUID`, because a random id would make the served response
+ * non-deterministic and break replay (CLAUDE.md, serve-path determinism).
+ */
+export declare function cohereId(seed: string): string;
+/** Deterministic token estimate: ~1 token per 4 chars. Never zero for non-empty text. */
+export declare function estimateTokens(text: string): number;
+/** Flatten a v2 message's content (string OR content-part array) to its text. Cohere's parts are
+ *  `{type:'text',text}`, `{type:'image_url',image_url}` and `{type:'document',document}`; only the
+ *  first contributes literal text, the rest contribute their JSON length so the count stays
+ *  deterministic and reflects payload size. */
+export declare function contentToText(content: CohereMessageV2['content']): string;
+/** Deterministic input-token count for a full v2 message list. */
+export declare function countInputTokens(messages: CohereMessageV2[]): number;
+/** The last user turn's text — the thing the stub echoes. */
+export declare function lastUserText(messages: CohereMessageV2[]): string;
+/**
+ * The deterministic stub ASSISTANT text. Unmistakably a twin stub: it carries the
+ * `[twin-stub:<model>]` marker and echoes the prompt, so no caller can mistake it for real model
+ * output. Deterministic for a given prompt → assertable in tests.
+ */
+export declare function stubAssistantText(messages: CohereMessageV2[], model: string): string;
+/** The v1 chat stub — v1 takes a single `message` string rather than a message list. */
+export declare function stubV1Text(message: string, model: string): string;
+/** The `tool_plan` a real Cohere model emits alongside tool calls — a chain-of-thought style
+ *  reflection. Stubbed deterministically and labeled. */
+export declare function stubToolPlan(toolNames: string[]): string;
+/** Every declared tool's name, in declaration order. */
+export declare function toolNames(tools: unknown): string[];
+/**
+ * A deterministic stub argument STRING for a tool. Real models emit arguments that validate
+ * against the tool's declared JSON schema, so the twin synthesizes a deterministic object
+ * containing every declared property with a type-appropriate placeholder. Cohere's `arguments` is
+ * a STRING on the wire (`ToolCallV2Function.arguments`), like OpenAI's.
+ */
+export declare function stubToolArguments(tool: unknown): string;
+/**
+ * When tools are provided, a real Cohere model may answer with `tool_calls` and
+ * `finish_reason: 'TOOL_CALL'`. The stub deterministically "calls" the tool selected by
+ * `forcedName` (a named `tool_choice`) or the FIRST provided tool.
+ *
+ * The id is SEEDED FROM THE REQUEST, never from a module-level counter: a counter makes the id
+ * depend on how many completions the process happened to serve, which is not a property a replay
+ * can rely on, and hands two different turns the same id inside one process. Hashing the
+ * conversation keeps replay byte-identical while making ids differ between turns.
+ */
+export declare function stubToolCall(tools: unknown, seed: string, index: number, forcedName?: string): CohereToolCallV2 | null;
+/** Cohere's tool-call ids are UUID-shaped, like its response ids. */
+export declare function toolCallId(seed: string): string;
+/**
+ * A deterministic, reproducible L2-normalized pseudo-embedding for `text`. NOT a real embedding —
+ * the values carry no semantic meaning; only the SHAPE, the dimensionality and the DETERMINISM are
+ * faithful. Same text → same vector, in every process
+ * and every state root.
+ */
+export declare function pseudoEmbedding(text: string, dimensions: number): number[];
+/**
+ * Quantize a float vector into one of Cohere's non-float `embedding_types`. The vendor returns the
+ * SAME vector under every requested type, quantized — so the twin derives all of them from the one
+ * pseudo-vector rather than hashing separately per type, which is what makes the types agree the
+ * way a real response's do.
+ *   • int8   — signed 8-bit, [-128, 127]
+ *   • uint8  — unsigned 8-bit, [0, 255]
+ *   • binary/ubinary — one BIT per dimension, packed 8 to a byte (so the array is dim/8 long),
+ *     signed and unsigned respectively; this packing is why a binary embedding is 1/32 the size.
+ */
+export declare function quantizeEmbedding(floats: number[], type: 'int8' | 'uint8' | 'binary' | 'ubinary'): number[];
+/** Base64 of the float vector's little-endian float32 bytes — Cohere's `base64` embedding type. */
+export declare function base64Embedding(floats: number[]): string;
+/** The output dimensionality Cohere's embed models produce, by model id. `embed-v4.0` accepts an
+ *  explicit `output_dimension` from the closed set {256, 512, 1024, 1536}; the v3 models are fixed
+ *  (1024 for the full models, 384 for the `light` ones). */
+export declare function embedDimensions(model: string): number;
+/** `embed-v4.0`'s documented closed `output_dimension` set. A literal here, so the handler's
+ *  rejection of anything outside it is checkable against the vendor's documented set. */
+export declare const COHERE_OUTPUT_DIMENSIONS: readonly [256, 512, 1024, 1536];
+/**
+ * Score one document against a query. NOT the real cross-encoder — a deterministic
+ * token-overlap ratio, so the ORDERING is explainable and reproducible while carrying no learned
+ * relevance. Always in [0, 1], the range the vendor's `relevance_score` occupies.
+ *
+ * A tiny hash term breaks ties deterministically, so two documents with identical overlap still
+ * get a stable, total order rather than an order that depends on sort stability.
+ */
+export declare function rerankScore(query: string, document: string): number;
+/**
+ * Deterministically score `input` across `labels`. NOT the real classifier — the confidence is a
+ * hash-derived value per (input, label), normalized so the confidences SUM TO 1 the way a real
+ * single-label classification's do. The prediction is the argmax.
+ */
+export declare function classifyText(input: string, labels: string[]): {
+    prediction: string;
+    confidences: number[];
+};
+/**
+ * Segment text the way the twin's tokenizer does. NOT Cohere's BPE (vendoring the published
+ * tokenizer JSON is `cohere.tokenize.bpe_vocabulary`, a todo) — a deterministic word-with-trailing-whitespace
+ * split, chosen so that JOINING the segments restores the input EXACTLY, including runs of spaces
+ * and newlines. That exact-join property is what lets `detokenize(tokenize(t)) === t` hold, which
+ * is the property a caller actually depends on.
+ */
+export declare function segmentText(text: string): string[];
+/**
+ * The PREFERRED token id for a segment — a pure function of the segment, so the same text
+ * tokenizes to the same ids in every process and every state root.
+ *
+ * This is only a preference, not the answer: two different segments can hash to the same value,
+ * and a vocabulary that silently let the second one overwrite the first would make `detokenize`
+ * return the WRONG text for the earlier one. The handler resolves that by probing upward over the
+ * vocabulary it has already observed (`cohere-twin.ts`, `assignToken`) — deterministic given the
+ * stored state, which is what a twin's determinism means. Ids start at 1: Cohere's token ids are
+ * positive, and 0 is reserved so an unset field can never read as a valid token.
+ */
+export declare function preferredTokenId(segment: string): number;