@volter/twin-cohere 0.1.0 → 0.1.1

package/README.md

@@ -54,6 +54,17 @@ modeled here and asserted by a named capability:
 | `check-api-key` | a **POST**, despite the name | a GET |
 | streaming | v2 is SSE terminated by `data: [DONE]`; v1 is newline-delimited JSON tagged `event_type` | one wire |
 
+**The exception is the Compatibility API**, `https://api.cohere.ai/compatibility/v1`
+([docs](https://docs.cohere.com/docs/compatibility-api)), where Cohere speaks OpenAI's wire, `choices` and all:
+`POST /compatibility/v1/chat/completions` answers `chat.completion` (and streams `chat.completion.chunk` frames ending
+`[DONE]`, with a usage chunk under `stream_options.include_usage`) for Cohere's models, so an application built on the
+OpenAI SDK reaches Cohere by changing its base URL. The twin serves it from the same turn as `/v2/chat` (stub, tool
+decision and handlers) in OpenAI's envelope; its embeddings, audio, `response_format` and `reasoning_effort` are
+`todo`. Where the docs stop, the twin decides, and none of it is probed against the live API: the parameters the docs
+name unsupported are ignored (the docs do not say whether Cohere refuses or ignores them), refusals keep the host's
+bare `{message}` body, `ERROR` and `TIMEOUT` finish as `stop` (OpenAI's wire has no error finish), and a tool turn
+carries no `tool_plan`.
+
 ## The generative-stub design (be honest)
 
 The twin **cannot run the model** — there are no weights here. So every generative endpoint returns
@@ -106,8 +117,9 @@ top-down from `cohere-ai@8.1.0`'s own operation inventory — every `client.<sub
 client module.
 
 **One unit, throughout:** those **45 SDK methods** resolve to **42 distinct (method, path)
-operations** over 32 paths. The twin serves **27** of the 42 — the same 27 pairs that make up
-`COHERE_ROUTER_SURFACE` and the conformance snapshot. The **15** it does not: `POST /v1/generate`,
+operations** over 32 paths. The twin serves **27** of the 42. `COHERE_ROUTER_SURFACE` and the conformance snapshot hold **28**
+pairs: those 27, and the Compatibility API's chat completions, which is outside `cohere-ai`'s denominator (it is
+reached with the OpenAI SDK). The **15** it does not: `POST /v1/generate`,
 `POST /v1/summarize`, `POST /v2/parse`, `POST /v2/audio/transcriptions`, the four `/v2/batches`
 operations and the seven `/v1/finetuning/*` operations — every one enumerated as a `todo`, because a
 denominator that omitted them would be a self-portrait rather than a measurement. Run
@@ -198,8 +210,10 @@ surface.
 
 ## Interception and world wiring
 
-- **Hosts:** exactly one — `api.cohere.com`. That is the only entry in `cohere-ai`'s
-  `CohereEnvironment`, and `@ai-sdk/cohere`'s default `baseURL` is that host plus `/v2`. Declared on
+- **Hosts:** `api.cohere.com`, the only entry in `cohere-ai`'s `CohereEnvironment` and
+  `@ai-sdk/cohere`'s default `baseURL` (plus `/v2`), and `api.cohere.ai`, Cohere's earlier host,
+  which its Compatibility API documents and applications speaking OpenAI's wire address
+  (LibreChat's own Cohere constant is `https://api.cohere.ai/v1`). Declared on
   the pack descriptor, so `volter-world` routes an unmodified SDK's traffic here with zero edits.
 - **Endpoint env: none, and that is a ruling rather than an omission.** Neither SDK reads a base-URL
   environment variable — `cohere-ai` takes the override as the `baseUrl`/`environment` **constructor**

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

@@ -9,6 +9,6 @@ import { type CapabilityReport, type CapabilitySpec } from '@volter/world-toolin
  * `connectors` is Cohere's PRODUCT (its RAG connector registry); `connector` is this twin's
  * pull/push plane. Two different things that unfortunately share a word; both are real areas.
  */
-export declare const COHERE_AREAS: readonly ["audio", "auth", "batches", "chat", "chat_v1", "classify", "conformance", "connector", "connectors", "datasets", "deployments", "determinism", "embed", "embed_jobs", "errors", "finetuning", "generate", "models", "parse", "rerank", "summarize", "tokenize"];
+export declare const COHERE_AREAS: readonly ["audio", "auth", "batches", "chat", "chat_v1", "compat", "classify", "conformance", "connector", "connectors", "datasets", "deployments", "determinism", "embed", "embed_jobs", "errors", "finetuning", "generate", "models", "parse", "rerank", "summarize", "tokenize"];
 export declare const COHERE_CAPABILITIES: CapabilitySpec[];
 export declare function cohereCapabilities(): Promise<CapabilityReport>;

package/dist/src/cohere-capabilities.js

@@ -52,7 +52,7 @@ import { checkCohereConformance } from "./cohere-conformance.js";
 import { cohereRequestForAction, fullSyncCohere, liveCohereExecute, mapConnector, mapDataset, mapEmbedJob, pollTimestamp, pushPendingCohereActions, syncCohereFromReal, unpushableReason, } from "./cohere-connector.js";
 import { COHERE_ENDPOINTS } from "./cohere-models.js";
 import { createCohereScenarioEngine } from "./cohere-scenario.js";
-import { handleCohereTwinRequest } from "./cohere-twin.js";
+import { compatMessages, handleCohereTwinRequest } from "./cohere-twin.js";
 /** A FIXED `occurredAt` keeps ids/timestamps deterministic across runs. */
 const PINNED_AT = '2026-08-31T12:00:00.000Z';
 /** Run a sequence of real Cohere requests against an ISOLATED root; return all responses. The
@@ -178,6 +178,7 @@ export const COHERE_AREAS = [
     'batches',
     'chat',
     'chat_v1',
+    'compat',
     'classify',
     'conformance',
     'connector',
@@ -266,6 +267,21 @@ export const COHERE_CAPABILITIES = [
             && none.body.message?.tool_calls === undefined
             && typeof none.body.message?.content?.[0]?.text === 'string';
     })),
+    done('cohere.chat.tool_result_answered', 'chat', 'v2 chat: a turn answering a tool result is words, not another tool call, unless tool_choice is REQUIRED', 'api', 'core', () => withRoot(async (h) => {
+        const first = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL] }) });
+        const call = first.body.message?.tool_calls?.[0];
+        if (!call)
+            return false;
+        const loop = [
+            { role: 'user', content: 'weather?' },
+            { role: 'assistant', tool_calls: [call], tool_plan: first.body.message.tool_plan },
+            { role: 'tool', tool_call_id: call.id, content: [{ type: 'document', document: { data: '{"temp":20}' } }] },
+        ];
+        const answered = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], messages: loop }) });
+        const insisted = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], messages: loop, tool_choice: 'REQUIRED' }) });
+        return answered.body.finish_reason === 'COMPLETE' && typeof answered.body.message?.content?.[0]?.text === 'string'
+            && insisted.body.finish_reason === 'TOOL_CALL';
+    })),
     done('cohere.chat.thinking', 'chat', 'v2 chat: `thinking: {type:enabled}` prepends a `thinking` content item', 'api', 'common', () => withRoot(async (h) => {
         const off = await h({ m: 'POST', p: '/v2/chat', b: CHAT() });
         const on = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ thinking: { type: 'enabled' } }) });
@@ -323,6 +339,94 @@ export const COHERE_CAPABILITIES = [
         const end = events.find((e) => e.data?.type === 'message-end').data;
         return end.delta.finish_reason === 'TOOL_CALL';
     })),
+    // ══ THE COMPATIBILITY API — OpenAI's wire at api.cohere.ai/compatibility/v1 ════════════
+    done('cohere.compat.chat_completions', 'compat', 'Compatibility API: POST /compatibility/v1/chat/completions answers OpenAI\'s chat.completion envelope for a Cohere model', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT() });
+        if (!ok(r))
+            return false;
+        const b = r.body;
+        // OpenAI's keys PRESENT, Cohere v2's ABSENT: the same turn in the other wire, not the v2 body relabelled.
+        if (b.object !== 'chat.completion' || typeof b.created !== 'number' || b.model !== 'command-a-03-2025')
+            return false;
+        if (b.message !== undefined || b.finish_reason !== undefined)
+            return false;
+        const c = b.choices?.[0];
+        if (b.choices.length !== 1 || c.index !== 0 || c.message?.role !== 'assistant' || c.finish_reason !== 'stop')
+            return false;
+        if (typeof c.message.content !== 'string' || !c.message.content.includes('[twin-stub:command-a-03-2025]') || !c.message.content.includes('hello twin'))
+            return false;
+        // The flat usage, whose counts move with the input (a constant would pass the shape check).
+        const long = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'x'.repeat(400) }] }) });
+        const u = b.usage;
+        const lu = long.body.usage;
+        return u.total_tokens === u.prompt_tokens + u.completion_tokens && lu.prompt_tokens > u.prompt_tokens * 5;
+    })),
+    done('cohere.compat.tool_calls', 'compat', 'Compatibility API: tools → OpenAI `tool_calls` with finish_reason tool_calls; tool_choice none forbids it; the tool result is answered in words', 'api', 'core', () => withRoot(async (h) => {
+        const call = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL] }) });
+        const none = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL], tool_choice: 'none' }) });
+        const c = call.body.choices?.[0];
+        if (c?.finish_reason !== 'tool_calls' || c.message?.content !== null)
+            return false;
+        const tc = c.message.tool_calls?.[0];
+        if (tc?.type !== 'function' || tc.function?.name !== 'get_weather' || typeof tc.function.arguments !== 'string')
+            return false;
+        if (none.body.choices?.[0]?.finish_reason !== 'stop' || none.body.choices[0].message.tool_calls !== undefined)
+            return false;
+        // OpenAI's tool loop: the assistant's tool call, then the `tool` result — the next turn is words, not another call.
+        const answered = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL], messages: [
+                    { role: 'user', content: 'weather?' },
+                    { role: 'assistant', content: null, tool_calls: [tc] },
+                    { role: 'tool', tool_call_id: tc.id, content: '{"temp":20}' },
+                ] }) });
+        return ok(answered) && typeof answered.body.choices?.[0]?.message?.content === 'string';
+    })),
+    done('cohere.compat.stream', 'compat', 'Compatibility API streaming: chat.completion.chunk frames reassemble the unary answer, end with the finish reason, a usage chunk when stream_options asks, then [DONE]', 'api', 'core', () => withStream('/compatibility/v1/chat/completions', CHAT({ stream: true, stream_options: { include_usage: true } }), (events, final) => {
+        const frames = events.filter((e) => !e.done).map((e) => e.data);
+        if (events[events.length - 1]?.done !== true)
+            return false;
+        if (!frames.every((f) => f.object === 'chat.completion.chunk' && f.id === final.body.id))
+            return false;
+        if (frames[0].choices[0].delta.role !== 'assistant')
+            return false;
+        const last = frames[frames.length - 1];
+        // the usage-only chunk: no choices, the unary usage
+        if (last.choices.length !== 0 || last.usage?.total_tokens !== final.body.usage.total_tokens)
+            return false;
+        const finishing = frames.filter((f) => f.choices[0]?.finish_reason);
+        if (finishing.length !== 1 || finishing[0].choices[0].finish_reason !== 'stop')
+            return false;
+        const joined = frames.map((f) => f.choices[0]?.delta?.content ?? '').join('');
+        return joined === final.body.choices[0].message.content;
+    })),
+    done('cohere.compat.stream_no_usage_unasked', 'compat', 'Compatibility API streaming: no usage chunk unless stream_options.include_usage', 'api', 'common', () => withStream('/compatibility/v1/chat/completions', CHAT({ stream: true }), (events) => events.length > 2 && events.filter((e) => !e.done).every((e) => e.data.usage === undefined && e.data.choices.length === 1))),
+    done('cohere.compat.refusals', 'compat', 'Compatibility API: a model Cohere does not serve, a missing model, an empty messages array and an unknown tool_choice are refused; the parameters the docs name unsupported are ignored', 'api', 'common', () => withRoot(async (h) => {
+        const P = '/compatibility/v1/chat/completions';
+        const wrongModel = await h({ m: 'POST', p: P, b: CHAT({ model: 'gpt-4o' }) });
+        const noModel = await h({ m: 'POST', p: P, b: { messages: [{ role: 'user', content: 'x' }] } });
+        const empty = await h({ m: 'POST', p: P, b: CHAT({ messages: [] }) });
+        const badChoice = await h({ m: 'POST', p: P, b: CHAT({ tool_choice: 'sometimes' }) });
+        const unsupported = await h({ m: 'POST', p: P, b: CHAT({ n: 2, logit_bias: { 1: 1 }, store: true, parallel_tool_calls: false }) });
+        return wrongModel.status === 404 && bareError(noModel, 400) && bareError(empty, 400) && bareError(badChoice, 400) && ok(unsupported);
+    })),
+    done('cohere.compat.named_tool_choice', 'compat', 'Compatibility API: tool_choice naming a function calls that function, not the first declared', 'api', 'common', () => withRoot(async (h) => {
+        const OTHER = { type: 'function', function: { name: 'get_time', parameters: { type: 'object', properties: { zone: { type: 'string' } } } } };
+        const named = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL, OTHER], tool_choice: { type: 'function', function: { name: 'get_time' } } }) });
+        const unnamed = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL, OTHER] }) });
+        return named.body.choices?.[0]?.message?.tool_calls?.[0]?.function?.name === 'get_time'
+            && unnamed.body.choices?.[0]?.message?.tool_calls?.[0]?.function?.name === 'get_weather';
+    })),
+    done('cohere.compat.developer_role', 'compat', 'Compatibility API: a `developer` message is a system message; an unknown role is refused', 'api', 'niche', () => withRoot(async (h) => {
+        const converted = compatMessages([{ role: 'developer', content: 'be brief' }, { role: 'user', content: 'hi' }]);
+        if (typeof converted === 'string' || converted[0]?.role !== 'system' || converted[0]?.content !== 'be brief')
+            return false;
+        const dev = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ messages: [{ role: 'developer', content: 'be brief' }, { role: 'user', content: 'hi' }] }) });
+        const bad = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ messages: [{ role: 'narrator', content: 'x' }] }) });
+        return ok(dev) && bareError(bad, 400);
+    })),
+    todo('cohere.compat.embeddings', 'compat', 'Compatibility API: POST /compatibility/v1/embeddings (input, model, encoding_format) in OpenAI\'s list-of-embeddings envelope', 'api', 'common'),
+    todo('cohere.compat.audio_transcriptions', 'compat', 'Compatibility API: POST /compatibility/v1/audio/transcriptions', 'api', 'niche'),
+    todo('cohere.compat.reasoning_effort', 'compat', 'Compatibility API: reasoning_effort (none / high) turns Cohere\'s thinking off and on', 'api', 'common'),
+    todo('cohere.compat.response_format', 'compat', 'Compatibility API: response_format json_object / json_schema answers JSON content', 'api', 'common'),
     done('cohere.chat.stream_needs_transport', 'chat', 'v2 chat: `stream:true` with no streaming transport is refused, not silently unary', 'api', 'niche', () => withRoot(async (h) => {
         const r = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ stream: true }) });
         return bareError(r, 400) && message(r).includes('streaming transport');
@@ -1819,7 +1923,7 @@ export const COHERE_CAPABILITIES = [
     // ══ CONFORMANCE ══════════════════════════════════════════════════════════════════════
     done('cohere.conformance.probes', 'conformance', 'Conformance: every claimed endpoint is probed for a live OUTCOME, not just a dispatch', 'api', 'core', async () => verifyBoundary('cohere.conformance', async () => {
         const report = await checkCohereConformance();
-        return report.ok && report.claimed === 27 && report.checksRun >= 58 && report.violations.length === 0;
+        return report.ok && report.claimed === 28 && report.checksRun >= 60 && report.violations.length === 0;
     })),
     done('cohere.conformance.scenario_engine_is_the_kernel', 'conformance', 'Scenario scripting runs on THE kernel engine with a pack adapter (never a bespoke one)', 'api', 'common', () => verifyBoundary('cohere.scenario_kernel', async () => {
         const engine = createCohereScenarioEngine();

package/dist/src/cohere-conformance.js

@@ -39,6 +39,7 @@ export const COHERE_TWIN_SNAPSHOT = [
     'POST /v2/embed',
     'POST /v2/rerank',
     'POST /v1/chat',
+    'POST /compatibility/v1/chat/completions',
     'POST /v1/embed',
     'POST /v1/rerank',
     'POST /v1/classify',
@@ -87,6 +88,17 @@ const PROBES = [
             && b.usage?.billed_units?.input_tokens > 0 && b.usage?.tokens?.input_tokens === b.usage.billed_units.input_tokens
             && b.usage?.tokens?.output_tokens > 0,
     },
+    {
+        claim: 'POST /compatibility/v1/chat/completions',
+        request: () => ({ method: 'POST', path: '/compatibility/v1/chat/completions', body: CHAT }),
+        status: [200],
+        // OpenAI's envelope on the Compatibility API — the very keys the v2 probe above asserts ABSENT.
+        expect: (b) => isObj(b) && b.object === 'chat.completion' && typeof b.created === 'number'
+            && b.choices?.[0]?.message?.role === 'assistant'
+            && String(b.choices[0].message.content).includes('[twin-stub:command-a-03-2025]')
+            && b.choices[0].finish_reason === 'stop'
+            && b.usage?.total_tokens === b.usage?.prompt_tokens + b.usage?.completion_tokens && b.usage.prompt_tokens > 0,
+    },
     {
         claim: 'POST /v1/chat',
         request: () => ({ method: 'POST', path: '/v1/chat', body: { message: 'v1 probe', model: 'command-r-08-2024' } }),

package/dist/src/cohere-server.js

@@ -123,7 +123,9 @@ export function createCohereTwinFetch(options) {
             // 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)) {
+            // The Compatibility API streams OpenAI's `chat.completion.chunk` frames over SSE, `[DONE]`-terminated.
+            const isCompatStream = request.method.toUpperCase() === 'POST' && cleanPath === '/compatibility/v1/chat/completions' && wantsStream(body);
+            if (!readOnly && (isV2Stream || isV1Stream || isCompatStream)) {
                 const events = [];
                 const { status, body: out, headers: extra } = await handleCohereTwinRequest({
                     method: request.method, path, body, readOnly, headers, occurredAt: worldNow(),
@@ -135,7 +137,7 @@ export function createCohereTwinFetch(options) {
                     return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(extra ?? {}) } });
                 }
                 const enc = new TextEncoder();
-                const frame = isV2Stream ? encodeSse : encodeNdjson;
+                const frame = isV2Stream || isCompatStream ? encodeSse : encodeNdjson;
                 const stream = new ReadableStream({
                     start(controller) {
                         for (const e of events) {
@@ -149,7 +151,7 @@ export function createCohereTwinFetch(options) {
                 return new Response(stream, {
                     status,
                     headers: {
-                        'content-type': isV2Stream ? 'text/event-stream; charset=utf-8' : 'application/stream+json; charset=utf-8',
+                        'content-type': isV2Stream || isCompatStream ? 'text/event-stream; charset=utf-8' : 'application/stream+json; charset=utf-8',
                         'cache-control': 'no-cache',
                         ...(extra ?? {}),
                     },

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

@@ -30,6 +30,8 @@ export type ChatV2Args = {
     messages: CohereMessageV2[];
     tools?: unknown;
     toolChoice?: 'REQUIRED' | 'NONE';
+    /** The one tool a caller names (the Compatibility API's `tool_choice: {function:{name}}`; v2 cannot name one). */
+    forcedTool?: string;
     maxTokens?: number;
     stream: boolean;
     thinking: boolean;
@@ -54,6 +56,9 @@ export declare function buildChatV2(args: ChatV2Args, outcome?: ScenarioOutcome)
  * detail a hand-written stream gets wrong.
  */
 export declare function streamChatV2(args: ChatV2Args, sink: SseSink, outcome?: ScenarioOutcome): CohereChatV2Response;
+/** OpenAI's chat messages as the v2 turn reads them (OpenAI's text, image_url, tool and assistant tool_calls shapes are
+ *  v2's own), or the refusal of the first message whose role neither wire has. */
+export declare function compatMessages(messages: unknown[]): CohereMessageV2[] | string;
 /**
  * Every method/path pair the dispatch below branches on. HAND-AUTHORED (the honest limit): a
  * branch added to the handler and to neither this list nor the conformance snapshot is invisible

package/dist/src/cohere-twin.js

@@ -322,10 +322,14 @@ function assistantTurn(args, scripted, missTeach = '') {
     const names = toolNames(args.tools);
     // `tool_choice: 'NONE'` forbids a tool call even when tools are declared — the vendor honours it
     // and so must the twin, or a caller testing the NONE path gets a tool call it explicitly banned.
-    const wantsTool = names.length > 0 && args.toolChoice !== 'NONE';
+    // A model answers a tool's result in words unless the caller insists on another call (REQUIRED):
+    // a stub that called a tool on every turn would never let an application's tool loop end (an
+    // agent runs until its recursion limit), where Cohere's model answers from what the tool returned.
+    const answeringTool = args.messages.at(-1)?.role === 'tool';
+    const wantsTool = names.length > 0 && args.toolChoice !== 'NONE' && (!answeringTool || args.toolChoice === 'REQUIRED');
     const seed = JSON.stringify(args.messages);
     if (wantsTool) {
-        const call = stubToolCall(args.tools, seed, 0);
+        const call = stubToolCall(args.tools, seed, 0, args.forcedTool);
         return { content: [], toolCalls: call ? [call] : [], toolPlan: stubToolPlan(names), finish: 'TOOL_CALL' };
     }
     const content = [];
@@ -421,6 +425,157 @@ function chunkText(text) {
     return out;
 }
 // ════════════════════════════════════════════════════════════════════════════════════════
+// THE COMPATIBILITY API — OpenAI's wire, Cohere's models (docs.cohere.com/docs/compatibility-api)
+// ════════════════════════════════════════════════════════════════════════════════════════
+//
+// Cohere serves OpenAI's Chat Completions wire at `https://api.cohere.ai/compatibility/v1` so an
+// application built on the OpenAI SDK (or one that speaks OpenAI's wire to every provider, as
+// LibreChat's custom endpoints do) reaches Cohere's models by changing base URL, key and model.
+// The docs' code examples all address that base; the parameters they list for chat completions
+// are exactly `model, messages, stream, reasoning_effort, response_format, tools, temperature,
+// max_tokens, stop, seed, top_p, frequency_penalty, presence_penalty`, and they name `store`,
+// `metadata`, `logit_bias`, `top_logprobs`, `n`, `modalities`, `prediction`, `audio`, `service_tier` and
+// `parallel_tool_calls` unsupported.
+//
+// The turn itself is the v2 chat's (`assistantTurn`, scenario handlers included): the same stub,
+// the same tool decision, and the same handler document script both wires. Only the envelope is
+// OpenAI's: `object: 'chat.completion'`, one `choices[0]` with an assistant `message`, the
+// lower-case finish reasons (`stop`, `tool_calls`, `length`), and a flat `usage`
+// (`prompt_tokens`, `completion_tokens`, `total_tokens`); streaming is `chat.completion.chunk`
+// frames over SSE ending `data: [DONE]`, with a usage-only chunk when `stream_options.include_usage`
+// asks for it, as OpenAI's wire has it.
+//
+// Where the documentation stops and the twin decides (not probed against the live API, which
+// needs a key): the parameters the docs name unsupported are ignored, since the docs do not say
+// whether Cohere refuses or ignores them and a refusal would break a client that sends one; the
+// refusals the twin does make (model, messages, role, tool_choice) keep Cohere's bare `{message}`
+// envelope (the host's own); a named `tool_choice` function calls that function; a `developer`
+// message is read as a system message, as OpenAI defines it; `ERROR` and `TIMEOUT` finish as
+// `stop` (OpenAI's wire has no error finish reason); and a tool turn carries no `tool_plan` (the
+// docs' examples show OpenAI's fields only). `reasoning_effort` is not modelled (a `todo`).
+const COMPAT_ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool']);
+const COMPAT_FINISH = {
+    COMPLETE: 'stop', STOP_SEQUENCE: 'stop', MAX_TOKENS: 'length', TOOL_CALL: 'tool_calls', ERROR: 'stop', TIMEOUT: 'stop',
+};
+/** OpenAI's chat messages as the v2 turn reads them (OpenAI's text, image_url, tool and assistant tool_calls shapes are
+ *  v2's own), or the refusal of the first message whose role neither wire has. */
+export function compatMessages(messages) {
+    const out = [];
+    for (const [i, raw] of messages.entries()) {
+        const m = raw;
+        const role = m?.role;
+        if (typeof role !== 'string' || !COMPAT_ROLES.has(role))
+            return `messages[${i}].role must be one of ${[...COMPAT_ROLES].join(', ')}`;
+        const msg = { role: role === 'developer' ? 'system' : role };
+        if (m.content !== undefined && m.content !== null)
+            msg.content = m.content;
+        if (Array.isArray(m.tool_calls) && m.tool_calls.length > 0)
+            msg.tool_calls = m.tool_calls;
+        if (typeof m.tool_call_id === 'string')
+            msg.tool_call_id = m.tool_call_id;
+        out.push(msg);
+    }
+    return out;
+}
+function validateCompatChat(params) {
+    const model = params.model;
+    if (typeof model !== 'string' || model === '')
+        return { error: invalidRequest('model is required') };
+    const messages = params.messages;
+    if (!Array.isArray(messages) || messages.length === 0)
+        return { error: invalidRequest('messages must be a non-empty array') };
+    const converted = compatMessages(messages);
+    if (typeof converted === 'string')
+        return { error: invalidRequest(converted) };
+    const v2Messages = converted;
+    const choice = params.tool_choice;
+    let toolChoice;
+    let forcedTool;
+    if (choice === 'none')
+        toolChoice = 'NONE';
+    else if (choice === 'required')
+        toolChoice = 'REQUIRED';
+    else if (choice !== null && typeof choice === 'object') {
+        toolChoice = 'REQUIRED';
+        const named = choice.function?.name;
+        if (typeof named === 'string')
+            forcedTool = named;
+    }
+    else if (choice !== undefined && choice !== 'auto')
+        return { error: invalidRequest('tool_choice must be none, auto, required or a named function') };
+    if (!modelServes(model, 'chat'))
+        return { error: modelNotFound(model) };
+    const maxTokens = typeof params.max_tokens === 'number' ? params.max_tokens : typeof params.max_completion_tokens === 'number' ? params.max_completion_tokens : undefined;
+    return {
+        args: {
+            v2: {
+                model,
+                messages: v2Messages,
+                ...(params.tools !== undefined ? { tools: params.tools } : {}),
+                ...(toolChoice !== undefined ? { toolChoice } : {}),
+                ...(forcedTool !== undefined ? { forcedTool } : {}),
+                ...(maxTokens !== undefined ? { maxTokens } : {}),
+                stream: params.stream === true,
+                thinking: false,
+            },
+            includeUsage: params.stream_options?.include_usage === true,
+        },
+    };
+}
+/** The OpenAI-shaped completion of one v2 turn. */
+function compatCompletion(args, outcome, occurredAt) {
+    const full = buildChatV2(args, outcome);
+    const text = (full.message.content ?? []).filter((c) => c.type === 'text').map((c) => c.text).join('');
+    const toolCalls = full.message.tool_calls ?? [];
+    const usage = full.usage.tokens ?? { input_tokens: 0, output_tokens: 0 };
+    return {
+        id: full.id,
+        object: 'chat.completion',
+        created: Math.floor(Date.parse(nowIso(occurredAt)) / 1000),
+        model: args.model,
+        choices: [{
+                index: 0,
+                message: { role: 'assistant', content: toolCalls.length > 0 && text === '' ? null : text, ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}) },
+                finish_reason: COMPAT_FINISH[full.finish_reason],
+            }],
+        usage: { prompt_tokens: usage.input_tokens, completion_tokens: usage.output_tokens, total_tokens: usage.input_tokens + usage.output_tokens },
+    };
+}
+/** Stream the same completion as `chat.completion.chunk` frames and return the unary body. */
+function streamCompat(completion, includeUsage, sink) {
+    const { id, created, model } = completion;
+    const choice = completion.choices[0];
+    const chunk = (delta, finish = null) => sink({ data: { id, object: 'chat.completion.chunk', created, model, choices: [{ index: 0, delta, finish_reason: finish }] } });
+    chunk({ role: 'assistant', content: '' });
+    for (const piece of chunkText(choice.message.content ?? ''))
+        chunk({ content: piece });
+    for (const [index, call] of (choice.message.tool_calls ?? []).entries()) {
+        chunk({ tool_calls: [{ index, id: call.id, type: 'function', function: { name: call.function.name, arguments: '' } }] });
+        for (const piece of chunkText(call.function.arguments))
+            chunk({ tool_calls: [{ index, function: { arguments: piece } }] });
+    }
+    chunk({}, choice.finish_reason);
+    if (includeUsage)
+        sink({ data: { id, object: 'chat.completion.chunk', created, model, choices: [], usage: completion.usage } });
+    sink({ done: true });
+    return completion;
+}
+function handleCompatChat(params, req) {
+    const validated = validateCompatChat(params);
+    if ('error' in validated)
+        return validated.error;
+    const { v2, includeUsage } = validated.args;
+    const outcome = req.scenarioEngine ? scenarioDecision(v2, req.scenarioEngine) : {};
+    if (outcome.error)
+        return outcome.error;
+    const completion = compatCompletion(v2, outcome, req.occurredAt);
+    if (!v2.stream)
+        return { status: 200, body: completion };
+    if (!req.sseSink)
+        return invalidRequest('stream:true requires a streaming transport');
+    return { status: 200, body: streamCompat(completion, includeUsage, req.sseSink) };
+}
+// ════════════════════════════════════════════════════════════════════════════════════════
 // CHAT v1 — a DIFFERENT protocol, not a versioned alias
 // ════════════════════════════════════════════════════════════════════════════════════════
 function handleChatV1(params, req) {
@@ -1004,6 +1159,7 @@ export const COHERE_ROUTER_SURFACE = [
     { method: 'POST', path: '/v2/embed' },
     { method: 'POST', path: '/v2/rerank' },
     { method: 'POST', path: '/v1/chat' },
+    { method: 'POST', path: '/compatibility/v1/chat/completions' },
     { method: 'POST', path: '/v1/embed' },
     { method: 'POST', path: '/v1/rerank' },
     { method: 'POST', path: '/v1/classify' },
@@ -1064,6 +1220,8 @@ export async function handleCohereTwinRequest(req) {
     }
     if (method === 'POST' && path === '/v1/chat')
         return handleChatV1(params, req);
+    if (method === 'POST' && path === '/compatibility/v1/chat/completions')
+        return handleCompatChat(params, req);
     // ── embed / rerank / classify ─────────────────────────────────────────────────────────
     if (method === 'POST' && path === '/v2/embed')
         return handleEmbedV2(params);

package/dist/src/index.js

@@ -71,7 +71,13 @@ export const pack = {
     // `/v2`. The Bedrock/SageMaker clients the SDK also ships (`AwsClient`, `BedrockClient`,
     // `SagemakerClient`) address AWS hosts, which are a different vendor's plane and deliberately
     // NOT claimed here.
-    hosts: [{ host: 'api.cohere.com' }],
+    //
+    // `api.cohere.ai` is Cohere's earlier host, still answering, and the one its Compatibility API
+    // documents (docs.cohere.com/docs/compatibility-api: every example's base URL is
+    // `https://api.cohere.ai/compatibility/v1`); applications that speak OpenAI's wire to Cohere
+    // address it there (LibreChat's own Cohere constant is `https://api.cohere.ai/v1`). The same
+    // twin answers both hosts, as the one API behind them.
+    hosts: [{ host: 'api.cohere.com' }, { host: 'api.cohere.ai' }],
     // WORLD WIRING (§7 point 12) — the ruling is NONE, and it is grounded, not skipped.
     // NEITHER SDK reads a base-URL environment variable. cohere-ai takes the override as a
     // CONSTRUCTOR option (`baseUrl` / `environment`, resolved through `core.Supplier.get`) and the
@@ -80,5 +86,5 @@ export const pack = {
     // Inventing a `COHERE_BASE_URL` would make `covers` report the world covered — any app-read env
     // counts — while the app, reading no such var, still talked to the real vendor. Interception is
     // therefore host-based, via the `hosts` entry above, which is the truth.
-    endpointEnvNone: 'neither official SDK reads a base-URL env var: cohere-ai@8.1.0 takes the override as the `baseUrl`/`environment` CONSTRUCTOR option and reads only CO_API_KEY from the environment (auth/BearerAuthProvider.js), and @ai-sdk/cohere@4.0.35 takes `options.baseURL` and reads only COHERE_API_KEY. Interception is host-based on api.cohere.com; inventing a COHERE_BASE_URL nothing reads would make `covers` claim a world it does not cover.',
+    endpointEnvNone: 'neither official SDK reads a base-URL env var: cohere-ai@8.1.0 takes the override as the `baseUrl`/`environment` CONSTRUCTOR option and reads only CO_API_KEY from the environment (auth/BearerAuthProvider.js), and @ai-sdk/cohere@4.0.35 takes `options.baseURL` and reads only COHERE_API_KEY. Interception is host-based on api.cohere.com and api.cohere.ai; inventing a COHERE_BASE_URL nothing reads would make `covers` claim a world it does not cover.',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-cohere",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local Cohere twin — a faithful, stateful local Cohere API your real cohere-ai / @ai-sdk/cohere client talks to unmodified. Both protocol versions are modeled (v1 chat/embed/rerank/classify/tokenize + v2 chat/embed/rerank), with deterministic stubs for model output and vendor-faithful envelopes, streaming, errors and refusals. Built on @volter/world-core.",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
@@ -37,15 +37,16 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.1"
   },
   "devDependencies": {
     "@ai-sdk/cohere": "^4.0.35",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.1",
     "@volter/world-tooling": "0.1.0",
     "cohere-ai": "^8.1.0",
+    "openai": "^6.45.0",
     "typescript": "^5.9.0"
   },
   "engines": {

package/src/cohere-capabilities.ts

@@ -64,7 +64,7 @@ import {
 } from './cohere-connector.ts';
 import { COHERE_MODELS, COHERE_ENDPOINTS } from './cohere-models.ts';
 import { createCohereScenarioEngine } from './cohere-scenario.ts';
-import { handleCohereTwinRequest, type CohereResponseEnvelope } from './cohere-twin.ts';
+import { compatMessages, handleCohereTwinRequest, type CohereResponseEnvelope } from './cohere-twin.ts';
 import type { SseEvent } from './cohere-types.ts';
 
 // ── API verify: drive REAL requests against a fresh temp root, then assert status/shape ──
@@ -196,6 +196,7 @@ export const COHERE_AREAS = [
   'batches',
   'chat',
   'chat_v1',
+  'compat',
   'classify',
   'conformance',
   'connector',
@@ -284,6 +285,22 @@ export const COHERE_CAPABILITIES: CapabilitySpec[] = [
         && typeof (none.body as Body).message?.content?.[0]?.text === 'string';
     }),
   ),
+  done('cohere.chat.tool_result_answered', 'chat', 'v2 chat: a turn answering a tool result is words, not another tool call, unless tool_choice is REQUIRED', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const first = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL] }) });
+      const call = (first.body as Body).message?.tool_calls?.[0];
+      if (!call) return false;
+      const loop = [
+        { role: 'user', content: 'weather?' },
+        { role: 'assistant', tool_calls: [call], tool_plan: (first.body as Body).message.tool_plan },
+        { role: 'tool', tool_call_id: call.id, content: [{ type: 'document', document: { data: '{"temp":20}' } }] },
+      ];
+      const answered = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], messages: loop }) });
+      const insisted = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], messages: loop, tool_choice: 'REQUIRED' }) });
+      return (answered.body as Body).finish_reason === 'COMPLETE' && typeof (answered.body as Body).message?.content?.[0]?.text === 'string'
+        && (insisted.body as Body).finish_reason === 'TOOL_CALL';
+    }),
+  ),
   done('cohere.chat.thinking', 'chat', 'v2 chat: `thinking: {type:enabled}` prepends a `thinking` content item', 'api', 'common', () =>
     withRoot(async (h) => {
       const off = await h({ m: 'POST', p: '/v2/chat', b: CHAT() });
@@ -338,6 +355,95 @@ export const COHERE_CAPABILITIES: CapabilitySpec[] = [
       return end.delta.finish_reason === 'TOOL_CALL';
     }),
   ),
+  // ══ THE COMPATIBILITY API — OpenAI's wire at api.cohere.ai/compatibility/v1 ════════════
+  done('cohere.compat.chat_completions', 'compat', 'Compatibility API: POST /compatibility/v1/chat/completions answers OpenAI\'s chat.completion envelope for a Cohere model', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT() });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      // OpenAI's keys PRESENT, Cohere v2's ABSENT: the same turn in the other wire, not the v2 body relabelled.
+      if (b.object !== 'chat.completion' || typeof b.created !== 'number' || b.model !== 'command-a-03-2025') return false;
+      if (b.message !== undefined || b.finish_reason !== undefined) return false;
+      const c = b.choices?.[0];
+      if (b.choices.length !== 1 || c.index !== 0 || c.message?.role !== 'assistant' || c.finish_reason !== 'stop') return false;
+      if (typeof c.message.content !== 'string' || !c.message.content.includes('[twin-stub:command-a-03-2025]') || !c.message.content.includes('hello twin')) return false;
+      // The flat usage, whose counts move with the input (a constant would pass the shape check).
+      const long = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'x'.repeat(400) }] }) });
+      const u = b.usage; const lu = (long.body as Body).usage;
+      return u.total_tokens === u.prompt_tokens + u.completion_tokens && lu.prompt_tokens > u.prompt_tokens * 5;
+    }),
+  ),
+  done('cohere.compat.tool_calls', 'compat', 'Compatibility API: tools → OpenAI `tool_calls` with finish_reason tool_calls; tool_choice none forbids it; the tool result is answered in words', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const call = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL] }) });
+      const none = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL], tool_choice: 'none' }) });
+      const c = (call.body as Body).choices?.[0];
+      if (c?.finish_reason !== 'tool_calls' || c.message?.content !== null) return false;
+      const tc = c.message.tool_calls?.[0];
+      if (tc?.type !== 'function' || tc.function?.name !== 'get_weather' || typeof tc.function.arguments !== 'string') return false;
+      if ((none.body as Body).choices?.[0]?.finish_reason !== 'stop' || (none.body as Body).choices[0].message.tool_calls !== undefined) return false;
+      // OpenAI's tool loop: the assistant's tool call, then the `tool` result — the next turn is words, not another call.
+      const answered = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL], messages: [
+        { role: 'user', content: 'weather?' },
+        { role: 'assistant', content: null, tool_calls: [tc] },
+        { role: 'tool', tool_call_id: tc.id, content: '{"temp":20}' },
+      ] }) });
+      return ok(answered) && typeof (answered.body as Body).choices?.[0]?.message?.content === 'string';
+    }),
+  ),
+  done('cohere.compat.stream', 'compat', 'Compatibility API streaming: chat.completion.chunk frames reassemble the unary answer, end with the finish reason, a usage chunk when stream_options asks, then [DONE]', 'api', 'core', () =>
+    withStream('/compatibility/v1/chat/completions', CHAT({ stream: true, stream_options: { include_usage: true } }), (events, final) => {
+      const frames = events.filter((e) => !e.done).map((e) => e.data as Body);
+      if (events[events.length - 1]?.done !== true) return false;
+      if (!frames.every((f) => f.object === 'chat.completion.chunk' && f.id === (final.body as Body).id)) return false;
+      if (frames[0]!.choices[0].delta.role !== 'assistant') return false;
+      const last = frames[frames.length - 1]!;
+      // the usage-only chunk: no choices, the unary usage
+      if (last.choices.length !== 0 || last.usage?.total_tokens !== (final.body as Body).usage.total_tokens) return false;
+      const finishing = frames.filter((f) => f.choices[0]?.finish_reason);
+      if (finishing.length !== 1 || finishing[0]!.choices[0].finish_reason !== 'stop') return false;
+      const joined = frames.map((f) => f.choices[0]?.delta?.content ?? '').join('');
+      return joined === (final.body as Body).choices[0].message.content;
+    }),
+  ),
+  done('cohere.compat.stream_no_usage_unasked', 'compat', 'Compatibility API streaming: no usage chunk unless stream_options.include_usage', 'api', 'common', () =>
+    withStream('/compatibility/v1/chat/completions', CHAT({ stream: true }), (events) =>
+      events.length > 2 && events.filter((e) => !e.done).every((e) => (e.data as Body).usage === undefined && (e.data as Body).choices.length === 1)),
+  ),
+  done('cohere.compat.refusals', 'compat', 'Compatibility API: a model Cohere does not serve, a missing model, an empty messages array and an unknown tool_choice are refused; the parameters the docs name unsupported are ignored', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const P = '/compatibility/v1/chat/completions';
+      const wrongModel = await h({ m: 'POST', p: P, b: CHAT({ model: 'gpt-4o' }) });
+      const noModel = await h({ m: 'POST', p: P, b: { messages: [{ role: 'user', content: 'x' }] } });
+      const empty = await h({ m: 'POST', p: P, b: CHAT({ messages: [] }) });
+      const badChoice = await h({ m: 'POST', p: P, b: CHAT({ tool_choice: 'sometimes' }) });
+      const unsupported = await h({ m: 'POST', p: P, b: CHAT({ n: 2, logit_bias: { 1: 1 }, store: true, parallel_tool_calls: false }) });
+      return wrongModel.status === 404 && bareError(noModel, 400) && bareError(empty, 400) && bareError(badChoice, 400) && ok(unsupported);
+    }),
+  ),
+  done('cohere.compat.named_tool_choice', 'compat', 'Compatibility API: tool_choice naming a function calls that function, not the first declared', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const OTHER = { type: 'function', function: { name: 'get_time', parameters: { type: 'object', properties: { zone: { type: 'string' } } } } };
+      const named = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL, OTHER], tool_choice: { type: 'function', function: { name: 'get_time' } } }) });
+      const unnamed = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ tools: [TOOL, OTHER] }) });
+      return (named.body as Body).choices?.[0]?.message?.tool_calls?.[0]?.function?.name === 'get_time'
+        && (unnamed.body as Body).choices?.[0]?.message?.tool_calls?.[0]?.function?.name === 'get_weather';
+    }),
+  ),
+  done('cohere.compat.developer_role', 'compat', 'Compatibility API: a `developer` message is a system message; an unknown role is refused', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const converted = compatMessages([{ role: 'developer', content: 'be brief' }, { role: 'user', content: 'hi' }]);
+      if (typeof converted === 'string' || converted[0]?.role !== 'system' || converted[0]?.content !== 'be brief') return false;
+      const dev = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ messages: [{ role: 'developer', content: 'be brief' }, { role: 'user', content: 'hi' }] }) });
+      const bad = await h({ m: 'POST', p: '/compatibility/v1/chat/completions', b: CHAT({ messages: [{ role: 'narrator', content: 'x' }] }) });
+      return ok(dev) && bareError(bad, 400);
+    }),
+  ),
+  todo('cohere.compat.embeddings', 'compat', 'Compatibility API: POST /compatibility/v1/embeddings (input, model, encoding_format) in OpenAI\'s list-of-embeddings envelope', 'api', 'common'),
+  todo('cohere.compat.audio_transcriptions', 'compat', 'Compatibility API: POST /compatibility/v1/audio/transcriptions', 'api', 'niche'),
+  todo('cohere.compat.reasoning_effort', 'compat', 'Compatibility API: reasoning_effort (none / high) turns Cohere\'s thinking off and on', 'api', 'common'),
+  todo('cohere.compat.response_format', 'compat', 'Compatibility API: response_format json_object / json_schema answers JSON content', 'api', 'common'),
+
   done('cohere.chat.stream_needs_transport', 'chat', 'v2 chat: `stream:true` with no streaming transport is refused, not silently unary', 'api', 'niche', () =>
     withRoot(async (h) => {
       const r = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ stream: true }) });
@@ -1819,7 +1925,7 @@ export const COHERE_CAPABILITIES: CapabilitySpec[] = [
   done('cohere.conformance.probes', 'conformance', 'Conformance: every claimed endpoint is probed for a live OUTCOME, not just a dispatch', 'api', 'core', async () =>
     verifyBoundary('cohere.conformance', async () => {
       const report = await checkCohereConformance();
-      return report.ok && report.claimed === 27 && report.checksRun >= 58 && report.violations.length === 0;
+      return report.ok && report.claimed === 28 && report.checksRun >= 60 && report.violations.length === 0;
     }),
   ),
   done('cohere.conformance.scenario_engine_is_the_kernel', 'conformance', 'Scenario scripting runs on THE kernel engine with a pack adapter (never a bespoke one)', 'api', 'common', () =>

package/src/cohere-conformance.ts

@@ -50,6 +50,7 @@ export const COHERE_TWIN_SNAPSHOT: ReadonlyArray<string> = [
   'POST /v2/embed',
   'POST /v2/rerank',
   'POST /v1/chat',
+  'POST /compatibility/v1/chat/completions',
   'POST /v1/embed',
   'POST /v1/rerank',
   'POST /v1/classify',
@@ -116,6 +117,17 @@ const PROBES: Probe[] = [
       && b.usage?.billed_units?.input_tokens > 0 && b.usage?.tokens?.input_tokens === b.usage.billed_units.input_tokens
       && b.usage?.tokens?.output_tokens > 0,
   },
+  {
+    claim: 'POST /compatibility/v1/chat/completions',
+    request: () => ({ method: 'POST', path: '/compatibility/v1/chat/completions', body: CHAT }),
+    status: [200],
+    // OpenAI's envelope on the Compatibility API — the very keys the v2 probe above asserts ABSENT.
+    expect: (b) => isObj(b) && b.object === 'chat.completion' && typeof b.created === 'number'
+      && b.choices?.[0]?.message?.role === 'assistant'
+      && String(b.choices[0].message.content).includes('[twin-stub:command-a-03-2025]')
+      && b.choices[0].finish_reason === 'stop'
+      && b.usage?.total_tokens === b.usage?.prompt_tokens + b.usage?.completion_tokens && b.usage.prompt_tokens > 0,
+  },
   {
     claim: 'POST /v1/chat',
     request: () => ({ method: 'POST', path: '/v1/chat', body: { message: 'v1 probe', model: 'command-r-08-2024' } }),

package/src/cohere-server.ts

@@ -134,7 +134,9 @@ export function createCohereTwinFetch(options: CohereTwinFetchOptions): (request
       // 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)) {
+      // The Compatibility API streams OpenAI's `chat.completion.chunk` frames over SSE, `[DONE]`-terminated.
+      const isCompatStream = request.method.toUpperCase() === 'POST' && cleanPath === '/compatibility/v1/chat/completions' && wantsStream(body);
+      if (!readOnly && (isV2Stream || isV1Stream || isCompatStream)) {
         const events: SseEvent[] = [];
         const { status, body: out, headers: extra } = await handleCohereTwinRequest({
           method: request.method, path, body, readOnly, headers, occurredAt: worldNow(),
@@ -146,7 +148,7 @@ export function createCohereTwinFetch(options: CohereTwinFetchOptions): (request
           return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(extra ?? {}) } });
         }
         const enc = new TextEncoder();
-        const frame = isV2Stream ? encodeSse : encodeNdjson;
+        const frame = isV2Stream || isCompatStream ? encodeSse : encodeNdjson;
         const stream = new ReadableStream<Uint8Array>({
           start(controller) {
             for (const e of events) {
@@ -159,7 +161,7 @@ export function createCohereTwinFetch(options: CohereTwinFetchOptions): (request
         return new Response(stream, {
           status,
           headers: {
-            'content-type': isV2Stream ? 'text/event-stream; charset=utf-8' : 'application/stream+json; charset=utf-8',
+            'content-type': isV2Stream || isCompatStream ? 'text/event-stream; charset=utf-8' : 'application/stream+json; charset=utf-8',
             'cache-control': 'no-cache',
             ...(extra ?? {}),
           },

package/src/cohere-twin.ts

@@ -315,6 +315,8 @@ export type ChatV2Args = {
   messages: CohereMessageV2[];
   tools?: unknown;
   toolChoice?: 'REQUIRED' | 'NONE';
+  /** The one tool a caller names (the Compatibility API's `tool_choice: {function:{name}}`; v2 cannot name one). */
+  forcedTool?: string;
   maxTokens?: number;
   stream: boolean;
   thinking: boolean;
@@ -408,10 +410,14 @@ function assistantTurn(args: ChatV2Args, scripted?: ScriptedResult, missTeach =
   const names = toolNames(args.tools);
   // `tool_choice: 'NONE'` forbids a tool call even when tools are declared — the vendor honours it
   // and so must the twin, or a caller testing the NONE path gets a tool call it explicitly banned.
-  const wantsTool = names.length > 0 && args.toolChoice !== 'NONE';
+  // A model answers a tool's result in words unless the caller insists on another call (REQUIRED):
+  // a stub that called a tool on every turn would never let an application's tool loop end (an
+  // agent runs until its recursion limit), where Cohere's model answers from what the tool returned.
+  const answeringTool = args.messages.at(-1)?.role === 'tool';
+  const wantsTool = names.length > 0 && args.toolChoice !== 'NONE' && (!answeringTool || args.toolChoice === 'REQUIRED');
   const seed = JSON.stringify(args.messages);
   if (wantsTool) {
-    const call = stubToolCall(args.tools, seed, 0);
+    const call = stubToolCall(args.tools, seed, 0, args.forcedTool);
     return { content: [], toolCalls: call ? [call] : [], toolPlan: stubToolPlan(names), finish: 'TOOL_CALL' };
   }
   const content: CohereAssistantContentItem[] = [];
@@ -508,6 +514,148 @@ function chunkText(text: string): string[] {
   return out;
 }
 
+// ════════════════════════════════════════════════════════════════════════════════════════
+// THE COMPATIBILITY API — OpenAI's wire, Cohere's models (docs.cohere.com/docs/compatibility-api)
+// ════════════════════════════════════════════════════════════════════════════════════════
+//
+// Cohere serves OpenAI's Chat Completions wire at `https://api.cohere.ai/compatibility/v1` so an
+// application built on the OpenAI SDK (or one that speaks OpenAI's wire to every provider, as
+// LibreChat's custom endpoints do) reaches Cohere's models by changing base URL, key and model.
+// The docs' code examples all address that base; the parameters they list for chat completions
+// are exactly `model, messages, stream, reasoning_effort, response_format, tools, temperature,
+// max_tokens, stop, seed, top_p, frequency_penalty, presence_penalty`, and they name `store`,
+// `metadata`, `logit_bias`, `top_logprobs`, `n`, `modalities`, `prediction`, `audio`, `service_tier` and
+// `parallel_tool_calls` unsupported.
+//
+// The turn itself is the v2 chat's (`assistantTurn`, scenario handlers included): the same stub,
+// the same tool decision, and the same handler document script both wires. Only the envelope is
+// OpenAI's: `object: 'chat.completion'`, one `choices[0]` with an assistant `message`, the
+// lower-case finish reasons (`stop`, `tool_calls`, `length`), and a flat `usage`
+// (`prompt_tokens`, `completion_tokens`, `total_tokens`); streaming is `chat.completion.chunk`
+// frames over SSE ending `data: [DONE]`, with a usage-only chunk when `stream_options.include_usage`
+// asks for it, as OpenAI's wire has it.
+//
+// Where the documentation stops and the twin decides (not probed against the live API, which
+// needs a key): the parameters the docs name unsupported are ignored, since the docs do not say
+// whether Cohere refuses or ignores them and a refusal would break a client that sends one; the
+// refusals the twin does make (model, messages, role, tool_choice) keep Cohere's bare `{message}`
+// envelope (the host's own); a named `tool_choice` function calls that function; a `developer`
+// message is read as a system message, as OpenAI defines it; `ERROR` and `TIMEOUT` finish as
+// `stop` (OpenAI's wire has no error finish reason); and a tool turn carries no `tool_plan` (the
+// docs' examples show OpenAI's fields only). `reasoning_effort` is not modelled (a `todo`).
+
+const COMPAT_ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool']);
+const COMPAT_FINISH: Record<CohereFinishReason, string> = {
+  COMPLETE: 'stop', STOP_SEQUENCE: 'stop', MAX_TOKENS: 'length', TOOL_CALL: 'tool_calls', ERROR: 'stop', TIMEOUT: 'stop',
+};
+
+type CompatArgs = { v2: ChatV2Args; includeUsage: boolean };
+
+/** OpenAI's chat messages as the v2 turn reads them (OpenAI's text, image_url, tool and assistant tool_calls shapes are
+ *  v2's own), or the refusal of the first message whose role neither wire has. */
+export function compatMessages(messages: unknown[]): CohereMessageV2[] | string {
+  const out: CohereMessageV2[] = [];
+  for (const [i, raw] of messages.entries()) {
+    const m = raw as Record<string, unknown> | null;
+    const role = m?.role;
+    if (typeof role !== 'string' || !COMPAT_ROLES.has(role)) return `messages[${i}].role must be one of ${[...COMPAT_ROLES].join(', ')}`;
+    const msg: CohereMessageV2 = { role: role === 'developer' ? 'system' : (role as CohereMessageV2['role']) };
+    if (m!.content !== undefined && m!.content !== null) msg.content = m!.content as CohereMessageV2['content'];
+    if (Array.isArray(m!.tool_calls) && m!.tool_calls.length > 0) msg.tool_calls = m!.tool_calls as CohereToolCallV2[];
+    if (typeof m!.tool_call_id === 'string') msg.tool_call_id = m!.tool_call_id;
+    out.push(msg);
+  }
+  return out;
+}
+
+function validateCompatChat(params: Record<string, unknown>): { args: CompatArgs } | { error: CohereResponseEnvelope } {
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return { error: invalidRequest('model is required') };
+  const messages = params.messages;
+  if (!Array.isArray(messages) || messages.length === 0) return { error: invalidRequest('messages must be a non-empty array') };
+  const converted = compatMessages(messages);
+  if (typeof converted === 'string') return { error: invalidRequest(converted) };
+  const v2Messages = converted;
+  const choice = params.tool_choice;
+  let toolChoice: ChatV2Args['toolChoice'];
+  let forcedTool: string | undefined;
+  if (choice === 'none') toolChoice = 'NONE';
+  else if (choice === 'required') toolChoice = 'REQUIRED';
+  else if (choice !== null && typeof choice === 'object') {
+    toolChoice = 'REQUIRED';
+    const named = (choice as { function?: { name?: unknown } }).function?.name;
+    if (typeof named === 'string') forcedTool = named;
+  }
+  else if (choice !== undefined && choice !== 'auto') return { error: invalidRequest('tool_choice must be none, auto, required or a named function') };
+  if (!modelServes(model, 'chat')) return { error: modelNotFound(model) };
+  const maxTokens = typeof params.max_tokens === 'number' ? params.max_tokens : typeof params.max_completion_tokens === 'number' ? params.max_completion_tokens : undefined;
+  return {
+    args: {
+      v2: {
+        model,
+        messages: v2Messages,
+        ...(params.tools !== undefined ? { tools: params.tools } : {}),
+        ...(toolChoice !== undefined ? { toolChoice } : {}),
+        ...(forcedTool !== undefined ? { forcedTool } : {}),
+        ...(maxTokens !== undefined ? { maxTokens } : {}),
+        stream: params.stream === true,
+        thinking: false,
+      },
+      includeUsage: (params.stream_options as { include_usage?: unknown } | undefined)?.include_usage === true,
+    },
+  };
+}
+
+/** The OpenAI-shaped completion of one v2 turn. */
+function compatCompletion(args: ChatV2Args, outcome: ScenarioOutcome, occurredAt?: string): Record<string, unknown> {
+  const full = buildChatV2(args, outcome);
+  const text = (full.message.content ?? []).filter((c) => c.type === 'text').map((c) => (c as { text: string }).text).join('');
+  const toolCalls = full.message.tool_calls ?? [];
+  const usage = full.usage.tokens ?? { input_tokens: 0, output_tokens: 0 };
+  return {
+    id: full.id,
+    object: 'chat.completion',
+    created: Math.floor(Date.parse(nowIso(occurredAt)) / 1000),
+    model: args.model,
+    choices: [{
+      index: 0,
+      message: { role: 'assistant', content: toolCalls.length > 0 && text === '' ? null : text, ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}) },
+      finish_reason: COMPAT_FINISH[full.finish_reason],
+    }],
+    usage: { prompt_tokens: usage.input_tokens, completion_tokens: usage.output_tokens, total_tokens: usage.input_tokens + usage.output_tokens },
+  };
+}
+
+/** Stream the same completion as `chat.completion.chunk` frames and return the unary body. */
+function streamCompat(completion: Record<string, unknown>, includeUsage: boolean, sink: SseSink): Record<string, unknown> {
+  const { id, created, model } = completion as { id: string; created: number; model: string };
+  const choice = (completion.choices as Array<{ message: { content: string | null; tool_calls?: CohereToolCallV2[] }; finish_reason: string }>)[0]!;
+  const chunk = (delta: Record<string, unknown>, finish: string | null = null): void =>
+    sink({ data: { id, object: 'chat.completion.chunk', created, model, choices: [{ index: 0, delta, finish_reason: finish }] } });
+  chunk({ role: 'assistant', content: '' });
+  for (const piece of chunkText(choice.message.content ?? '')) chunk({ content: piece });
+  for (const [index, call] of (choice.message.tool_calls ?? []).entries()) {
+    chunk({ tool_calls: [{ index, id: call.id, type: 'function', function: { name: call.function.name, arguments: '' } }] });
+    for (const piece of chunkText(call.function.arguments)) chunk({ tool_calls: [{ index, function: { arguments: piece } }] });
+  }
+  chunk({}, choice.finish_reason);
+  if (includeUsage) sink({ data: { id, object: 'chat.completion.chunk', created, model, choices: [], usage: completion.usage as Record<string, unknown> } });
+  sink({ done: true });
+  return completion;
+}
+
+function handleCompatChat(params: Record<string, unknown>, req: CohereRequest): CohereResponseEnvelope {
+  const validated = validateCompatChat(params);
+  if ('error' in validated) return validated.error;
+  const { v2, includeUsage } = validated.args;
+  const outcome = req.scenarioEngine ? scenarioDecision(v2, req.scenarioEngine) : {};
+  if (outcome.error) return outcome.error;
+  const completion = compatCompletion(v2, outcome, req.occurredAt);
+  if (!v2.stream) return { status: 200, body: completion };
+  if (!req.sseSink) return invalidRequest('stream:true requires a streaming transport');
+  return { status: 200, body: streamCompat(completion, includeUsage, req.sseSink) };
+}
+
 // ════════════════════════════════════════════════════════════════════════════════════════
 // CHAT v1 — a DIFFERENT protocol, not a versioned alias
 // ════════════════════════════════════════════════════════════════════════════════════════
@@ -1071,6 +1219,7 @@ export const COHERE_ROUTER_SURFACE: ReadonlyArray<{ method: string; path: string
   { method: 'POST', path: '/v2/embed' },
   { method: 'POST', path: '/v2/rerank' },
   { method: 'POST', path: '/v1/chat' },
+  { method: 'POST', path: '/compatibility/v1/chat/completions' },
   { method: 'POST', path: '/v1/embed' },
   { method: 'POST', path: '/v1/rerank' },
   { method: 'POST', path: '/v1/classify' },
@@ -1130,6 +1279,7 @@ export async function handleCohereTwinRequest(req: CohereRequest): Promise<Coher
     return { status: 200, body: buildChatV2(args, outcome) };
   }
   if (method === 'POST' && path === '/v1/chat') return handleChatV1(params, req);
+  if (method === 'POST' && path === '/compatibility/v1/chat/completions') return handleCompatChat(params, req);
 
   // ── embed / rerank / classify ─────────────────────────────────────────────────────────
   if (method === 'POST' && path === '/v2/embed') return handleEmbedV2(params);

package/src/index.ts

@@ -145,7 +145,13 @@ export const pack: TwinPack = {
   // `/v2`. The Bedrock/SageMaker clients the SDK also ships (`AwsClient`, `BedrockClient`,
   // `SagemakerClient`) address AWS hosts, which are a different vendor's plane and deliberately
   // NOT claimed here.
-  hosts: [{ host: 'api.cohere.com' }],
+  //
+  // `api.cohere.ai` is Cohere's earlier host, still answering, and the one its Compatibility API
+  // documents (docs.cohere.com/docs/compatibility-api: every example's base URL is
+  // `https://api.cohere.ai/compatibility/v1`); applications that speak OpenAI's wire to Cohere
+  // address it there (LibreChat's own Cohere constant is `https://api.cohere.ai/v1`). The same
+  // twin answers both hosts, as the one API behind them.
+  hosts: [{ host: 'api.cohere.com' }, { host: 'api.cohere.ai' }],
 
   // WORLD WIRING (§7 point 12) — the ruling is NONE, and it is grounded, not skipped.
   // NEITHER SDK reads a base-URL environment variable. cohere-ai takes the override as a
@@ -155,5 +161,5 @@ export const pack: TwinPack = {
   // Inventing a `COHERE_BASE_URL` would make `covers` report the world covered — any app-read env
   // counts — while the app, reading no such var, still talked to the real vendor. Interception is
   // therefore host-based, via the `hosts` entry above, which is the truth.
-  endpointEnvNone: 'neither official SDK reads a base-URL env var: cohere-ai@8.1.0 takes the override as the `baseUrl`/`environment` CONSTRUCTOR option and reads only CO_API_KEY from the environment (auth/BearerAuthProvider.js), and @ai-sdk/cohere@4.0.35 takes `options.baseURL` and reads only COHERE_API_KEY. Interception is host-based on api.cohere.com; inventing a COHERE_BASE_URL nothing reads would make `covers` claim a world it does not cover.',
+  endpointEnvNone: 'neither official SDK reads a base-URL env var: cohere-ai@8.1.0 takes the override as the `baseUrl`/`environment` CONSTRUCTOR option and reads only CO_API_KEY from the environment (auth/BearerAuthProvider.js), and @ai-sdk/cohere@4.0.35 takes `options.baseURL` and reads only COHERE_API_KEY. Interception is host-based on api.cohere.com and api.cohere.ai; inventing a COHERE_BASE_URL nothing reads would make `covers` claim a world it does not cover.',
 };