@siliconflow-official/dsh-llm-siliconflow 0.1.0-rc.5

package/lib/types/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Register a {@link SiliconFlowAdapter} for the `siliconflow` provider route
+ * on `ctx.llm`, with connection facts resolved per request instead of frozen
+ * at load: the plugin layers its `cordis.yml` entry config under the optional
+ * `llm-siliconflow` user-settings section (`ctx.settings`) and resolves the
+ * API key through the optional credential seam (`ctx.credentials`), so a
+ * changed base URL, catalog, or key reaches the very next request without
+ * restarting anything, while an in-flight stream keeps the facts it started
+ * with. The one registration-captured fact — the retry policy — re-registers
+ * the route in place when it changes.
+ * @module @siliconflow-official/dsh-llm-siliconflow
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm';
+import { type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
+import type { SiliconFlowCatalogModel, SiliconFlowConnectionOptions } from './adapter.ts';
+export { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DISCOVERY_TTL_MS, SiliconFlowAdapter, } from './adapter.ts';
+export { discoverChatModels, listingUrl, readListing } from './discovery.ts';
+export type { SiliconFlowListingEntry } from './discovery.ts';
+export type { SiliconFlowAdapterOptions, SiliconFlowCatalogModel, SiliconFlowConnectionOptions } from './adapter.ts';
+export type * from './types.ts';
+export declare const name = "llm-siliconflow";
+export declare const inject: string[];
+/** Credential reference this plugin reads by default, also used by the setup CLI. */
+export declare const DEFAULT_API_KEY_ENV = "SILICONFLOW_API_KEY";
+/** The single provider route this plugin owns. */
+export declare const PROVIDER = "siliconflow";
+/** Fallback advisory catalog: six widely hosted chat models, also the setup CLI's discovery fallback. */
+export declare const DEFAULT_MODELS: SiliconFlowCatalogModel[];
+/**
+ * Plugin config, validated by the same-named schemastery schema and doubling
+ * as the `llm-siliconflow` settings-section shape. Every field is optional in
+ * yml: a missing API key resolves through {@link Config.apiKeyEnv} at each
+ * request (a request without any key fails with `MISSING_CREDENTIAL`, not at
+ * plugin load).
+ */
+export interface Config {
+    /** Credential reference (environment-variable name) resolved per request; defaults to `SILICONFLOW_API_KEY`. */
+    apiKeyEnv?: string;
+    /** Endpoint base; falls back to $SILICONFLOW_BASE_URL from a trusted environment layer, then the public API. */
+    baseURL?: string;
+    /** Default per-request output cap (default 8,192); a model's own cap and explicit request values win. */
+    maxTokens?: number;
+    /** Positive context capacity used when the selected model has no exact value (default 32,768). */
+    defaultContextWindow?: number;
+    /** Advisory models shown by discovery consumers; defaults to six widely hosted models. */
+    models?: SiliconFlowCatalogModel[];
+    /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
+    streamIdleTimeoutMs?: number;
+    /** Provider-owned model-request retry policy; omission uses normal defaults. */
+    retryPolicy?: RetryPolicyConfig;
+}
+export declare const Config: z<Config>;
+/** Public API default; the internal endpoint comes from $SILICONFLOW_BASE_URL. */
+export declare const PUBLIC_BASE_URL = "https://api.siliconflow.cn/v1";
+/**
+ * One resolution's complete request facts. Connection and credential facts
+ * are one value on purpose: a snapshot the resolver rejects keeps the whole
+ * previous generation, so a request can never pair a stale endpoint with a
+ * newer key.
+ */
+export type ResolvedSiliconFlowOptions = SiliconFlowConnectionOptions;
+/**
+ * The one explicit resolve step from raw config to validated connection
+ * facts. Programmatic construction may bypass Schemastery normalization, so
+ * every default and bound is re-judged here — for the composition entry at
+ * load (fail loud) and for each settings snapshot at its first use.
+ * @param config - raw plugin config or resolved settings snapshot.
+ * @param environment - this run's environment layers, or `undefined` outside
+ * the product CLI. Every layer may supply an endpoint: the product trusts the
+ * project it is launched in, so a checkout can point its own agent at the
+ * gateway that checkout is meant to use.
+ * @returns validated connection facts plus the credential reference.
+ */
+export declare function resolveAdapterOptions(config: Config, environment?: LaunchEnvironmentSnapshot): ResolvedSiliconFlowOptions;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@siliconflow-official/dsh-llm-siliconflow`.
+ * @module @siliconflow-official/dsh-llm-siliconflow/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "llm-siliconflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/serialize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Serialize harness messages into SiliconFlow chat completions. User text is
+ * joined; assistant text becomes `content`, tool calls become `tool_calls`,
+ * and tool results become separate tool messages. Assistant reasoning is
+ * replayed as `reasoning_content` only on tool-call turns, as hosted reasoning
+ * models (DeepSeek-R1 and siblings) require. Core image blocks are rejected
+ * explicitly because this wire route is text-only; unknown declaration-merged
+ * block types retain the adapter's documented extension fallback.
+ * @module dsh-llm-siliconflow/serialize
+ */
+import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm';
+import type { WireMessage, WireRequest } from './types.ts';
+/**
+ * Serialize the conversation. `tool-result` blocks become standalone
+ * `{role: 'tool'}` messages; the harness puts each tool result in its own
+ * user-role message, so a mixed user message contributes its text first and
+ * its tool results as separate wire messages after.
+ * @param messages - the harness conversation, in order.
+ * @returns the wire messages; order preserved, each tool result expanded into its own entry.
+ */
+export declare function serializeMessages(messages: Message[]): WireMessage[];
+/**
+ * Build the full wire request. Always streaming (`stream: true`, usage
+ * reporting on); optional fields are omitted rather than sent as null, so
+ * provider defaults apply.
+ * @param options - the harness request (model, history, system, tools, sampling).
+ * @returns the chat-completions request body.
+ */
+export declare function serializeRequest(options: GenerateOptions): WireRequest;
+//# sourceMappingURL=serialize.d.ts.map

package/lib/types/setup.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Interactive setup wizard core for {@link @siliconflow-official/dsh-llm-siliconflow}:
+ * the pure steps (harness-home and document-path resolution, credential and
+ * settings read/write, model-choice parsing) plus the orchestration over an
+ * injected I/O face, so the thin bin entry stays untested glue and the whole
+ * flow is unit-testable without a terminal.
+ *
+ * The wizard guides a fresh install to a working route: confirm the default
+ * channel, obtain an API key, interrogate the live chat-model listing, pick a
+ * default model, then persist `agent-default-model` into `settings.yaml`.
+ * @module @siliconflow-official/dsh-llm-siliconflow/setup
+ */
+import type { SiliconFlowListingEntry } from './discovery.ts';
+/** Directory name for the default DeepSeek Harness home under the OS home. */
+export declare const DSH_HOME_DIR_NAME = ".dsh";
+/** Environment variable that overrides the default DeepSeek Harness home. */
+export declare const DSH_HOME_ENV = "DSH_HOME";
+/** Settings namespace the wizard writes the default model into. */
+export declare const DEFAULT_MODEL_NAMESPACE = "agent-default-model";
+/** One model row the wizard offers, independent of the discovery source. */
+export interface SetupModel {
+    /** Provider-owned model id, exactly as written to `agent-default-model`. */
+    id: string;
+    /** Optional display name; falls back to the id. */
+    name?: string;
+}
+/** Minimal terminal face the wizard talks through. */
+export interface SetupIo {
+    /** Ask one question and resolve with the trimmed-free answer. */
+    question(prompt: string): Promise<string>;
+    /** Print one line of wizard progress. */
+    log(message: string): void;
+}
+/** Injected dependencies keeping the wizard testable and network-agnostic. */
+export interface SetupDeps {
+    /** Resolved harness home (`settings.yaml` and `.credentials.yaml` live here). */
+    home: string;
+    /** The terminal face. */
+    io: SetupIo;
+    /** Live chat-model listing; the wizard falls back to the static catalog on rejection. */
+    discover: (apiKey: string | undefined) => Promise<readonly SiliconFlowListingEntry[]>;
+}
+/** A persisted default-model selection. */
+export interface DefaultModelSelection {
+    provider: string;
+    model: string;
+}
+/**
+ * Resolve the DeepSeek Harness home: non-empty `$DSH_HOME`, else `~/.dsh`.
+ * @param env - environment mapping; defaults to `process.env`.
+ * @returns the normalized absolute home path.
+ */
+export declare function resolveHome(env?: Record<string, string | undefined>): string;
+/** The managed credential document path under a harness home. */
+export declare function credentialsPath(home: string): string;
+/** The settings document path under a harness home. */
+export declare function settingsPath(home: string): string;
+/**
+ * Read one credential reference from a comment-preserving document.
+ * @param path - the credentials document path.
+ * @param keyEnv - the top-level reference name (e.g. `SILICONFLOW_API_KEY`).
+ * @returns the stored value, or `undefined` when absent or the file is missing.
+ */
+export declare function readCredential(path: string, keyEnv: string): Promise<string | undefined>;
+/**
+ * Set one credential reference, preserving every other entry and comment.
+ * @param path - the credentials document path; created when absent.
+ * @param keyEnv - the top-level reference name to write.
+ * @param key - the value.
+ */
+export declare function writeCredential(path: string, keyEnv: string, key: string): Promise<void>;
+/**
+ * Read the persisted default-model selection, if the section is a complete
+ * `{provider, model}` map.
+ * @param path - the settings document path.
+ * @returns the selection, or `undefined` when absent or incomplete.
+ */
+export declare function readDefaultModel(path: string): Promise<DefaultModelSelection | undefined>;
+/**
+ * Replace the default-model section, preserving every other section and comment.
+ * The replacement carries only `provider` and `model`, so a previous
+ * `reasoningEffort` (unsupported by SiliconFlow) is dropped with the section.
+ * @param path - the settings document path; created when absent.
+ * @param selection - the provider/model pair to persist.
+ */
+export declare function writeDefaultModel(path: string, selection: DefaultModelSelection): Promise<void>;
+/**
+ * Parse a 1-based model-choice answer.
+ * @param raw - the user's answer.
+ * @param count - the number of offered models.
+ * @returns the 0-based index, or `undefined` when the answer is out of range.
+ */
+export declare function parseModelIndex(raw: string, count: number): number | undefined;
+/**
+ * Run the wizard: confirm the default channel, obtain a key, list models,
+ * pick the default, and persist the selection. Never throws for an unroutable
+ * endpoint — discovery falls back to the static catalog — but a malformed
+ * existing document or an unwritable one fails loud.
+ * @param deps - home, terminal face, and discovery function.
+ */
+export declare function runSetup(deps: SetupDeps): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/lib/types/sse.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decode an SSE byte stream into event `data` payloads. Framing — chunk
+ * reassembly, UTF-8/CRLF/BOM handling, comment and non-data field skipping,
+ * multi-`data:` joining — is `eventsource-parser`'s. Comments are reported
+ * only through an optional transport-activity callback. This module keeps the
+ * SiliconFlow (OpenAI-compatible) protocol: the literal `[DONE]` is yielded so
+ * the caller owns final flushing, and EOF before it raises {@link LlmError}.
+ * Framing is spec-strict: an event dispatches only on its blank-line
+ * terminator, so an unterminated tail at EOF is truncation, not a flushable
+ * payload.
+ *
+ * @module dsh-llm-siliconflow/sse
+ */
+/** The terminal payload SiliconFlow (and OpenAI) send after the last chunk. */
+export declare const DONE = "[DONE]";
+/**
+ * Parse an SSE byte stream into data payloads. Yields `[DONE]` as the final
+ * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
+ * without it (truncated response — the model call cannot be trusted).
+ * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onComment - optional transport-activity callback; comments never enter the yielded payload stream.
+ * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
+ */
+export declare function parseSse(stream: ReadableStream<BufferSource>, onComment?: (comment: string) => void): AsyncGenerator<string>;
+//# sourceMappingURL=sse.d.ts.map

package/lib/types/translate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Translate SiliconFlow SSE payloads with one stateful harness block per
+ * content, reasoning, or tool-call index. An empty initial reasoning delta
+ * does not open a block. Finish reason and the latest usage are deferred until
+ * `[DONE]`, covering both finish-attached and trailing usage-only shapes while
+ * ensuring no chunk follows `finish`.
+ *
+ * Translate SiliconFlow wire chunks into the harness `StreamChunk` protocol.
+ * @module dsh-llm-siliconflow/translate
+ */
+import type { FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { WireUsage } from './types.ts';
+/**
+ * Map the wire finish_reason vocabulary to the harness FinishReason.
+ * @param reason - the wire `finish_reason` string.
+ * @returns the mapped reason; unrecognized values (content_filter, …) become `{kind: 'error'}` with the uppercased value as `code`.
+ */
+export declare function mapFinishReason(reason: string): FinishReason;
+/**
+ * Map wire usage fields. SiliconFlow's `prompt_tokens` INCLUDES cache hits
+ * (`prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens`); the
+ * harness TokenUsage convention is DISJOINT counts, so cache reads are
+ * subtracted out of `inputTokens`.
+ * @param usage - wire usage from the finish chunk or the trailing usage-only chunk.
+ * @returns disjoint harness counts; cache/reasoning fields present only when the wire reported them.
+ */
+export declare function mapUsage(usage: WireUsage): TokenUsage;
+/**
+ * Consume SSE data payloads (ending with `[DONE]`) and yield StreamChunks.
+ * Malformed JSON payloads abort the stream with `MALFORMED_RESPONSE`.
+ * @param payloads - SSE data payloads from {@link parseSse}, `[DONE]`-terminated.
+ * @returns deltas as they arrive; `block-end`s, `usage`, and `finish` are all deferred to the `[DONE]` sentinel.
+ *   A `stop` (or absent) finish with no opened blocks is a degenerate provider completion and maps to an
+ *   `EMPTY_RESPONSE` error finish instead of a successful empty message.
+ */
+export declare function translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk>;
+//# sourceMappingURL=translate.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * SiliconFlow chat-completions wire format (OpenAI-compatible). Types only.
+ *
+ * Source of truth: the SiliconFlow API docs at https://docs.siliconflow.cn
+ * (chat completions), cross-checked against live streams. SiliconFlow hosts
+ * reasoning models (DeepSeek-R1, QwQ, Kimi-K2-Thinking, …) whose deltas carry
+ * `reasoning_content` exactly like the upstream DeepSeek-R1 wire shape, so the
+ * assistant history type keeps that passback field for tool-call turns.
+ *
+ * @module dsh-llm-siliconflow/types
+ */
+/** Request body for `POST {baseURL}/chat/completions`. */
+export interface WireRequest {
+    model: string;
+    messages: WireMessage[];
+    stream: true;
+    stream_options: {
+        include_usage: true;
+    };
+    tools?: WireTool[];
+    temperature?: number;
+    max_tokens?: number;
+    /**
+     * Stop sequences (OpenAI `stop`): generation halts as soon as the model
+     * produces any one of these strings. Mapped from `GenerateOptions.stop`.
+     */
+    stop?: string[];
+}
+/** System-role message: a single string of instructions. */
+export interface WireSystemMessage {
+    role: 'system';
+    content: string;
+}
+/** User-role message: a single string of user input. */
+export interface WireUserMessage {
+    role: 'user';
+    content: string;
+}
+/** Tool-role message: the result of one tool call, keyed by its call id. */
+export interface WireToolMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+}
+/** One entry of the request `messages` array, discriminated on `role`. */
+export type WireMessage = WireSystemMessage | WireUserMessage | WireAssistantMessage | WireToolMessage;
+/**
+ * Assistant-role history message. The harness replays `content: ""` (never
+ * null) on tool-call-only turns — some gateways reject null — and sends null
+ * only when the turn carried neither text nor tool calls.
+ */
+export interface WireAssistantMessage {
+    role: 'assistant';
+    content: string | null;
+    /**
+     * CoT passback for hosted reasoning models (DeepSeek-R1 and siblings).
+     * Required on assistant turns that carried tool calls; ignored on
+     * tool-call-free turns (omitted there to save tokens).
+     */
+    reasoning_content?: string;
+    tool_calls?: WireToolCall[];
+}
+/** A completed tool call replayed on an assistant history message; `arguments` is the raw JSON string. */
+export interface WireToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** One entry of the request `tools` array; `parameters` is a JSON Schema object. */
+export interface WireTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** One parsed SSE `data:` payload (a chat.completion.chunk). */
+export interface WireChunk {
+    choices?: WireChoice[];
+    /** Arrives attached to the finish chunk and/or as a trailing usage-only chunk. */
+    usage?: WireUsage | null;
+}
+/** One streamed choice (requests always ask for a single one); `finish_reason` is non-null only on its terminal chunk. */
+export interface WireChoice {
+    delta?: WireDelta;
+    finish_reason?: string | null;
+}
+/** The incremental content of one streamed choice; any subset of fields may be present per chunk. */
+export interface WireDelta {
+    role?: string;
+    /** Visible text. Null/empty on reasoning/tool-call chunks. */
+    content?: string | null;
+    /**
+     * Reasoning-model CoT. The FIRST chunk carries an empty string (must not
+     * open a reasoning block); absent entirely on non-reasoning models.
+     */
+    reasoning_content?: string | null;
+    tool_calls?: WireToolCallDelta[];
+}
+/** A streamed fragment of one tool call; fragments sharing an `index` concatenate into one call. */
+export interface WireToolCallDelta {
+    /** Disambiguates parallel tool calls; stable across a call's deltas. */
+    index: number;
+    /** Present on the first delta of each call only. */
+    id?: string;
+    type?: 'function';
+    function?: {
+        /** Present on the first delta of each call only. */
+        name?: string;
+        /** Argument JSON fragment (concatenate across deltas). */
+        arguments?: string;
+    };
+}
+/**
+ * Wire token accounting. `prompt_tokens` INCLUDES cache hits (it equals
+ * `prompt_cache_hit_tokens + prompt_cache_miss_tokens`); `mapUsage` subtracts
+ * them to keep the harness convention of disjoint counts.
+ * `prompt_tokens_details.cached_tokens` is the OpenAI-compat spelling of the
+ * hit count.
+ */
+export interface WireUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
+/** Non-2xx error body. */
+export interface WireError {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map