@volter/twin-cohere 0.1.0

package/src/cohere-types.ts

@@ -0,0 +1,231 @@
+// Shared wire-shape types for the Cohere API surface. These mirror the real vendor JSON shapes
+// (not an SDK's internal types — the twin never imports a vendor SDK at runtime; the SDKs are
+// exercised only in *.test.ts). Kept minimal but faithful.
+//
+// COHERE SPEAKS ITS OWN DIALECT. It is NOT OpenAI-compatible and copying an OpenAI-shaped pack's
+// permissiveness would be exactly the bug: Cohere's chat response has no `choices` array, its
+// finish reasons are UPPER-CASE (`COMPLETE`/`TOOL_CALL`/`MAX_TOKENS`), its usage lives under
+// `usage.billed_units`/`usage.tokens` (v2) or `meta.billed_units` (v1), and its error envelope is
+// a BARE `{ "message": "…" }` with no `error` wrapper, no `type`, no `code`.
+//
+// PROVENANCE for every shape below: the two SDKs this pack is built against, read from their
+// published npm tarballs during this build (2026-08-31):
+//   • cohere-ai@8.1.0 — the Fern-generated client. The WIRE keys come from its
+//     `serialization/**/*.d.ts` `interface Raw` blocks (Fern's serializers map snake_case wire
+//     keys onto camelCase TS properties, so the TS types alone would be MISLEADING here):
+//     `V2ChatResponse`, `AssistantMessageResponse`, `Usage`, `UsageTokens`, `UsageBilledUnits`,
+//     `ChatFinishReason`, `V2ChatStreamResponse` (+ its twelve event members),
+//     `EmbedByTypeResponse`, `EmbedByTypeResponseEmbeddings`, `EmbedFloatsResponse`,
+//     `V2RerankResponse`, `V2RerankResponseResultsItem`, `ClassifyResponse`, `TokenizeResponse`,
+//     `DetokenizeResponse`, `CheckApiKeyResponse`, `ListModelsResponse`, `GetModelResponse`,
+//     `ApiMeta`, `ApiMetaBilledUnits`, `ApiMetaApiVersion`, `NonStreamedChatResponse`, `Dataset`,
+//     `Connector`, `EmbedJob`, `ToolCallV2`.
+//   • @ai-sdk/cohere@4.0.35 — the SECOND independent transcription of the same wire, and the
+//     STRICTER one for chat/embed/rerank: `cohereChatResponseSchema`, `cohereChatChunkSchema`
+//     (a `z.discriminatedUnion("type", …)` over the stream events), `cohereUsageSchema`,
+//     `cohereTextEmbeddingResponseSchema`, `cohereRerankingResponseSchema` and
+//     `cohereErrorDataSchema`. Where the two disagree in strictness the twin satisfies BOTH.
+
+// ── Errors ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Cohere's API error envelope. It is a BARE object with ONE key — exactly as
+ * @ai-sdk/cohere@4.0.35's `cohereErrorDataSchema` transcribes it:
+ *   `cohereErrorDataSchema = z.object({ message: z.string() })`
+ * There is no `error` wrapper, no `type`, and no `code`. A twin that emitted OpenAI's
+ * `{ error: { message, type } }` here would be caught by that schema on every failure path.
+ */
+export type CohereApiError = { message: string };
+
+// ── Chat v2 (`POST /v2/chat`) ───────────────────────────────────────────────────────────
+/** A v2 chat message as the caller sends it. `content` is a string OR a content-part array. */
+export type CohereMessageV2 = {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content?: string | Array<Record<string, unknown>> | null;
+  tool_calls?: CohereToolCallV2[] | null;
+  tool_plan?: string | null;
+  tool_call_id?: string | null;
+};
+
+/**
+ * `ToolCallV2`. The vendor's own serializer declares `function?: ToolCallV2Function.Raw | null`,
+ * with `name` and `arguments` optional INSIDE it — but this type deliberately declares all three
+ * REQUIRED, because that is what the twin EMITS and what a caller may rely on.
+ *
+ * The narrowing is the right way round: @ai-sdk/cohere's `cohereChatResponseSchema` requires
+ * `function.name` and `function.arguments` on every tool call, and its `tool-call-start` chunk
+ * schema requires them too — so a twin that emitted the vendor's loosest legal shape would fail
+ * the stricter of its two clients. Narrower on OUTPUT, never on input. (§9 round 1, finding 9
+ * caught the comment here saying the opposite of the code.)
+ */
+export type CohereToolCallV2 = {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+};
+
+/**
+ * The reason a chat request finished. Cohere's values are UPPER-CASE and are its own set — this
+ * is the single most conspicuous place an OpenAI-shaped copy goes wrong (`stop` / `tool_calls`
+ * are NOT Cohere values). Source: `api/types/ChatFinishReason.d.ts`.
+ */
+export type CohereFinishReason = 'COMPLETE' | 'STOP_SEQUENCE' | 'MAX_TOKENS' | 'TOOL_CALL' | 'ERROR' | 'TIMEOUT';
+
+export const COHERE_FINISH_REASONS: readonly CohereFinishReason[] = ['COMPLETE', 'STOP_SEQUENCE', 'MAX_TOKENS', 'TOOL_CALL', 'ERROR', 'TIMEOUT'];
+
+/** `Usage` — TWO nested counters, `billed_units` and `tokens`, not a flat `prompt_tokens` trio. */
+export type CohereUsage = {
+  billed_units: { input_tokens: number; output_tokens: number };
+  tokens: { input_tokens: number; output_tokens: number };
+};
+
+/** A content item on an assistant response message. */
+export type CohereAssistantContentItem =
+  | { type: 'text'; text: string }
+  | { type: 'thinking'; thinking: string };
+
+/** `AssistantMessageResponse`. */
+export type CohereAssistantMessage = {
+  role: 'assistant';
+  content?: CohereAssistantContentItem[];
+  tool_plan?: string;
+  tool_calls?: CohereToolCallV2[];
+};
+
+/** The unary `POST /v2/chat` envelope — NO `choices`, NO `object`, NO `created`. */
+export type CohereChatV2Response = {
+  id: string;
+  finish_reason: CohereFinishReason;
+  message: CohereAssistantMessage;
+  usage: CohereUsage;
+};
+
+/**
+ * The v2 streaming event `type` values, in the order `cohereChatChunkSchema`'s discriminated
+ * union declares them. The twin emits a subset; the SET is the vendor's.
+ */
+export type CohereStreamEventType =
+  | 'message-start' | 'content-start' | 'content-delta' | 'content-end'
+  | 'tool-plan-delta' | 'tool-call-start' | 'tool-call-delta' | 'tool-call-end'
+  | 'citation-start' | 'citation-end' | 'message-end' | 'debug';
+
+// ── Chat v1 (`POST /v1/chat`) — a DIFFERENT envelope, not a versioned alias ──────────────
+/**
+ * v1's OWN finish-reason set. It is NOT the v2 `ChatFinishReason` set, which is the sort of
+ * conflation that looks harmless until a value crosses over: `NonStreamedChatResponse.finish_reason`
+ * is `FinishReason` — all EIGHT of `COMPLETE | STOP_SEQUENCE | ERROR | ERROR_TOXIC | ERROR_LIMIT |
+ * USER_CANCEL | MAX_TOKENS | TIMEOUT` (`api/types/FinishReason.d.ts`), with **no `TOOL_CALL`** and
+ * with three members v2 does not have. Typing the v1 body with the v2 union invited `TOOL_CALL`
+ * onto a response the vendor's union rejects (§9 round 1, finding 9) — and the first correction
+ * then transcribed only six of the eight, which §9 round two caught: this const is public API, so a
+ * consumer validating a v1 body against a short set rejects two legal vendor values.
+ * The twin only ever emits `COMPLETE` on v1, which is valid in this set, in the v2 set, and in the
+ * narrower `ChatStreamEndEventFinishReason` the v1 stream terminator uses.
+ */
+export type CohereV1FinishReason = 'COMPLETE' | 'STOP_SEQUENCE' | 'ERROR' | 'ERROR_TOXIC' | 'ERROR_LIMIT' | 'USER_CANCEL' | 'MAX_TOKENS' | 'TIMEOUT';
+
+export const COHERE_V1_FINISH_REASONS: readonly CohereV1FinishReason[] = ['COMPLETE', 'STOP_SEQUENCE', 'ERROR', 'ERROR_TOXIC', 'ERROR_LIMIT', 'USER_CANCEL', 'MAX_TOKENS', 'TIMEOUT'];
+
+/**
+ * `NonStreamedChatResponse`. v1 answers a FLAT `text` string with `meta` (not `usage`), and takes
+ * a single `message` string plus `chat_history` — it is a different protocol from v2, sharing
+ * only the host. Modeling it as "v2 with a prefix" is the trap.
+ */
+export type CohereChatV1Response = {
+  text: string;
+  generation_id: string;
+  response_id: string;
+  finish_reason: CohereV1FinishReason;
+  chat_history: Array<{ role: string; message: string }>;
+  meta: CohereApiMeta;
+};
+
+// ── `ApiMeta` — the v1 metering envelope ────────────────────────────────────────────────
+export type CohereApiMeta = {
+  api_version: { version: string };
+  billed_units: Partial<{ input_tokens: number; output_tokens: number; search_units: number; classifications: number; images: number; image_tokens: number; pages: number }>;
+  tokens?: { input_tokens?: number; output_tokens?: number };
+  warnings?: string[];
+};
+
+// ── Embed ───────────────────────────────────────────────────────────────────────────────
+/** The six `EmbeddingType` values Cohere accepts. `float` is the default and the only one
+ *  @ai-sdk/cohere requests. */
+export const COHERE_EMBEDDING_TYPES = ['float', 'int8', 'uint8', 'binary', 'ubinary', 'base64'] as const;
+export type CohereEmbeddingType = (typeof COHERE_EMBEDDING_TYPES)[number];
+
+/** The five `EmbedInputType` values. v2 embed REQUIRES one; v1 does not. */
+export const COHERE_INPUT_TYPES = ['search_document', 'search_query', 'classification', 'clustering', 'image'] as const;
+export type CohereInputType = (typeof COHERE_INPUT_TYPES)[number];
+
+/** `V2EmbedRequestTruncate` / `EmbedRequestTruncate` — UPPER-CASE, unlike most vendors' enums. */
+export const COHERE_TRUNCATE = ['NONE', 'START', 'END'] as const;
+
+/** `EmbedByTypeResponse` — v2 keys the vectors BY TYPE under `embeddings`. */
+export type CohereEmbedV2Response = {
+  id: string;
+  embeddings: Partial<Record<CohereEmbeddingType, number[][] | string[]>>;
+  texts: string[];
+  response_type: 'embeddings_by_type';
+  meta: CohereApiMeta;
+};
+
+/** `EmbedFloatsResponse` — v1's DEFAULT answer puts a flat `number[][]` at `embeddings`. The two
+ *  shapes are not interchangeable, and the v1 caller only gets the by-type shape when it asks for
+ *  `embedding_types`. */
+export type CohereEmbedV1FloatsResponse = {
+  id: string;
+  embeddings: number[][];
+  texts: string[];
+  response_type: 'embeddings_floats';
+  meta: CohereApiMeta;
+};
+
+// ── Rerank ──────────────────────────────────────────────────────────────────────────────
+export type CohereRerankResult = { index: number; relevance_score: number; document?: { text: string } };
+export type CohereRerankResponse = { id: string; results: CohereRerankResult[]; meta: CohereApiMeta };
+
+// ── Classify ────────────────────────────────────────────────────────────────────────────
+export type CohereClassification = {
+  id: string;
+  input: string;
+  prediction: string;
+  predictions: string[];
+  confidence: number;
+  confidences: number[];
+  labels: Record<string, { confidence: number }>;
+  classification_type: 'single-label' | 'multi-label';
+};
+export type CohereClassifyResponse = { id: string; classifications: CohereClassification[]; meta: CohereApiMeta };
+
+// ── Tokenize / detokenize / check-api-key ───────────────────────────────────────────────
+export type CohereTokenizeResponse = { tokens: number[]; token_strings: string[]; meta: CohereApiMeta };
+export type CohereDetokenizeResponse = { text: string; meta: CohereApiMeta };
+export type CohereCheckApiKeyResponse = { valid: boolean; organization_id: string; owner_id: string };
+
+// ── Models ──────────────────────────────────────────────────────────────────────────────
+/** `CompatibleEndpoint` — the closed set of endpoint names a model card may list. */
+export const COHERE_ENDPOINTS = ['chat', 'embed', 'classify', 'summarize', 'rerank', 'rate', 'generate'] as const;
+export type CohereEndpoint = (typeof COHERE_ENDPOINTS)[number];
+
+export type CohereModelCard = {
+  name: string;
+  endpoints: CohereEndpoint[];
+  finetuned: boolean;
+  context_length: number;
+  tokenizer_url: string | null;
+  default_endpoints: CohereEndpoint[];
+  is_deprecated?: boolean;
+};
+
+// ── Streaming ───────────────────────────────────────────────────────────────────────────
+/**
+ * A single Server-Sent Event the streaming path emits (collected in tests, socketed by the
+ * server). `data` is the JSON payload; the terminator is signalled with `done: true` — cohere-ai's
+ * `core.Stream` is constructed with `eventShape: { type: 'sse', streamTerminator: '[DONE]' }`, so
+ * `data: [DONE]` is what ends a v2 chat stream.
+ */
+export type SseEvent = { data?: Record<string, unknown>; done?: boolean };
+
+/** A sink the streaming path writes events into (an injected collector in tests / a real HTTP SSE
+ *  writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;

package/src/index.ts

@@ -0,0 +1,159 @@
+// @volter/twin-cohere — the Cohere twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. Cohere's API is TWO protocols on one host: the v1 surface
+// (`/v1/chat` with a single `message` string, `/v1/embed` answering flat float vectors,
+// `/v1/rerank`, `/v1/classify`, `/v1/tokenize`, `/v1/models`, datasets, connectors, embed jobs)
+// and the v2 surface (`/v2/chat` with structured `messages[]`, `/v2/embed` keyed by embedding
+// type, `/v2/rerank`). Both are modeled — vendor-faithfully, and as the DIFFERENT protocols they
+// are rather than as a versioned alias. (Cohere is an API-first vendor: its dashboard is
+// incidental tooling for keys, billing and usage, not where the work happens —
+// docs/contributing/architecture.md C1b — so this pack ships no mirror.)
+//
+// THE HONEST CARVE-OUT: the twin cannot run the model, so every generative endpoint returns a
+// DETERMINISTIC STUB (clearly labeled `[twin-stub:<model>]`), never pretending to be real
+// inference. Everything around it — the wire protocol — is faithful. (Conformance + capability
+// tooling live in @volter/world-tooling, a dev dependency — NOT re-exported here, per E2.)
+export { handleCohereTwinRequest, buildChatV2, streamChatV2, COHERE_ROUTER_SURFACE, COHERE_CLOSED_SETS } from './cohere-twin.ts';
+export type { CohereRequest, CohereResponseEnvelope, ChatV2Args } from './cohere-twin.ts';
+export { createCohereTwinFetch, createCohereTwinServer, type CohereTwinFetchOptions } from './cohere-server.ts';
+export { cohereScenarioAdapter, createCohereScenarioEngine, loadCohereScenarioDocument, realizeCohereRespond } from './cohere-scenario.ts';
+export type { CohereScenarioEngine, CohereScenarioRequest, CohereScenarioRespond, ScenarioToolCall, ScriptedResult } from './cohere-scenario.ts';
+export { COHERE_MODELS, COHERE_ENDPOINTS, findModel, modelServes } from './cohere-models.ts';
+export {
+  base64Embedding,
+  classifyText,
+  COHERE_OUTPUT_DIMENSIONS,
+  cohereId,
+  contentToText,
+  countInputTokens,
+  embedDimensions,
+  estimateTokens,
+  fnv1a,
+  lastUserText,
+  preferredTokenId,
+  pseudoEmbedding,
+  quantizeEmbedding,
+  rerankScore,
+  segmentText,
+  stubAssistantText,
+  stubToolArguments,
+  stubToolCall,
+  stubToolPlan,
+  stubV1Text,
+  toolCallId,
+  toolNames,
+} from './cohere-stub.ts';
+export {
+  COHERE_EMBEDDING_TYPES,
+  COHERE_ENDPOINTS as COHERE_COMPATIBLE_ENDPOINTS,
+  COHERE_FINISH_REASONS,
+  COHERE_INPUT_TYPES,
+  COHERE_TRUNCATE,
+  COHERE_V1_FINISH_REASONS,
+} from './cohere-types.ts';
+export type {
+  CohereApiError, CohereApiMeta, CohereAssistantContentItem, CohereAssistantMessage,
+  CohereChatV1Response, CohereChatV2Response, CohereClassifyResponse, CohereEmbedV1FloatsResponse,
+  CohereEmbedV2Response, CohereEmbeddingType, CohereFinishReason, CohereInputType,
+  CohereMessageV2, CohereModelCard, CohereRerankResponse, CohereToolCallV2, CohereUsage,
+  CohereV1FinishReason,
+  SseEvent, SseSink,
+} from './cohere-types.ts';
+export {
+  COHERE_API_BASE,
+  cohereRequestForAction,
+  fullSyncCohere,
+  liveCohereExecute,
+  mapConnector,
+  mapDataset,
+  mapEmbedJob,
+  pollTimestamp,
+  pullCohereState,
+  pushCohereAction,
+  pushPendingCohereActions,
+  syncCohereFromReal,
+  unpushableReason,
+} from './cohere-connector.ts';
+export type { CohereExecute, LiveCohereOptions } from './cohere-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveCohereExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Cohere's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `CohereBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  COHERE_BUDGET_CEILING,
+  COHERE_BUDGET_MAX_RETRY_AFTER_S,
+  COHERE_BUDGET_WINDOW_MS,
+  COHERE_CALL_WEIGHTS,
+  COHERE_RATE_BUDGET,
+  CohereBudget,
+  CohereBudgetError,
+  cohereBudgetPath,
+  cohereCallWeight,
+} from './cohere-budget.ts';
+export type { CohereBudgetErrorKind, CohereBudgetOptions, CohereBudgetReservation, CohereBudgetSnapshot } from './cohere-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it, and it is the SINGLE
+// HOME for this vendor's world-facing facts. `bun scripts/pack-facts.ts` compiles `adoption` /
+// `hosts` / `endpointEnv` into packages/world-core/generated/pack-facts.json; re-run it
+// after ANY edit below or the drift gate (scripts/pack-facts.test.ts) goes RED.
+import type { TwinPack } from '@volter/world-core';
+import { COHERE_RATE_BUDGET as RATE_BUDGET } from './cohere-budget.ts';
+export const pack: TwinPack = {
+  vendor: 'cohere',
+  // The SAME object cohere-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'generative',
+  bin: 'world-cohere',
+  // The subject types this twin projects. `token` is the LEARNED TOKENIZER VOCABULARY that
+  // `/v1/tokenize` observes and `/v1/detokenize` folds — twin-local state with no vendor
+  // endpoint, which is why the connector refuses to push it type-wide.
+  resources: ['dataset', 'connector', 'embed_job', 'token'],
+  specSource: 'Cohere API v1 + v2, grounded in the two installed SDKs (cohere-ai@8.1.0 — the Fern-generated client, whose serialization/**/*.d.ts `interface Raw` blocks carry the snake_case WIRE keys — and @ai-sdk/cohere@4.0.35, whose zod schemas are the stricter second transcription of chat/embed/rerank); envelope-faithful, model output is a labeled stub',
+  description: 'Cohere twin — faithful v1 AND v2 protocol envelopes (chat with SSE and NDJSON streaming, tool calls, UPPER-CASE finish reasons, two-level usage), deterministic embeddings across all six embedding_types, rerank/classify, a learned tokenizer vocabulary, the real model catalog, and stateful datasets / connectors / embed jobs; generative output is a labeled stub.',
+  // cohere-ai addresses the same origin with `v1/…` and `v2/…` paths (`core.url.join(environment,
+  // "v2/chat")`); @ai-sdk/cohere's default baseURL is 'https://api.cohere.com/v2'. The common
+  // prefix both share is the origin root, so the browser-routing prefix is '/'.
+  browserRouting: { apiPathPrefix: '/', loaderHost: 'https://api.cohere.com' },
+
+  // ADOPTION — how an app repo betrays that it talks to this vendor (§7 point 11), declared HERE
+  // rather than in the central SDK_TWINS / ENV_STEM_VENDORS maps (declaring a fact in both homes
+  // throws at module init).
+  //   • sdks — the TWO official npm clients of the surface this pack models: Cohere's own
+  //     Fern-generated client and the Vercel AI SDK provider. `cohere-ai` was on covers.ts's
+  //     UNKNOWN_DEP_KNOWN_SERVICES list (the curated "well-known client with NO twin pack" set)
+  //     until this pack was born; that entry is deleted in the same commit, because
+  //     scripts/packless-claims.test.ts is RED on any name both packless-listed and pack-claimed.
+  //   • envStems — the two SDKs read DIFFERENT variables and both are claimed: cohere-ai's
+  //     `BearerAuthProvider` falls back to `CO_API_KEY` (`const ENV_TOKEN = "CO_API_KEY"`), while
+  //     @ai-sdk/cohere calls `loadApiKey({ environmentVariableName: 'COHERE_API_KEY' })`. Claiming
+  //     only one would let an app configured for the other read as uncovered. The stems are
+  //     written bare because the overlay lowercases and the detector strips non-alphanumerics.
+  //   • NO `scopes` entry: Cohere owns no npm scope. `@ai-sdk/` belongs to Vercel and is shared by
+  //     every provider, so claiming it would attribute openai/anthropic/mistral traffic here.
+  adoption: {
+    // Cohere's official Python SDK (`cohere-ai` on npm, `cohere` on PyPI).
+    pypi: ['cohere'],
+    sdks: ['cohere-ai', '@ai-sdk/cohere'],
+    envStems: ['COHERE', 'CO'],
+  },
+
+  // INTERCEPTION (§7 point 8). ONE host: `CohereEnvironment` in cohere-ai@8.1.0's
+  // environments.d.ts declares exactly `Production: "https://api.cohere.com"` and nothing else —
+  // no regional or staging siblings — and @ai-sdk/cohere's default baseURL is that host plus
+  // `/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' }],
+
+  // 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
+  // only env var anywhere in its source is `CO_API_KEY` (plus the AWS credential names its Bedrock
+  // client uses); @ai-sdk/cohere takes `options.baseURL` and reads only `COHERE_API_KEY`.
+  // 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.',
+};