@volter/twin-deepseek 0.1.0

package/src/deepseek-types.ts

@@ -0,0 +1,201 @@
+// Shared wire-shape types for the DeepSeek Platform API. These mirror the REAL vendor JSON shapes
+// as published by DeepSeek's own API reference (api-docs.deepseek.com, read 2026-08-31) and by the
+// zod schemas `@ai-sdk/deepseek@3.0.37` decodes responses with (src/chat/deepseek-chat-api-types.ts,
+// src/files/deepseek-files-api.ts). The twin never imports the SDK at runtime; the SDK is exercised
+// only in *.test.ts.
+//
+// DEEPSEEK IS OPENAI-COMPATIBLE, NOT OPENAI, and the differences below are load-bearing — they are
+// exactly what a "copy the openai pack" twin gets wrong (ADDING_A_TWIN.md §0, the compatible-vendor
+// warning). The REJECTIONS are the fidelity surface:
+//   • there is NO `/v1` path prefix — `base_url` is `https://api.deepseek.com` and the endpoint is
+//     `/chat/completions` (api-docs.deepseek.com "Your First API Call", read 2026-08-31);
+//   • the documented error table has NO 404 and DOES have 402 (Insufficient Balance) and
+//     422 (Invalid Parameters) — OpenAI 400s where DeepSeek 422s
+//     (api-docs.deepseek.com/quick_start/error_codes);
+//   • `usage` carries the KV-cache split `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
+//     (OpenAI reports `prompt_tokens_details.cached_tokens` instead);
+//   • the assistant message/delta carries `reasoning_content` (OpenAI has no such field);
+//   • `finish_reason` includes DeepSeek's own `insufficient_system_resource`;
+//   • the end-user identifier is `user_id` (regex + 512-char cap), NOT OpenAI's `user`;
+//   • `response_format` accepts ONLY `text` and `json_object` — `json_schema` is OpenAI-only;
+//   • `n`, `seed`, `logit_bias` and `top_k` are not DeepSeek parameters at all;
+//   • `frequency_penalty` / `presence_penalty` are DEPRECATED but accepted with NO effect (they
+//     must NOT be errors), as are `temperature` / `top_p` while thinking is enabled;
+//   • assistant-prefix completion and strict tool calls live only under the `/beta` base URL;
+//   • a `GET /models` row is `{id, object, owned_by}` — no `created`, no `context_window`.
+
+// ── Chat Completions ────────────────────────────────────────────────────────────────────
+/** A chat message param as the caller sends it (content is a string OR a content-part array). */
+export type DeepSeekMessageParam = {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content?: string | Array<Record<string, unknown>> | null;
+  /** Optional participant name — supported on system, user and assistant messages only.
+   *  `@ai-sdk/deepseek` warns `unsupported: message name on tool messages`. */
+  name?: string;
+  /** Beta-only: continue this assistant message's content instead of starting a new turn.
+   *  Requires the `/beta` base URL and must be the FINAL message. */
+  prefix?: boolean;
+  /** The chain-of-thought DeepSeek returned on a previous assistant turn. When the request carries
+   *  `tools`, DeepSeek requires previous turns to carry it back or answers 400
+   *  (api-docs.deepseek.com/guides/thinking_mode). */
+  reasoning_content?: string | null;
+  tool_calls?: DeepSeekToolCall[];
+  tool_call_id?: string;
+};
+
+/** A function tool_call inside an assistant message (faithful shape). */
+export type DeepSeekToolCall = {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+};
+
+/**
+ * The chat.completion `usage` object. `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` are
+ * DeepSeek's KV-cache accounting and always sum to `prompt_tokens`
+ * (api-docs.deepseek.com/guides/kv_cache: "the number of tokens in the input of this request that
+ * resulted in a cache hit" / "…that did not result in a cache hit"). `@ai-sdk/deepseek` reads both
+ * into `providerMetadata.deepseek.promptCacheHitTokens` / `…MissTokens` and derives
+ * `usage.inputTokens.cacheRead` from the hit count (src/chat/convert-to-deepseek-usage.ts).
+ */
+export type DeepSeekUsage = {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  prompt_cache_hit_tokens: number;
+  prompt_cache_miss_tokens: number;
+  prompt_tokens_details?: { cached_tokens: number };
+  completion_tokens_details?: { reasoning_tokens: number };
+};
+
+/**
+ * The assistant message DeepSeek returns. NOTE `reasoning_content` (no OpenAI counterpart) and the
+ * absence of OpenAI's `refusal` / `annotations`.
+ */
+export type DeepSeekAssistantMessage = {
+  role: 'assistant';
+  content: string | null;
+  reasoning_content?: string | null;
+  tool_calls?: DeepSeekToolCall[];
+};
+
+/** One entry of a `logprobs.content` / `logprobs.reasoning_content` array. */
+export type DeepSeekLogprob = {
+  token: string;
+  logprob: number;
+  bytes: number[] | null;
+  top_logprobs: Array<{ token: string; logprob: number; bytes: number[] | null }>;
+};
+
+/** DeepSeek splits logprobs by channel: generated content AND reasoning content. */
+export type DeepSeekLogprobs = {
+  content?: DeepSeekLogprob[] | null;
+  reasoning_content?: DeepSeekLogprob[] | null;
+};
+
+/** `insufficient_system_resource` is DeepSeek's own value — `@ai-sdk/deepseek` maps it to the
+ *  unified `error` finish reason (src/chat/map-deepseek-finish-reason.ts). */
+export type DeepSeekFinishReason = 'stop' | 'length' | 'content_filter' | 'tool_calls' | 'insufficient_system_resource';
+
+export type DeepSeekChoice = {
+  index: number;
+  message: DeepSeekAssistantMessage;
+  logprobs: DeepSeekLogprobs | null;
+  finish_reason: DeepSeekFinishReason;
+};
+
+/** The unary chat.completion response envelope (faithful shape). */
+export type DeepSeekChatCompletion = {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: DeepSeekChoice[];
+  usage: DeepSeekUsage;
+  system_fingerprint: string;
+};
+
+// ── FIM completions (beta) ──────────────────────────────────────────────────────────────
+/** `POST https://api.deepseek.com/beta/completions` — fill-in-the-middle. `object` is
+ *  `text_completion` and the choice carries `text`, not a message. */
+export type DeepSeekCompletionChoice = {
+  index: number;
+  text: string;
+  finish_reason: 'stop' | 'length' | 'content_filter' | 'insufficient_system_resource';
+  logprobs: { tokens: string[]; token_logprobs: number[]; text_offset: number[]; top_logprobs: Array<Record<string, number>> } | null;
+};
+export type DeepSeekCompletion = {
+  id: string;
+  object: 'text_completion';
+  created: number;
+  model: string;
+  choices: DeepSeekCompletionChoice[];
+  usage: DeepSeekUsage;
+  system_fingerprint: string;
+};
+
+// ── Models ──────────────────────────────────────────────────────────────────────────────
+/**
+ * A DeepSeek model row. THREE keys, and that is the whole object: DeepSeek's own
+ * `GET /models` example response is `{"id": "...", "object": "model", "owned_by": "deepseek"}`
+ * (api-docs.deepseek.com/api/list-models, read 2026-08-31). OpenAI's row additionally carries
+ * `created`; DeepSeek's does not, and inventing one would be surface the vendor does not have.
+ */
+export type DeepSeekModel = {
+  id: string;
+  object: 'model';
+  owned_by: string;
+};
+
+// ── User balance ────────────────────────────────────────────────────────────────────────
+/** `GET /user/balance` (api-docs.deepseek.com/api/get-user-balance). Balances are STRINGS. */
+export type DeepSeekBalanceInfo = {
+  currency: 'CNY' | 'USD';
+  total_balance: string;
+  granted_balance: string;
+  topped_up_balance: string;
+};
+export type DeepSeekBalance = {
+  is_available: boolean;
+  balance_infos: DeepSeekBalanceInfo[];
+};
+
+// ── Files ───────────────────────────────────────────────────────────────────────────────
+/** The file object (api-docs.deepseek.com/guides/files_api; validated key-for-key by
+ *  `@ai-sdk/deepseek`'s `deepSeekFilesResponseSchema`). `expires_at` appears only when an
+ *  expiration was requested. */
+export type DeepSeekFile = {
+  id: string;
+  object: 'file';
+  bytes: number;
+  created_at: number;
+  filename: string;
+  purpose: 'user_data';
+  expires_at?: number;
+};
+
+// ── Errors ──────────────────────────────────────────────────────────────────────────────
+/**
+ * DeepSeek's error envelope. `message` is the only REQUIRED key; `type`, `param` and `code` are
+ * nullish. This is not folklore from a rendered docs example — it is the zod schema
+ * `@ai-sdk/deepseek@3.0.37` actually decodes every failed response with
+ * (`deepSeekErrorSchema`, src/chat/deepseek-chat-api-types.ts), which is the stronger first-party
+ * oracle (ADDING_A_TWIN.md §6, "When first-party sources conflict").
+ */
+export type DeepSeekError = {
+  error: {
+    message: string;
+    type?: string | null;
+    param?: unknown;
+    code?: string | number | null;
+  };
+};
+
+// ── Streaming ───────────────────────────────────────────────────────────────────────────
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+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,133 @@
+// @volter/twin-deepseek — the DeepSeek twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The DeepSeek Platform API: a vendor-faithful protocol envelope (chat
+// completions/streaming/tool_calls, `reasoning_content`, DeepSeek's KV-cache-bearing `usage`), the
+// published model catalog, the account balance, beta FIM completion, and a STATEFUL image Files API
+// — over an event/action log. (DeepSeek is an API-first vendor: platform.deepseek.com is a
+// keys/billing/usage console, not where the work happens — docs/contributing/architecture.md C1b — so this pack ships
+// no mirror.)
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so POST /chat/completions returns a
+// DETERMINISTIC STUB completion (clearly labeled), its `reasoning_content` is a labeled stub, and
+// POST /beta/completions returns a labeled FIM stub — never pretending to be real inference.
+// Everything around them — the wire protocol, and above all WHAT DEEPSEEK REFUSES — is faithful.
+// (Conformance + capability tooling live in @volter/world-tooling, a dev dependency — NOT
+// re-exported here, per E2.)
+export { handleDeepSeekTwinRequest, streamChat, buildChatCompletion, DEEPSEEK_BETA_PREFIX, DEEPSEEK_ANTHROPIC_PREFIX } from './deepseek-twin.ts';
+export type { DeepSeekRequest, DeepSeekResponseEnvelope } from './deepseek-twin.ts';
+export { createDeepSeekTwinFetch, createDeepSeekTwinServer, type DeepSeekTwinFetchOptions } from './deepseek-server.ts';
+export { DEEPSEEK_MODELS, FIM_MODELS, RETIRED_MODEL_IDS, VISION_MODELS, findModel, isThinkingModel } from './deepseek-models.ts';
+export { cacheHitTokens, canonicalMessage, prefixId, prefixKey, recordCachePrefixes } from './deepseek-cache.ts';
+export {
+  buildUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, messageTokens,
+  stubAssistantText, stubFimText, stubFingerprint, stubJsonObject, stubReasoningText,
+  stubToolArguments, stubToolCall,
+} from './deepseek-stub.ts';
+export type {
+  DeepSeekAssistantMessage, DeepSeekBalance, DeepSeekBalanceInfo, DeepSeekChatCompletion,
+  DeepSeekChoice, DeepSeekCompletion, DeepSeekCompletionChoice, DeepSeekError, DeepSeekFile,
+  DeepSeekFinishReason, DeepSeekLogprob, DeepSeekLogprobs, DeepSeekMessageParam, DeepSeekModel,
+  DeepSeekToolCall, DeepSeekUsage, SseEvent, SseSink,
+} from './deepseek-types.ts';
+export { createDeepSeekScenarioEngine, deepseekScenarioAdapter, loadDeepSeekScenarioDocument, realizeDeepSeekRespond } from './deepseek-scenario.ts';
+export type { DeepSeekScenarioEngine, DeepSeekScenarioRequest, DeepSeekScenarioRespond, ScenarioToolCall, ScriptedResult } from './deepseek-scenario.ts';
+export {
+  fullSyncDeepSeek,
+  externalIdFor,
+  deepseekRequestForAction,
+  liveDeepSeekExecute,
+  mapBalance,
+  mapFile,
+  mapModel,
+  pullDeepSeekState,
+  pushDeepSeekAction,
+  pushPendingDeepSeekActions,
+  syncDeepSeekFromReal,
+  unpushableReason,
+} from './deepseek-connector.ts';
+export type { DeepSeekExecute, LiveDeepSeekOptions } from './deepseek-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveDeepSeekExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is DeepSeek'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
+// `DeepSeekBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  DEEPSEEK_BUDGET_CEILING,
+  DEEPSEEK_BUDGET_MAX_RETRY_AFTER_S,
+  DEEPSEEK_BUDGET_WINDOW_MS,
+  DEEPSEEK_CALL_WEIGHTS,
+  DEEPSEEK_RATE_BUDGET,
+  DeepSeekBudget,
+  DeepSeekBudgetError,
+  deepseekBudgetPath,
+  deepseekCallWeight,
+} from './deepseek-budget.ts';
+export type { DeepSeekBudgetErrorKind, DeepSeekBudgetOptions, DeepSeekBudgetReservation, DeepSeekBudgetSnapshot } from './deepseek-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import type { TwinPack } from '@volter/world-core';
+import { DEEPSEEK_RATE_BUDGET as RATE_BUDGET } from './deepseek-budget.ts';
+export const pack: TwinPack = {
+  vendor: 'deepseek',
+  // The SAME object deepseek-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-deepseek',
+  // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+  resourcesUnreachable: {
+    'model': 'the vendor catalog',
+    'balance': 'the account ledger the vendor keeps; read-only',
+  },
+  resources: ['model', 'file', 'balance', 'cache_prefix'],
+  specSource: "DeepSeek Platform API — enumerated top-down from api-docs.deepseek.com (quick_start/{error_codes,rate_limit,pricing}, api/{create-chat-completion,create-completion,list-models,get-user-balance}, guides/{kv_cache,thinking_mode,files_api,anthropic_api,chat_prefix_completion}; read 2026-08-31) and cross-checked key-for-key against the zod schemas @ai-sdk/deepseek@3.0.37 encodes/decodes with (src/chat/deepseek-chat-api-types.ts, src/chat/deepseek-chat-language-model{,-options}.ts, src/chat/deepseek-prepare-tools.ts, src/files/deepseek-files{,-api,-options}.ts) plus the provider doc page shipped in that tarball (docs/30-deepseek.mdx). DeepSeek publishes no OpenAPI document. Envelope-faithful; model output, reasoning_content, FIM text and logprob values are labeled deterministic stubs.",
+  description: "DeepSeek Platform API twin — faithful protocol envelope (chat completions/streaming/tool_calls, reasoning_content, KV-cache-split usage), the published catalog, user balance, beta FIM + prefix completion + strict tools, and a stateful image Files API; generative output is a labeled stub and the OpenAI-divergent REFUSALS (402/422, no json_schema, no n/seed/logit_bias/user) are modeled.",
+  // DeepSeek's base_url is https://api.deepseek.com with NO version segment — the endpoint is
+  // `/chat/completions` (api-docs.deepseek.com "Your First API Call", read 2026-08-31). This is the
+  // single most likely thing to be copied wrong from an OpenAI-shaped exemplar.
+  browserRouting: { apiPathPrefix: '/', loaderHost: 'https://api.deepseek.com' },
+  // ADOPTION (adding-a-twin.md §3): how an app repo betrays that it talks to DeepSeek. Declared
+  // HERE, not in world-runtime's central SDK_TWINS/ENV_STEM_VENDORS maps — declaring in both throws.
+  //
+  // `@ai-sdk/deepseek` is the Vercel AI SDK provider and the ONLY first-party npm client of this
+  // surface — DeepSeek publishes no SDK of its own; its docs tell integrators to point the OpenAI
+  // or Anthropic SDK at api.deepseek.com instead ("The DeepSeek API uses an API format compatible
+  // with OpenAI/Anthropic"). That is exactly why `openai` is NOT claimed here: a repo depending on
+  // `openai` is an OpenAI repo unless its base URL says otherwise, and claiming the package would
+  // mis-attribute every OpenAI integration in the census to this pack. The 2026-08-31-b census
+  // bears this out — 5 of the 6 demanding repos signal `@ai-sdk/deepseek`; the sixth (nextchat)
+  // signals the bare `deepseek` stem via DEEPSEEK_API_KEY / DEEPSEEK_URL.
+  //
+  // `envStems: ['DEEPSEEK']` normalizes (covers.ts `normalizeId`: lowercase + strip
+  // non-alphanumerics) to `deepseek`, which is what DEEPSEEK_API_KEY — the one env
+  // `@ai-sdk/deepseek` reads (`loadApiKey({ environmentVariableName: 'DEEPSEEK_API_KEY' })`,
+  // src/deepseek-provider.ts) — and NextChat's DEEPSEEK_URL both reduce to.
+  //
+  // No `scopes`: `@ai-sdk/` is Vercel's scope shared by every provider package, not DeepSeek's.
+  adoption: {
+    // No official Python SDK: DeepSeek's own docs tell Python callers to use the `openai` client
+    // against api.deepseek.com, and that distribution belongs to the openai pack (the pypi list is
+    // the distribution; DEEPSEEK_BASE_URL is what routes it). The `deepseek` name on PyPI is an
+    // unaffiliated third-party wrapper with no adoption, deliberately not claimed.
+    pypi: [],
+    sdks: ['@ai-sdk/deepseek'], envStems: ['DEEPSEEK'],
+  },
+  // INTERCEPTION: the one host every client addresses. `@ai-sdk/deepseek` defaults its baseURL to
+  // `https://api.deepseek.com` and builds every URL as `${baseURL}${path}` for chat and
+  // `${baseURL}/files` for uploads (src/deepseek-provider.ts, src/files/deepseek-files.ts), so the
+  // standard surface, the `/beta` surface and the `/anthropic` surface all live on this one host.
+  // No second host exists anywhere in the SDK.
+  hosts: [{ host: 'api.deepseek.com' }],
+  // The injector intercepts api.deepseek.com (see `hosts`), so a world wires this pack through
+  // DEEPSEEK_TWIN_URL rather than an app-read base-URL var.
+  //
+  // THE GROUNDING FOR THE "NONE" HALF: `@ai-sdk/deepseek` reads exactly ONE environment variable —
+  // `DEEPSEEK_API_KEY`, via `loadApiKey` — and takes `baseURL` as a constructor option only
+  // (`DeepSeekProviderSettings.baseURL`, src/deepseek-provider.ts). There is no DEEPSEEK_BASE_URL
+  // in the SDK, in DeepSeek's docs, or anywhere in the tarball. NextChat's `DEEPSEEK_URL` is that
+  // one application's own convention, not a vendor-documented var, and injecting it would make
+  // `covers` report every DeepSeek world covered while the five repos on `@ai-sdk/deepseek` — which
+  // read no such var — still talked to the real vendor. That is precisely the class of lie
+  // ADDING_A_TWIN.md §7 point 12 forbids ("never invent a <VENDOR>_BASE_URL the app does not read").
+  endpointEnvNone: "no app-read endpoint env: @ai-sdk/deepseek — the only first-party npm client of this surface — reads exactly one environment variable (DEEPSEEK_API_KEY, via loadApiKey in src/deepseek-provider.ts) and takes baseURL as a constructor option, so there is no vendor-documented base-URL var to inject. The injector covers api.deepseek.com instead (see `hosts`). NextChat's DEEPSEEK_URL is one application's own convention, not vendor surface, and claiming it would report a world covered while the SDK-based majority still reached the real vendor.",
+};