dsh-any-deepseek 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benard. Y
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# dsh-any-deepseek
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One **DeepSeek V4.1 Flash** provider for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+Instead of configuring every third-party DeepSeek relay as its own provider, install one
+provider with **exactly one model**, paste a key per channel in the settings panel, and pick
+which channel is live. Token usage is booked **per real upstream**, so you can see what each
+relay actually cost you in tokens.
+
+```text
+composer → any-deepseek / deepseek-v4.1-flash
+                │
+                ├─ channel selected in the panel (manual switch, v1)
+                ├─ key resolved from ctx.credentials per request
+                └─ forwarded as openai-completions to the channel's endpoint
+```
+
+## Why
+
+- **One row in the model picker.** Your relay list stops being N provider groups.
+- **Only a key is user input.** Endpoint, upstream model id, context window, output cap and
+  compatibility flags ship in the plugin's own preset table.
+- **Per-channel accounting.** Input / cache-read / cache-write / output are recorded per
+  request and grouped by the channel that actually served it.
+- **Keys never enter configuration.** They live in the harness credential store; the config
+  only carries the reference name, exactly like the official Models page.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-any-deepseek
+```
+
+Then restart DSH and open **Settings → Any DeepSeek**.
+
+> **Restart is required for a first install** — the profile's layer list changed, and the
+> composing graph is built at boot. Editing an already-installed plugin's client half reloads
+> in the browser without a restart; its node half does not.
+>
+> `dsh plugin` forwards its arguments to pnpm, so `add <spec>` accepts a registry name, a
+> tarball path, or a local directory (which installs as a symlink).
+
+## Configuration
+
+Everything lives under the `dsh-any-deepseek` settings namespace — that is the **profile entry
+id** from `cordis.patch.yml`, and it is what the panel binds to:
+
+```yaml
+dsh-any-deepseek:
+  current: opencode-go          # the live channel (manual)
+  channels:
+    opencode-go:
+      apiKeyEnv: ANY_DEEPSEEK_OPENCODE_GO_KEY
+      enabled: true
+    commandcode:
+      apiKeyEnv: ANY_DEEPSEEK_COMMANDCODE_KEY
+      enabled: true
+  usage:
+    enabled: true
+```
+
+`channels.<id>` may be either:
+
+- **preset-backed** — `preset: opencode-go` plus optional overrides; or
+- **fully declared** — `baseURL` + `model` are required; `api` defaults to
+  `openai-completions`, and `contextWindow` / `maxTokens` fall back to documented defaults
+  (the panel shows a warning next to the row when a default was applied rather than declared).
+
+### Channels vs. protocols
+
+`openai-completions` is the default and the recommended protocol: it is what almost every
+relay speaks, it exposes the largest compatibility surface (~20 switches), and its usage
+normalization already reconciles the three cache-token spellings relays use
+(`prompt_tokens_details.cached_tokens`, `prompt_cache_hit_tokens`, top-level `cached_tokens`).
+
+Set `api` on one channel only when that relay speaks something else (`openai-responses`,
+`anthropic-messages`). The picker never changes per channel behind your back.
+
+### Switching channels
+
+v1 is deliberately manual. A channel that fails reports its error; it does not silently fail
+over to another one. Switching invalidates the prompt cache for the running conversation, so
+switch at a natural boundary (or start a new session).
+
+## Usage accounting
+
+The ledger is append-only JSONL, split by month, under the harness home:
+
+```text
+~/.dsh/any-deepseek/usage-YYYY-MM.jsonl
+```
+
+One line per request:
+
+```json
+{"at":"2026-10-19T10:12:03+08:00","channel":"opencode-go","model":"deepseek-v4.1-flash","ok":true,"ms":4210,"firstTokenMs":810,"usage":{"input":812,"output":96,"cacheRead":40960,"cacheWrite":0,"reasoning":0,"total":41868}}
+```
+
+`usage` is `null` when a relay does not report token counts — the panel shows `—`, never `0`,
+because a zero would read as "this request was free".
+
+**Counting convention.** `TokenUsage` counts are *disjoint*: `input` is uncached input only,
+cache reads and writes are reported separately, and the three together are the billable input.
+The stats table states this next to the numbers.
+
+## Development
+
+```bash
+pnpm install
+pnpm run typecheck     # host types come from pinned devDependencies
+pnpm run test          # pure layers only; no harness needed
+pnpm run build         # lib/index.js + lib/client.js
+```
+
+The pure layers (`presets`, `channels`, `route`, `usage-ledger`) do not import the harness and
+are covered by the unit tests. The adapter and panel talk to the host through public seams
+only.
+
+## Boundaries
+
+- Does not modify the harness, and does not replace `deepseek-official` or `llm-pi-ai` routes.
+- Exposes exactly one model id. Upstream model ids differ per relay and are mapped in presets.
+- No cost estimation (no price table), no automatic failover (v1), no multi-model aggregation.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Any-deepseek bundle layer (declared by package.json `dsh.bundle.patch`).
+#
+# The entry id becomes the settings namespace: the panel, the config document and every
+# recorded reference are all keyed by `dsh-any-deepseek`, so renaming the id would move the
+# user's stored configuration. Keep it stable.
+- insert:
+    - id: dsh-any-deepseek
+      name: 'dsh-any-deepseek'

package/lib/adapter.d.ts

@@ -0,0 +1,126 @@
+/**
+ * adapter.ts — the harness-side `LlmAdapter` that fans one model out to many relays.
+ *
+ * ## The shape of the problem
+ *
+ * The harness asks an adapter for exactly two kinds of thing: "what models do you serve" and
+ * "stream this request". Everything between — which relay is live, which key it uses, what it
+ * calls the model, how it spells its thinking parameters — is this file's business, and none
+ * of it is visible to the harness.
+ *
+ * ## Why a new pi-ai collection per call
+ *
+ * The pi-ai adapter makes the argument and it applies here unchanged: `streamSimple()` resolves
+ * the provider lazily, after the credential await, so a collection mutated between requests
+ * would let a call that started under one configuration finish under another. Building the
+ * collection per call makes a settings change reach the next request and never the current one.
+ * The cost is one small object graph per request, which is noise next to an HTTP call.
+ *
+ * ## Why the ledger is written here
+ *
+ * `usage` only exists at this boundary: the harness's token meter replays a session log to
+ * estimate context pressure, which is a different question from "what did this relay report for
+ * this request". The ledger write cannot fail the call — accounting is not allowed to be a
+ * single point of failure for model traffic.
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { type Api, type AssistantMessage, type AssistantMessageEvent, type Context as PiContext, type Model } from '@earendil-works/pi-ai';
+import type { ResolvedChannel } from './channels.js';
+import type { LedgerEntry } from './usage-ledger.js';
+/** The single provider route this plugin owns. */
+export declare const PROVIDER_ID = "any-deepseek";
+/** Display name for the route in provider selectors. */
+export declare const PROVIDER_NAME = "Any DeepSeek";
+/** What the adapter needs from the plugin, so it can be tested without a harness context. */
+export interface AdapterDeps {
+    /** Enabled, resolved channels in configuration order. */
+    channels: () => readonly ResolvedChannel[];
+    /** The configured channel id. */
+    current: () => string | undefined;
+    /** Resolve a credential reference to its value; undefined when unconfigured. */
+    resolveKey: (ref: string) => Promise<string | undefined>;
+    /** Record one finished request. Must never throw. */
+    record: (entry: LedgerEntry) => Promise<void>;
+    /** Clock, injectable so tests are deterministic. */
+    now: () => Date;
+    /** Monotonic-ish millisecond clock for durations. */
+    elapsed: () => number;
+}
+/** One finished call, as the adapter observed it. */
+interface CallOutcome {
+    ok: boolean;
+    code?: string;
+    usage: TokenUsage | null;
+}
+/**
+ * Build the pi-ai model entry for one channel.
+ *
+ * The advertised id (`deepseek-v4.1-flash`) never reaches the wire here: each channel's own
+ * `model` does. That substitution is the entire reason this layer exists.
+ * @param channel - the resolved channel.
+ * @returns a pi-ai chat model describing that relay's view of the model.
+ */
+export declare function buildPiModel(channel: ResolvedChannel): Model<Api>;
+/**
+ * Translate one harness request into a pi-ai context.
+ *
+ * The harness already projects images and files before an adapter sees them, so this is a
+ * straightforward content mapping; anything the harness did not project is passed through.
+ * @param options - the harness request.
+ * @returns a pi-ai context plus the one-shot system prompt, when the caller set one.
+ */
+export declare function toPiContext(options: GenerateOptions): PiContext;
+/** Map pi-ai usage onto the harness's disjoint counters. */
+export declare function toTokenUsage(usage: AssistantMessage['usage']): TokenUsage;
+/**
+ * Map pi-ai events onto harness stream chunks.
+ *
+ * The two protocols agree on the important part (indexed blocks, deltas, one terminal event),
+ * so this is a rename table plus the terminal handling. Failures arrive as an `error` event
+ * rather than a throw — pi-ai never throws mid-stream — which is why the terminal event is the
+ * only place a failure code can be produced.
+ * @param events - the pi-ai event stream.
+ * @param onOutcome - called once with the terminal outcome, before the finish chunk.
+ * @returns harness chunks, ending with `finish`.
+ */
+export declare function toStreamChunks(events: AsyncIterable<AssistantMessageEvent>, onOutcome: (outcome: CallOutcome) => void): AsyncGenerator<StreamChunk>;
+/**
+ * Assign a provider-neutral failure code.
+ *
+ * The harness routes retries on these codes, so the mapping matters more than the message. A
+ * relay's own wording is preserved in the message; only the class is normalized here.
+ * @param message - the terminal pi-ai message.
+ * @returns a harness failure code.
+ */
+export declare function classifyFailure(message: AssistantMessage): string;
+/**
+ * The adapter. One instance serves the single provider route.
+ */
+export declare class AnyDeepSeekAdapter extends LlmAdapter {
+    private readonly deps;
+    constructor(deps: AdapterDeps);
+    providerInfo(provider: string): LlmProviderInfo;
+    /**
+     * Advertise exactly one model.
+     *
+     * A relay that is missing a key still gets no catalog entry — the picker then hides the whole
+     * group, which is the harness's own convention for a dormant provider — but the settings page
+     * keeps its entry, so the user can go fix it.
+     */
+    listModels(_provider: string): Promise<LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /**
+     * Bind the model metadata and the dispatch to one channel generation.
+     *
+     * The harness calls `prepareCall` before logging a request header and dispatches later; binding
+     * here is what stops a panel change from landing in the middle of a recorded step.
+     */
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncGenerator<StreamChunk>;
+    /** The channel the panel has selected, if any (used for model metadata). */
+    private selected;
+}
+/** Re-export the credential helper so callers build references the same way the adapter does. */
+export { credentialRef };

package/lib/channels.d.ts

@@ -0,0 +1,108 @@
+/**
+ * channels.ts — the configuration entry → resolved channel profile layer.
+ *
+ * ## Two shapes, one resolution
+ *
+ * A channel entry is either preset-backed (`preset: opencode-go`, key only) or fully declared
+ * (every field present). Both resolve through {@link resolveChannel} to the same
+ * {@link ResolvedChannel}, so the adapter never branches on which shape the user chose.
+ *
+ * ## Why a missing field is an error rather than a default
+ *
+ * A partially declared custom channel is a configuration mistake, not a preference: guessing
+ * the endpoint would send the user's key somewhere they did not name. The only defaults
+ * applied are the ones the host itself documents (capacities), and they are applied *loudly*
+ * in the returned `warnings` so the panel can show them.
+ */
+import { ADVERTISED_MODEL_ID, type ChannelApi, type ChannelModality } from './presets.js';
+/** One channel as the configuration document stores it. */
+export interface ChannelEntry {
+    /** Human label; falls back to the preset's or the id. */
+    label?: string;
+    /** Preset id this entry references. Mutually exclusive with a fully declared channel. */
+    preset?: string;
+    /** Wire protocol. Required for a channel that names no preset. */
+    api?: string;
+    /** Endpoint. Required for a channel that names no preset. */
+    baseURL?: string;
+    /** Upstream model id. Required for a channel that names no preset. */
+    model?: string;
+    /** Credential reference (environment-variable name). Required. */
+    apiKeyEnv?: string;
+    /** Whether the panel offers this channel. Absent means enabled. */
+    enabled?: boolean;
+    /** Overrides applied on top of a preset, or the whole declaration for a custom channel. */
+    contextWindow?: number;
+    maxTokens?: number;
+    input?: string[];
+    reasoningEfforts?: Record<string, string | null>;
+    compat?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+/** A channel with every fact the adapter needs, and nothing optional left to guess. */
+export interface ResolvedChannel {
+    /** Stable channel id (the configuration key). */
+    id: string;
+    label: string;
+    api: ChannelApi;
+    baseURL: string;
+    /** Upstream model id, as the relay spells it. */
+    model: string;
+    apiKeyEnv: string;
+    contextWindow: number;
+    maxTokens: number;
+    input: ChannelModality[];
+    reasoningEfforts?: Record<string, string | null>;
+    compat?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    /** Facts the user should see because a default was applied rather than declared. */
+    warnings: string[];
+}
+/** Why one entry could not be resolved. */
+export interface ChannelProblem {
+    id: string;
+    code: 'UNKNOWN_PRESET' | 'MISSING_API_KEY_REF' | 'MISSING_FIELD' | 'INVALID_API' | 'UNKNOWN_KEY';
+    detail: string;
+}
+/** Result of resolving a whole configuration's channel map. */
+export interface ChannelResolution {
+    /** Channels that resolved, keyed by id, in configuration order. */
+    channels: Map<string, ResolvedChannel>;
+    /** Entries that could not resolve; each is reported rather than skipped silently. */
+    problems: ChannelProblem[];
+}
+/**
+ * Resolve one channel entry.
+ *
+ * Precedence is preset first, entry second: an entry that names a preset inherits everything
+ * and overrides only what it declares. A custom entry (no preset) must supply the endpoint
+ * facts itself.
+ * @param id - configuration key, used verbatim as the channel's identity.
+ * @param raw - the entry as stored.
+ * @returns the resolved channel, or the problem that prevented resolution.
+ */
+export declare function resolveChannel(id: string, raw: unknown): {
+    ok: true;
+    channel: ResolvedChannel;
+} | {
+    ok: false;
+    problem: ChannelProblem;
+};
+/**
+ * Resolve every channel in one configuration document.
+ *
+ * Problems are collected, never thrown: one broken channel must not make the rest of the
+ * panel unusable, and the panel needs the per-entry reason to show next to the row.
+ * @param entries - the configuration's `channels` map.
+ * @returns resolved channels plus every problem found.
+ */
+export declare function resolveChannels(entries: unknown): ChannelResolution;
+/**
+ * Channels that should appear and serve requests: resolved AND not explicitly disabled.
+ * @param resolution - output of {@link resolveChannels}.
+ * @param entries - the same configuration map, read again for the `enabled` flags.
+ * @returns enabled channels, configuration order preserved.
+ */
+export declare function enabledChannels(resolution: ChannelResolution, entries: unknown): ResolvedChannel[];
+/** The advertised model id, re-exported so callers need one import for routing facts. */
+export { ADVERTISED_MODEL_ID };