@vibedev-si/dsh-vibedev 0.2.1

package/lib/llm/adapter.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The VibeDev gateway behind the Harness LLM seam.
+ *
+ * Shaped after `@deepseek-ai/dsh-llm-pi-ai`'s adapter (src/adapter.ts,
+ * dsh-v0.2.0-rc.2): one immutable snapshot per catalog, captured before an
+ * operation's first await, so a catalog refresh mid-reply only affects the next
+ * step. What differs is what a gateway needs:
+ *
+ * - one route serves every protocol, each model naming its own (see models.ts);
+ * - the credential is the account's access token (or a development key), sent
+ *   as `Authorization: Bearer` on every protocol;
+ * - Anthropic requests carry `metadata.user_id = {device_id, session_id}` and
+ *   OpenAI requests `session_id` and `prompt_cache_key`, which is how the gateway
+ *   keeps one session on one upstream account so its prompt cache keeps hitting;
+ * - "off" is spelled out where the catalog offers `none`, and Responses drops
+ *   `temperature` while reasoning;
+ * - a 401 hands the credential back to its owner and, when the owner renewed it,
+ *   sends the request once more; failures carry this plugin's own codes
+ *   (`VIBEDEV_SIGN_IN_REQUIRED`, `VIBEDEV_INSUFFICIENT_BALANCE`) because the
+ *   Harness's account codes raise the DeepSeek account's prompts.
+ *
+ * Ported from the VibeDev app's `@vibedev/dsh-llm-gateway` (vibedev-app
+ * f08333ee7f), where the same models sit on the app's own account channel.
+ *
+ * @module dsh-vibedev/llm/adapter
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, ImageAttachmentAccess, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, ResolvedRetryPolicy, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { GatewayModel } from './catalog.js';
+/** The credential for one request. */
+export interface GatewayCredential {
+    readonly token: string;
+    /**
+     * `account`: the host app's VibeDev account (the VibeDev app); `plugin`: this
+     * plugin's own sign-in; `key`: a development key. Account and plugin tokens
+     * go back to their owner on a 401; a development key does not.
+     */
+    readonly kind: 'account' | 'plugin' | 'key';
+}
+/**
+ * Failure code for "no VibeDev sign-in": deliberately not the Harness's
+ * `ACCOUNT_SIGN_IN_REQUIRED`, which belongs to the DeepSeek account and would
+ * raise its sign-in prompt; the chat shows this failure's own message.
+ */
+export declare const SIGN_IN_REQUIRED_CODE = "VIBEDEV_SIGN_IN_REQUIRED";
+/** Failure code for a used-up balance; not the Harness's `ACCOUNT_QUOTA`, which opens the DeepSeek top-up. */
+export declare const INSUFFICIENT_BALANCE_CODE = "VIBEDEV_INSUFFICIENT_BALANCE";
+/** What a person reads when a VibeDev model is used before signing in. */
+export declare const SIGN_IN_MESSAGE: string;
+/** What a person reads when the gateway ended the sign-in and a refresh could not renew it. */
+export declare const SESSION_ENDED_MESSAGE: string;
+/**
+ * What a person reads on a used-up balance.
+ * @param origin - the gateway origin, whose `/purchase` page tops up.
+ * @returns the message.
+ */
+export declare function balanceMessage(origin: string): string;
+/** Constructor options for {@link GatewayAdapter}. */
+export interface GatewayAdapterOptions {
+    /** The route key the adapter registers under. */
+    readonly provider: string;
+    /** The name selectors show for the route. */
+    readonly displayName: string;
+    /** The gateway origin, read per snapshot. */
+    readonly origin: () => string;
+    /** The current catalog; a new array identity means a new catalog. */
+    readonly catalog: () => readonly GatewayModel[];
+    /**
+     * Read the catalog again because it is empty when models are listed, so a catalog read that missed a
+     * fresh sign-in, or failed on a flaky network, recovers on the next list instead of the next timer.
+     */
+    readonly refreshCatalog?: () => Promise<void>;
+    /** The credential for one request, or undefined when nobody is signed in and no key is configured. */
+    readonly resolveCredential: () => Promise<GatewayCredential | undefined>;
+    /** Hand a credential the gateway rejected back to its owner, which refreshes it or signs out. */
+    readonly rejectCredential?: (credential: GatewayCredential) => Promise<void>;
+    /** A stable device id for Anthropic session affinity. */
+    readonly deviceId?: () => Promise<string | undefined>;
+    readonly retryPolicy?: () => ResolvedRetryPolicy | undefined;
+    readonly streamIdleTimeoutMs?: number;
+    readonly cacheRetention?: 'none' | 'short' | 'long';
+    readonly resolveAttachments?: () => AttachmentStore | undefined;
+    readonly resolveImageAccess?: (attachments: AttachmentStore, ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
+    readonly onReplayDegrade?: (detail: {
+        provider: string;
+        model: string;
+        reason: string;
+    }) => void;
+}
+/**
+ * The gateway as an LLM adapter. Each operation reads the current catalog, so a refresh reaches
+ * the next request without a restart, while a request in flight finishes on the catalog it began with.
+ */
+export declare class GatewayAdapter extends LlmAdapter {
+    private readonly config;
+    private snapshot;
+    constructor(config: GatewayAdapterOptions);
+    private current;
+    private assertOwned;
+    private modelOf;
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): ResolvedRetryPolicy | undefined;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    private modelInfo;
+    prepareCall(provider: string, model: string, _signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private streamWithSnapshot;
+    /**
+     * Fit pi-ai's payload to the gateway: Chat Completions gets the session's cache key (pi-ai sends it
+     * only to api.openai.com), "off" is spelled out where the catalog offers `none`, and Responses
+     * drops `temperature` while reasoning, which reasoning models refuse.
+     */
+    private shapePayload;
+    /**
+     * Hand a refused credential back to its owner (which refreshes it, or signs out when the gateway
+     * ended the session) and return the credential that replaced it, if one did.
+     * @param credential - the credential the gateway answered 401 to.
+     * @returns a credential with a different token, or undefined when there is none to try.
+     */
+    private renew;
+    /**
+     * Turn a failed finish into the VibeDev failure the gateway status names: 402 is the balance
+     * (with the top-up page), 401 a sign-in that has ended. Both carry this plugin's own codes and
+     * messages, so the chat shows them instead of the DeepSeek account's prompts.
+     */
+    private accountFailure;
+}

package/lib/llm/catalog.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The VibeDev gateway's model catalog (`GET /v1/models`), narrowed to the chat
+ * models this channel can serve and annotated with the wire protocol each one
+ * is called over.
+ *
+ * The gateway answers with its VibeDev projection for signed, signature-exempt,
+ * and app-token requests: every entry carries `protocol`, `capabilities` (context,
+ * output, thinking, `reasoning_levels`, `default_reasoning`, modalities,
+ * `allowed_endpoints`), and prices. Media generators, transcription models, and
+ * the models the client drives itself (`internal_role`) are not chat models and
+ * never reach the picker.
+ *
+ * @module dsh-vibedev/llm/catalog
+ */
+/** The wire protocols the gateway serves chat models over, named as pi-ai names them. */
+export type GatewayApi = 'anthropic-messages' | 'openai-responses' | 'openai-completions';
+/** A reasoning level as the gateway catalog spells it. */
+export type GatewayReasoningLevel = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** One chat model of the catalog with everything the adapter needs to describe and call it. */
+export interface GatewayModel {
+    readonly id: string;
+    readonly name: string;
+    /** The protocol requests for this model use. */
+    readonly api: GatewayApi;
+    readonly contextWindow: number;
+    readonly maxTokens: number;
+    readonly input: readonly ('text' | 'image')[];
+    /**
+     * Levels the user may pick, in escalation order; `undefined` when the catalog
+     * states none (no level control), `[]` when the model thinks with no levels.
+     */
+    readonly reasoningLevels?: readonly GatewayReasoningLevel[];
+    /** The level a new session starts on, when the catalog names one it offers. */
+    readonly defaultReasoning?: GatewayReasoningLevel;
+    /** Claude's effort-driven thinking, as opposed to a token budget. */
+    readonly adaptiveThinking: boolean;
+    /** Catalog prices per million tokens, in the catalog's currency (yuan). */
+    readonly cost: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+    };
+}
+/**
+ * The protocol a model family is called over best, before the catalog's endpoint list has a say:
+ * Claude speaks Messages natively; GPT, the o-series, Codex, and Grok keep their reasoning state
+ * on Responses; everything else (DeepSeek, GLM, Kimi, Doubao, ...) passes through Chat Completions.
+ * @param id - the catalog model id.
+ * @returns the preferred protocol.
+ */
+export declare function preferredApi(id: string): GatewayApi;
+/**
+ * The protocol to call one catalog entry over: the family's preferred protocol when the
+ * entry allows it, otherwise the first protocol it does allow. An entry listing no endpoint
+ * this channel speaks (a native-only Gemini, say) has none.
+ * @param id - the catalog model id.
+ * @param allowed - the entry's `allowed_endpoints`, when it lists them.
+ * @param protocol - the entry's `protocol`, used when it lists no endpoints.
+ * @returns the protocol, or undefined when this channel cannot call the model.
+ */
+export declare function chooseApi(id: string, allowed: readonly string[] | undefined, protocol: string | undefined): GatewayApi | undefined;
+/**
+ * Parse one `/v1/models` body into the chat models this channel serves.
+ * @param body - the decoded response: `{object, data: [...]}` or a bare array.
+ * @returns the chat models, in catalog order; entries that are not chat models or cannot be called are left out.
+ */
+export declare function parseCatalog(body: unknown): GatewayModel[];
+/**
+ * The level a new session starts on: the catalog's default, else `high`, else the highest level
+ * not above `high`, else the lowest level offered.
+ * @param model - the catalog model.
+ * @returns the starting level, or undefined when the model offers no levels.
+ */
+export declare function startingReasoning(model: GatewayModel): GatewayReasoningLevel | undefined;

package/lib/llm/context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Copied (by way of the VibeDev app) from DeepSeek Harness `@deepseek-ai/dsh-llm-pi-ai` (src/context.ts,
+ * dsh-v0.2.0-rc.2; MIT, Copyright (c) 2026 DeepSeek — see THIRD-PARTY-NOTICES.txt), only the
+ * image-limit import moved to ./limits.ts,
+ * so the gateway adapter can choose a wire protocol per model. Keep it in step with upstream.
+ *
+ * Harness request-history conversion into pi-ai's Context vocabulary.
+ *
+ * @module dsh-llm-pi-ai/context
+ */
+import type { GenerateOptions, ImageAttachmentAccessResolver } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { Context as PiContext } from '@earendil-works/pi-ai';
+/** Inputs that bind deterministic request images to one current tool execution world. */
+export interface PiImageRequestContext {
+    /** Durable provider that resolves request-image bytes and provider-owned host objects. */
+    attachments: AttachmentStore;
+    /** Resolve current tool access separately from deterministic request-image versions. */
+    resolveImageAccess: ImageAttachmentAccessResolver;
+    /** Request-level bound on the base64-encoded payload of retained images; omission leaves the bound unchecked. */
+    maxRequestImageBytes?: number;
+    /** Route pixel and raw encoded-byte budgets. */
+    requestImagePolicy?: PiImageRequestBudget;
+}
+/** Per-route budgets from which each request image's target is derived. */
+export interface PiImageRequestBudget {
+    /** Total-pixel budget; larger sources are downscaled proportionally. */
+    maxPixels: number;
+    /** Encoded-byte target for one request image. */
+    maxBytes: number;
+}
+/**
+ * Convert text-only harness history to a synchronous pi-ai Context. Tool
+ * result names are recovered from preceding assistant tool calls.
+ * @param options - the harness request; `options.system`, else a leading `system` message, maps to pi-ai's single `systemPrompt` slot.
+ * @param images - absent; selects the synchronous conversion.
+ * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @returns the pi-ai context; `tools` is omitted when the request declares none.
+ * @throws {LlmError} `UNSUPPORTED_CONTENT` for images in any history role, including a leading system message.
+ */
+export declare function toPiContext(options: GenerateOptions, images?: undefined, onReplayDegrade?: (reason: string) => void): PiContext;
+/**
+ * Convert harness history to a pi-ai Context while resolving durable images.
+ * Tool result names are recovered from preceding assistant tool calls. Image
+ * occurrences the surface marks offloaded become text placeholders; when the
+ * retained occurrences' exact base64 payload still exceeds
+ * `maxRequestImageBytes`, the call fails with `IMAGE_OFFLOAD_REQUIRED` naming
+ * how many more oldest occurrences must be offloaded.
+ * @param options - the harness request; `options.system`, else a leading `system` message, maps to pi-ai's single `systemPrompt` slot.
+ * @param images - attachment provider, current path resolver, and request limits.
+ * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @returns the asynchronously resolved pi-ai context.
+ */
+export declare function toPiContext(options: GenerateOptions, images: PiImageRequestContext, onReplayDegrade?: (reason: string) => void): Promise<PiContext>;

package/lib/llm/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The VibeDev gateway's chat models on their own route, `vibedev-gateway`, so
+ * they sit in the model pickers next to whatever else the Harness offers — the
+ * DeepSeek account's models included — and are paid from the VibeDev balance.
+ *
+ * The catalog comes from the gateway (`GET /v1/models`) with the credential
+ * requests use, so nothing is listed before a sign-in: the catalog is per
+ * account. It is read at start, on every sign-in, sign-out or account change,
+ * and every `catalogRefreshMinutes`; a changed catalog republishes the route
+ * so pickers update without a restart.
+ *
+ * Inside the VibeDev app the host account already serves these models on the
+ * app's own account channel; when the credential comes from the host account
+ * the route stays empty, so the pickers do not list every model twice.
+ *
+ * @module dsh-vibedev/llm
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { GatewayCredential } from './adapter.js';
+import type { GatewayModel } from './catalog.js';
+export { GatewayAdapter, INSUFFICIENT_BALANCE_CODE, SIGN_IN_REQUIRED_CODE } from './adapter.js';
+export type { GatewayAdapterOptions, GatewayCredential } from './adapter.js';
+export { parseCatalog } from './catalog.js';
+export type { GatewayModel } from './catalog.js';
+/** The route the gateway's chat models are listed under. */
+export declare const VIBEDEV_ROUTE = "vibedev-gateway";
+/** What the route needs from the rest of the plugin. */
+export interface GatewayModelsOptions {
+    /** Gateway origin, without a trailing slash. */
+    readonly origin: string;
+    /** The name pickers and the Models page show for the route. */
+    readonly displayName: string;
+    /** The credential for the next request, from the plugin's credential chain. */
+    readonly resolveCredential: () => Promise<GatewayCredential | undefined>;
+    /** Hand a credential the gateway refused back to its owner. */
+    readonly rejectCredential: (credential: GatewayCredential) => Promise<void>;
+    /** A stable id for this installation (Anthropic session affinity). */
+    readonly deviceId: () => Promise<string>;
+    /** Model ids listed first, in this order, when the catalog offers them. Read at every catalog read. */
+    readonly preferredModels: () => readonly string[];
+    /** Subscribe to sign-in changes; returns unsubscribe. */
+    readonly onCredentialChange: (listener: () => void) => () => void;
+    readonly catalogRefreshMinutes?: number;
+    readonly catalogTimeoutMs?: number;
+    readonly cacheRetention?: 'none' | 'short' | 'long';
+}
+/** The route's live state, for status lines and tests. */
+export interface GatewayModels {
+    /** Chat models listed now. */
+    models(): readonly GatewayModel[];
+    /** Why the route is empty, when it is. */
+    hidden(): 'signed-out' | 'host-account' | undefined;
+    /** Read the catalog now (after a sign-in, say); resolves when the read ends. */
+    refresh(): Promise<void>;
+}
+/**
+ * The catalog with the preferred models first, in their configured order, and the rest in catalog order.
+ * @param models - the parsed catalog.
+ * @param preferred - model ids to list first.
+ * @returns the reordered catalog.
+ */
+export declare function preferredFirst(models: readonly GatewayModel[], preferred: readonly string[]): GatewayModel[];
+/**
+ * Register the route and keep its catalog current.
+ * @param ctx - a context with the `llm` service.
+ * @param options - origin, credentials and catalog policy.
+ * @returns the route's live state.
+ */
+export declare function installGatewayModels(ctx: Context, options: GatewayModelsOptions): GatewayModels;

package/lib/llm/limits.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Request limits the gateway adapter and its copied conversion modules read.
+ * The values are `@deepseek-ai/dsh-llm-pi-ai`'s defaults, so a request through
+ * the gateway is sized exactly as one through the pi-ai channel.
+ *
+ * @module dsh-vibedev/llm/limits
+ */
+/** Maximum base64-encoded image payload per request before the oldest images become placeholders. */
+export declare const DEFAULT_MAX_REQUEST_IMAGE_BYTES: number;
+/** Total-pixel budget that preserves the complete 2048px normalized attachment. */
+export declare const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET: number;
+/** Raw encoded-byte target before inline base64 expansion. */
+export declare const DEFAULT_REQUEST_IMAGE_MAX_BYTES: number;
+/** Maximum provider idle time while one stream read is outstanding. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Context capacity for a catalog model that does not state one. */
+export declare const DEFAULT_CONTEXT_WINDOW = 200000;
+/** Output capability for a catalog model that does not state one. */
+export declare const DEFAULT_MAX_TOKENS = 32768;

package/lib/llm/models.d.ts

@@ -0,0 +1,67 @@
+/**
+ * pi-ai model descriptors and the multi-protocol provider for the gateway.
+ *
+ * A configured pi-ai route speaks one protocol, but one gateway serves Claude
+ * over Messages, GPT and Grok over Responses, and DeepSeek and the rest over Chat
+ * Completions. Every pi-ai `Model` carries its own `api`, so this provider
+ * dispatches each request to the protocol module its model names, and the whole
+ * catalog lives on one channel.
+ *
+ * @module dsh-vibedev/llm/models
+ */
+import type { Api, CreateModelsOptions, Model, ModelThinkingLevel, MutableModels, Provider, ThinkingLevelMap } from '@earendil-works/pi-ai';
+import type { GatewayApi, GatewayModel, GatewayReasoningLevel } from './catalog.js';
+/** Every pi-ai thinking level, in pi-ai's escalation order. */
+export declare const THINKING_LEVELS: readonly ModelThinkingLevel[];
+/**
+ * pi-ai's level map for the catalog's levels. pi-ai offers `low`/`medium`/`high`
+ * (and `minimal`) unless mapped to null, and `xhigh`/`max` only when mapped, so
+ * every level the catalog leaves out is closed explicitly. `off` stays open only
+ * when the catalog offers `none`; a model that always thinks never shows "off".
+ * @param levels - the catalog's levels for one model.
+ * @returns the map pi-ai reads to list and spell levels.
+ */
+export declare function thinkingLevelMap(levels: readonly GatewayReasoningLevel[]): ThinkingLevelMap;
+/**
+ * The endpoint root the protocol's SDK appends its path to: the Anthropic SDK adds
+ * `/v1/messages` itself, the OpenAI SDK expects the `/v1` root.
+ * @param origin - the gateway origin.
+ * @param api - the model's protocol.
+ * @returns the base URL for that protocol.
+ */
+export declare function baseUrlFor(origin: string, api: GatewayApi): string;
+/**
+ * Build pi-ai's descriptor for one catalog model on the given provider route.
+ * @param model - the catalog model.
+ * @param provider - the route the model is registered under.
+ * @param origin - the gateway origin.
+ * @returns the pi-ai model.
+ */
+export declare function toPiModel(model: GatewayModel, provider: string, origin: string): Model<Api>;
+/**
+ * The provider for one catalog snapshot: each request goes to the protocol module its model names.
+ * @param input - route id, display name, and the snapshot's models.
+ * @param input.id - the provider route key.
+ * @param input.name - the display name.
+ * @param input.models - pi-ai descriptors for the snapshot's models.
+ * @returns the pi-ai provider.
+ */
+export declare function gatewayProvider(input: {
+    id: string;
+    name: string;
+    models: readonly Model<Api>[];
+}): Provider;
+/**
+ * Create an empty pi-ai collection. pi-ai's main entry builds one with no
+ * providers; its `providers/all` entry would pull every provider's SDK (AWS,
+ * Google, Mistral…) into this plugin's bundle for nothing.
+ * @param options - credential storage and ambient authentication integrations.
+ * @returns a mutable collection with no registered providers.
+ */
+export declare function createModels(options?: CreateModelsOptions): MutableModels;
+/**
+ * Selectable levels from pi-ai's view of one model, in escalation order.
+ * @param model - descriptor carrying reasoning support and wire mappings.
+ * @returns the supported levels.
+ */
+export declare function getSupportedThinkingLevels(model: Model<Api>): ModelThinkingLevel[];

package/lib/llm/replay.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copied unchanged (by way of the VibeDev app) from DeepSeek Harness `@deepseek-ai/dsh-llm-pi-ai` (src/replay.ts,
+ * dsh-v0.2.0-rc.2; MIT, Copyright (c) 2026 DeepSeek — see THIRD-PARTY-NOTICES.txt)
+ * so the gateway adapter can choose a wire protocol per model. Keep it in step with upstream.
+ *
+ * Durable pi-ai replay metadata and assistant-history reconstruction.
+ *
+ * Harness content remains the durable source for text and tool calls. This
+ * module stores only the provider-native metadata needed to reconstruct a
+ * pi-ai assistant message on a later request.
+ *
+ * @module dsh-llm-pi-ai/replay
+ */
+import type { AssistantMessage as HarnessAssistantMessage, ReplayEnvelope } from '@deepseek-ai/dsh-llm';
+import type { Api, AssistantMessage } from '@earendil-works/pi-ai';
+/** Per-block half of the pi-ai replay envelope, one entry per content block. */
+export type PiAiReplayBlock = {
+    type: 'text';
+    textSignature?: string;
+} | {
+    type: 'reasoning';
+    thinkingSignature?: string;
+    redacted?: boolean;
+} | {
+    type: 'tool-call';
+    thoughtSignature?: string;
+};
+/** Versioned response-level half of the pi-ai replay envelope. */
+export interface PiAiReplayResponse {
+    kind: 'pi-ai';
+    version: 2;
+    api: Api;
+    provider: string;
+    /** Requested model identity, matching the durable assistant source. */
+    model: string;
+    /** Provider-reported model; replay retains the requested model for signature matching. */
+    responseModel?: string;
+    responseId?: string;
+    /** Provider-native effort for historical replay; absence is preserved. */
+    providerThinkingLevel?: string;
+    stopReason: AssistantMessage['stopReason'];
+}
+/**
+ * Project a successful pi-ai response into the minimal durable replay state.
+ * The per-block half is index-aligned with the streamed blocks (pi-ai content
+ * order), so `BlockAssembler` prunes an entry with its block whenever assembly
+ * removes one.
+ * @param message - completed native pi-ai assistant response.
+ * @param requestedModel - request identity stored in the assistant source; defaults to the native model.
+ * @returns the versioned lossless-JSON replay projection.
+ */
+export declare function toPiReplayState(message: AssistantMessage, requestedModel?: string): ReplayEnvelope;
+/**
+ * Convert one durable Harness assistant message into pi-ai history.
+ *
+ * Durable content is the authoritative record; replay metadata only restores
+ * native fidelity (ids, signatures). A replay state this build cannot use —
+ * another adapter's kind, another version, a malformed value, or metadata that
+ * no longer matches the content — therefore degrades the one message to
+ * provider-neutral history instead of failing the request.
+ * @param message - model-produced assistant content with provider, model, and optional adapter-owned replay metadata.
+ * @param onDegrade - called with the diagnostic reason when an unusable replay
+ *   state falls back to provider-neutral conversion.
+ * @returns a native pi-ai assistant message reconstructed from durable content.
+ */
+export declare function toPiAssistant(message: HarnessAssistantMessage, onDegrade?: (reason: string) => void): AssistantMessage;

package/lib/llm/stream.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copied unchanged (by way of the VibeDev app) from DeepSeek Harness `@deepseek-ai/dsh-llm-pi-ai` (src/stream.ts,
+ * dsh-v0.2.0-rc.2; MIT, Copyright (c) 2026 DeepSeek — see THIRD-PARTY-NOTICES.txt)
+ * so the gateway adapter can choose a wire protocol per model. Keep it in step with upstream.
+ *
+ * pi-ai assistant event translation into the Harness streaming protocol.
+ *
+ * pi-ai tool-call arguments are parsed objects while the Harness keeps their
+ * raw JSON representation. pi-ai also reports failures as terminal stream
+ * events, which this module maps into Harness finish chunks.
+ *
+ * @module dsh-llm-pi-ai/stream
+ */
+import type { FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { AssistantMessage, AssistantMessageEvent, Usage as PiUsage } from '@earendil-works/pi-ai';
+/**
+ * Map pi-ai usage (reasoning folded into output by pi-ai).
+ * @param usage - cumulative usage from the terminal pi-ai event.
+ * @returns harness counts with pi-ai's exact total; cache fields appear only
+ *   when non-zero (pi-ai reports zeros, not absence).
+ */
+export declare function mapUsage(usage: PiUsage): TokenUsage;
+/**
+ * Map a terminal pi-ai event to the harness finish reason.
+ * @param message - the assistant message carried by the `done` or `error` event.
+ * @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+ * @returns the mapped harness reason. Recognized error text, `stop` usage above
+ *   `contextWindow`, and zero-output `length` usage that fills the window map
+ *   to `CONTEXT_WINDOW_EXCEEDED`; a `stop` with no content blocks maps to an
+ *   `EMPTY_RESPONSE` error, while terminal `pending` and `deferred` states map
+ *   to non-retryable `PI_AI_ERROR` failures.
+ */
+export declare function mapStopReason(message: AssistantMessage, contextWindow?: number): FinishReason;
+/**
+ * Translate the pi-ai event stream into StreamChunks. pi-ai never throws
+ * mid-stream — failures arrive as `error` events, which become error/aborted
+ * `finish` chunks (the harness protocol's other error-delivery style).
+ * @param events - one assistant turn's pi-ai event stream.
+ * @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+ * @param callerSignal - caller cancellation state; an aborted caller makes any
+ *   in-band terminal error an aborted finish.
+ * @param requestedModel - request model identity recorded for durable replay.
+ * @returns the harness chunks, ending with `usage` then `finish`; throws
+ *   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
+ */
+export declare function toStreamChunks(events: AsyncIterable<AssistantMessageEvent>, contextWindow?: number, callerSignal?: AbortSignal, requestedModel?: string): AsyncGenerator<StreamChunk>;

package/lib/media/chat.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Media the user attached in the conversation, addressed as `chat:N` (the Nth
+ * most recent attachment of the kind the input needs) or `chat:<kind>:N`
+ * (`chat:image:1`, `chat:video:2`, `chat:audio:1`). The model sees attached
+ * images but no path to them; this is how it can pass one on as a reference.
+ * @module dsh-vibedev/media/chat
+ */
+import type { AttachmentStore, FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { Message } from '@deepseek-ai/dsh-llm';
+import type { LoadedMedia } from './sources.js';
+/** The media kinds a chat reference can name. */
+export type ChatMediaKind = 'image' | 'video' | 'audio';
+/** A parsed `chat:` reference. */
+export interface ChatReference {
+    /** The kind named in the reference, or undefined for `chat:N`. */
+    readonly kind?: ChatMediaKind;
+    /** 1 for the most recent. */
+    readonly index: number;
+}
+/**
+ * Parse a `chat:` reference.
+ * @param source - what the model passed.
+ * @returns the reference, or undefined when the source is not one.
+ */
+export declare function parseChatReference(source: string): ChatReference | undefined;
+interface ChatItem {
+    readonly kind: ChatMediaKind | 'other';
+    readonly name: string;
+    readonly image?: ImageAttachmentRef;
+    readonly file?: FileAttachmentRef;
+}
+/**
+ * The user's attachments, most recent first.
+ * @param messages - the conversation, oldest first.
+ * @returns images and files from user messages.
+ */
+export declare function chatAttachments(messages: readonly Message[]): ChatItem[];
+/**
+ * Load one `chat:` reference.
+ * @param reference - the parsed reference.
+ * @param want - the kind the input needs; `chat:N` counts only attachments of this kind.
+ * @param messages - the conversation, oldest first.
+ * @param store - the attachment store.
+ * @param maxBytes - the largest accepted file.
+ * @param signal - cancels the read.
+ * @returns the loaded media.
+ */
+export declare function loadChatReference(reference: ChatReference, want: ChatMediaKind, messages: readonly Message[], store: AttachmentStore, maxBytes: number, signal?: AbortSignal): Promise<LoadedMedia>;
+export {};

package/lib/media/sources.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Loading media inputs: a workspace path, an absolute path, an HTTP(S) link or a
+ * `data:` URL. The type is read from the file's own header first, so a file
+ * named `.png` that is really a JPEG is treated as a JPEG.
+ * @module dsh-vibedev/media/sources
+ */
+/** One loaded input. */
+export interface LoadedMedia {
+    /** What the caller passed. */
+    readonly source: string;
+    /** A file name for uploads. */
+    readonly name: string;
+    readonly mime: string;
+    readonly data: Uint8Array;
+}
+/** How paths are read; the tool layer backs it with the host's filesystem service. */
+export interface SourceReader {
+    readPath(path: string, maxBytes: number, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+        name: string;
+    }>;
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * The file extension for a MIME type.
+ * @param mime - the type.
+ * @param fallback - extension when the type is unknown.
+ * @returns the extension, without a dot.
+ */
+export declare function extensionFor(mime: string, fallback?: string): string;
+/**
+ * The MIME type a file's leading bytes identify, falling back to its name.
+ * @param data - the file bytes (the first 64 suffice).
+ * @param name - the file name or path, for the extension fallback.
+ * @returns the type, or `application/octet-stream` when unknown.
+ */
+export declare function sniffMime(data: Uint8Array, name?: string): string;
+/**
+ * Load one input.
+ * @param source - path, URL or data URL.
+ * @param reader - how paths are read, and the fetch to use for links.
+ * @param maxBytes - the largest accepted size.
+ * @param signal - cancels the load.
+ * @returns the bytes, a name and the sniffed type.
+ */
+export declare function loadMedia(source: string, reader: SourceReader, maxBytes: number, signal?: AbortSignal): Promise<LoadedMedia>;