@maci0/dsh-google-vertex 0.0.0-stage → 0.12.4

package/lib/gemini.js

@@ -0,0 +1,561 @@
+/**
+ * Wire translation for Google's own Gemini models on Vertex AI: the request
+ * body `publishers/google` accepts, the SSE response shape, and (the part that
+ * makes tool calling work at all on Gemini 3) the thought signature that has to
+ * travel back with every replayed function call.
+ *
+ * Everything here is pure: the adapter feeds it bytes and yields the chunks it
+ * returns, so the protocol is testable without a harness or a network.
+ *
+ * @module dsh-google-vertex/gemini
+ */
+import { systemParts, takeCounters, toolInput } from './wire-shared.js';
+import { EMPTY_RESPONSE_CODE, endpointOrigin, failureForEvent, resultText } from './wire.js';
+/** Harness code reported when the provider refused on safety grounds. */
+export const SAFETY_BLOCKED_CODE = 'SAFETY';
+/** Vertex path version this adapter speaks. */
+const API_VERSION = 'v1';
+/**
+ * Gemini context capacity: every current Gemini model serves roughly a million
+ * tokens, and the catalog below narrows nothing.
+ */
+export const DEFAULT_GEMINI_CONTEXT_WINDOW = 1_048_576;
+/**
+ * Output cap applied when a caller omits one.
+ *
+ * Vertex's ceiling here is EXCLUSIVE: `maxOutputTokens: 65536` is refused with
+ * "supported range is from 1 (inclusive) to 65536 (exclusive)", so the highest
+ * accepted value is one less.
+ */
+export const DEFAULT_GEMINI_MAX_TOKENS = 65_535;
+/**
+ * Gemini models the global endpoint serves, in picker order. Ids are the
+ * provider's own aliases, so a promoted release needs no edit here.
+ */
+export const DEFAULT_GEMINI_MODELS = [
+    { id: 'gemini-3.5-flash', name: 'Gemini 3.5 Flash (Vertex)' },
+    { id: 'gemini-3.1-pro-preview', name: 'Gemini 3.1 Pro Preview (Vertex)' },
+    { id: 'gemini-3-flash-preview', name: 'Gemini 3 Flash Preview (Vertex)' },
+    { id: 'gemini-2.5-pro', name: 'Gemini 2.5 Pro (Vertex)' },
+    { id: 'gemini-2.5-flash', name: 'Gemini 2.5 Flash (Vertex)' },
+    { id: 'gemini-2.5-flash-lite', name: 'Gemini 2.5 Flash-Lite (Vertex)' },
+];
+/**
+ * The streaming publisher path for one Gemini model.
+ * @param project - Google Cloud project id.
+ * @param location - region, or `global`.
+ * @param model - publisher model id, e.g. `gemini-3.5-flash`.
+ * @returns the absolute request URL, with the SSE response encoding.
+ */
+export function geminiEndpointFor(project, location, model) {
+    const origin = endpointOrigin(location);
+    const path = `/${API_VERSION}/projects/${encodeURIComponent(project)}/locations/${encodeURIComponent(location)}`
+        + `/publishers/google/models/${encodeURIComponent(model)}:streamGenerateContent?alt=sse`;
+    return `${origin}${path}`;
+}
+/**
+ * Build the replay envelope for one finished response.
+ * @param model - the model that produced the response.
+ * @param blocks - per-block metadata in emitted order.
+ * @returns the envelope for the terminal finish chunk.
+ */
+export function geminiReplayState(model, blocks) {
+    return { response: { kind: 'google-vertex-gemini', version: 1, model }, blocks };
+}
+/** A JSON object, or undefined for anything else. */
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * Convert one harness parameter schema (or nested schema) into one Vertex's
+ * `Schema` message can carry.
+ *
+ * Vertex accepts only `anyOf`, `default`, `description`, `enum`, `example`,
+ * `format`, `items`, the min/max bounds, `nullable`, `pattern`, `properties`,
+ * `propertyOrdering`, `required`, `title`, and `type`. Two members the harness's
+ * value-schema subset emits are not among them, and the endpoint refuses the
+ * whole request when one arrives: `Invalid JSON payload received. Unknown name
+ * "additionalProperties" at 'tools[0].function_declarations[0].parameters'`:
+ *
+ * - `additionalProperties` (the harness requires it on every object) is dropped.
+ * - `oneOf` has no `Schema` member; `anyOf` does. The backend also has no null
+ *   type, so a `null` branch becomes `nullable: true` and the remaining branch
+ *   is inlined (one branch left) or kept as `anyOf` (several). That is the same
+ *   rewrite the official `@google/genai` converter applies to `anyOf`, and it
+ *   only loosens the provider-side hint, since the harness validates the model's
+ *   arguments against the original schema itself.
+ *
+ * Every other member is copied verbatim.
+ * @param schema - one parameter schema, or one nested schema.
+ * @returns the schema Vertex accepts; the input is not mutated.
+ */
+function geminiSchema(schema) {
+    const copy = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === 'additionalProperties')
+            continue;
+        if (key === 'properties') {
+            const properties = asObject(value);
+            if (properties !== undefined) {
+                const rebuilt = {};
+                for (const [name, property] of Object.entries(properties)) {
+                    const nested = asObject(property);
+                    rebuilt[name] = nested === undefined ? property : geminiSchema(nested);
+                }
+                copy[key] = rebuilt;
+                continue;
+            }
+        }
+        if (key === 'items' || key === 'anyOf') {
+            copy[key] = geminiSchemaValue(value);
+            continue;
+        }
+        copy[key] = value;
+    }
+    const union = copy['oneOf'];
+    if (!Array.isArray(union))
+        return copy;
+    delete copy['oneOf'];
+    const branches = [];
+    for (const branch of union) {
+        const node = asObject(branch);
+        if (node === undefined) {
+            branches.push(branch);
+            continue;
+        }
+        if (node['type'] === 'null') {
+            copy['nullable'] = true;
+            continue;
+        }
+        branches.push(geminiSchema(node));
+    }
+    if (branches.length === 1) {
+        const only = asObject(branches[0]);
+        // One branch left: the node itself, its annotations kept, plus the branch.
+        if (only !== undefined) {
+            for (const [key, value] of Object.entries(only))
+                copy[key] ??= value;
+            return copy;
+        }
+    }
+    if (branches.length > 0)
+        copy['anyOf'] = branches;
+    return copy;
+}
+/** Convert one schema-valued member: a single schema, or a list of them. */
+function geminiSchemaValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => {
+            const nested = asObject(entry);
+            return nested === undefined ? entry : geminiSchema(nested);
+        });
+    }
+    const nested = asObject(value);
+    return nested === undefined ? value : geminiSchema(nested);
+}
+/**
+ * Read back the replay metadata for one assistant message.
+ *
+ * Anything unexpected (a foreign envelope, another model, a block count that no
+ * longer lines up with the content) yields undefined, which degrades to sending
+ * the call without its signature rather than throwing: the provider then decides,
+ * and a cross-provider history stays replayable.
+ * @param message - the assistant message from history.
+ * @param model - the model about to be called; signatures do not cross models.
+ * @returns index-aligned metadata, or undefined when unusable.
+ */
+export function readGeminiReplay(message, model) {
+    const source = message.source;
+    if (source?.kind !== 'model' || source.replayState === undefined)
+        return undefined;
+    const envelope = asObject(source.replayState);
+    const response = asObject(envelope?.['response']);
+    if (response?.['kind'] !== 'google-vertex-gemini' || response['version'] !== 1)
+        return undefined;
+    if (response['model'] !== model)
+        return undefined;
+    const raw = envelope?.['blocks'];
+    if (!Array.isArray(raw) || raw.length !== message.content.length)
+        return undefined;
+    const blocks = [];
+    for (const [index, value] of raw.entries()) {
+        const block = asObject(value);
+        const type = block?.['type'];
+        if (type !== message.content[index]?.type)
+            return undefined;
+        if (type !== 'text' && type !== 'tool-call')
+            return undefined;
+        const signature = block?.['thoughtSignature'];
+        if (signature !== undefined && typeof signature !== 'string')
+            return undefined;
+        blocks.push({ type, ...signature === undefined ? {} : { thoughtSignature: signature } });
+    }
+    return blocks;
+}
+/** Every tool-call id in this request, mapped to the tool's name. */
+function toolNames(messages) {
+    const names = new Map();
+    for (const message of messages) {
+        for (const block of message.content) {
+            if (block.type === 'tool-call' && typeof block.id === 'string')
+                names.set(block.id, String(block.name));
+        }
+    }
+    return names;
+}
+/** Project one assistant message onto Gemini parts, signatures included. */
+function assistantParts(message, model) {
+    const replay = readGeminiReplay(message, model);
+    const parts = [];
+    message.content.forEach((block, index) => {
+        const signature = replay?.[index]?.thoughtSignature;
+        if (block.type === 'text') {
+            if (typeof block.text === 'string' && block.text.length > 0) {
+                parts.push({ text: block.text, ...signature === undefined ? {} : { thoughtSignature: signature } });
+            }
+            return;
+        }
+        if (block.type === 'tool-call') {
+            const call = {
+                name: String(block.name),
+                args: toolInput(String(block.arguments)),
+                ...typeof block.id === 'string' && block.id.length > 0 ? { id: block.id } : {},
+            };
+            parts.push({ functionCall: call, ...signature === undefined ? {} : { thoughtSignature: signature } });
+        }
+        // Reasoning blocks carry text this adapter never asks for; a Gemini thought
+        // part needs its own signature to replay, so a foreign one is dropped.
+    });
+    return parts;
+}
+/** Project one user message onto Gemini parts. */
+function userParts(message) {
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0)
+            parts.push({ text: block.text });
+    }
+    return parts;
+}
+/**
+ * Project one harness `tool`-role message onto the `functionResponse` part
+ * Gemini requires for the `functionCall` it answers.
+ *
+ * The harness puts the call identity on the message, the provider reads it from
+ * the part, and the function name is what Vertex matches a response by.
+ */
+function toolResultParts(message, names) {
+    const callId = message.toolCallId;
+    if (callId === undefined || callId.length === 0)
+        return userParts(message);
+    return [{
+            functionResponse: {
+                name: names.get(callId) ?? callId,
+                id: callId,
+                response: { result: resultText((message.content ?? [])) },
+            },
+        }];
+}
+/**
+ * Build the request body for one model call.
+ *
+ * History is projected part by part (tool results become `functionResponse`
+ * parts, replayed tool calls carry their thought signature), and consecutive
+ * same-role turns are merged, which is the one turn shape Gemini accepts.
+ *
+ * No `thinkingConfig` is ever sent: Gemini's own default (dynamic thinking) is
+ * what keeps 2.5 Pro working, since that model refuses a zero thinking budget.
+ * @param options - the harness request.
+ * @param config - project, location, and default output cap.
+ * @returns the wire body.
+ */
+export function buildGeminiRequest(options, config) {
+    const model = options.model;
+    const names = toolNames(options.messages);
+    const contents = [];
+    for (const message of options.messages) {
+        if (message.role === 'system' || message.role === 'developer')
+            continue;
+        const role = message.role === 'assistant' ? 'model' : 'user';
+        const parts = message.role === 'tool'
+            ? toolResultParts(message, names)
+            : role === 'model'
+                ? assistantParts(message, model)
+                : userParts(message);
+        if (parts.length === 0)
+            continue;
+        const previous = contents.at(-1);
+        if (previous !== undefined && previous.role === role)
+            previous.parts.push(...parts);
+        else
+            contents.push({ role, parts });
+    }
+    const system = systemParts(options).join('\n\n');
+    const tools = (options.tools ?? []).map(tool => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: geminiSchema(tool.parameters),
+    }));
+    const generationConfig = {
+        maxOutputTokens: options.maxTokens ?? config.maxTokens,
+        ...options.temperature === undefined ? {} : { temperature: options.temperature },
+        ...options.stop === undefined || options.stop.length === 0 ? {} : { stopSequences: [...options.stop] },
+    };
+    return {
+        contents,
+        ...system.length === 0 ? {} : { systemInstruction: { parts: [{ text: system }] } },
+        ...tools.length === 0 ? {} : { tools: [{ functionDeclarations: tools }] },
+        generationConfig,
+    };
+}
+/**
+ * Map Gemini's counters onto harness accounting.
+ *
+ * Gemini folds cached input into `promptTokenCount` and reports it separately as
+ * well, so the harness's disjoint rule means subtracting it out; thinking tokens
+ * are billed as output, exactly as the harness's own pi-ai mapping treats them.
+ * @param usage - the latest cumulative counters seen on the stream.
+ * @returns disjoint harness counts.
+ */
+export function mapGeminiUsage(usage) {
+    const cached = usage.cachedContentTokenCount ?? 0;
+    const prompt = usage.promptTokenCount;
+    const thoughts = usage.thoughtsTokenCount ?? 0;
+    const candidates = usage.candidatesTokenCount;
+    const output = (candidates ?? 0) + thoughts;
+    // An exact total is the provider's own; the arithmetic fallback is only as
+    // complete as the two counters it needs, so a missing one omits the total
+    // rather than reporting a partial sum as the whole request.
+    const total = usage.totalTokenCount
+        ?? (prompt === undefined || candidates === undefined ? undefined : prompt + output);
+    return {
+        inputTokens: Math.max(0, (prompt ?? 0) - cached),
+        outputTokens: output,
+        ...total === undefined ? {} : { totalTokens: total },
+        ...cached > 0 ? { cacheReadTokens: cached } : {},
+        ...thoughts > 0 ? { reasoningTokens: thoughts } : {},
+    };
+}
+/**
+ * Map Gemini's finish reason onto the harness vocabulary.
+ *
+ * `STOP`, `OTHER`, and an absent reason all mean the same thing here, and so
+ * does any reason a provider release adds: the turn ended, and only a tool call
+ * in it changes what that is called.
+ * @param reason - the `finishReason` Vertex reported.
+ * @param sawToolCall - whether the response contained a function call, which
+ *   Gemini reports as an ordinary `STOP`.
+ * @returns the harness finish reason.
+ */
+export function mapGeminiFinishReason(reason, sawToolCall) {
+    switch (reason) {
+        case 'MAX_TOKENS':
+            return { kind: 'max-tokens' };
+        case 'SAFETY':
+        case 'RECITATION':
+        case 'BLOCKLIST':
+        case 'PROHIBITED_CONTENT':
+        case 'SPII':
+        case 'IMAGE_SAFETY':
+            return {
+                kind: 'error',
+                failure: {
+                    message: `google-vertex: the model refused to answer (finish reason ${reason})`,
+                    code: SAFETY_BLOCKED_CODE,
+                },
+            };
+        case 'MALFORMED_FUNCTION_CALL':
+            return {
+                kind: 'error',
+                failure: {
+                    message: 'google-vertex: the model produced a malformed function call',
+                    code: 'INVALID_REQUEST',
+                },
+            };
+        default:
+            return sawToolCall ? { kind: 'tool-calls' } : { kind: 'stop' };
+    }
+}
+/**
+ * Translate Gemini's `streamGenerateContent` chunks into harness chunks.
+ *
+ * Gemini streams whole parts rather than deltas, so the shape of this translator
+ * is: text parts append to one open text block, a function call closes that block
+ * and is itself closed immediately (arguments arrive complete), and the terminal
+ * chunk carries usage plus the stop reason.
+ */
+export class GeminiStreamTranslator {
+    #model;
+    #open;
+    #nextIndex = 0;
+    #replay = [];
+    #usage = {};
+    #usageReported = false;
+    #finishReason;
+    #sawFinish = false;
+    #failed = false;
+    #sawToolCall = false;
+    /**
+     * @param model - the model being called, recorded in the replay envelope.
+     */
+    constructor(model) {
+        this.#model = model;
+    }
+    /**
+     * Feed one decoded SSE payload.
+     * @param event - the parsed chunk.
+     * @returns the chunks this payload completes, in order.
+     */
+    handle(event) {
+        if (this.#failed)
+            return [];
+        // Vertex can refuse mid-stream with an error envelope instead of a
+        // candidate. Without this the body simply ends, and the adapter would
+        // report a truncated response and lose the provider's own message and code.
+        const error = event['error'];
+        if (error !== undefined) {
+            this.#failed = true;
+            return [{ type: 'finish', reason: { kind: 'error', failure: failureForEvent(error) } }];
+        }
+        const out = [];
+        const candidates = event['candidates'];
+        if (Array.isArray(candidates)) {
+            for (const candidate of candidates) {
+                const fields = asObject(candidate);
+                if (fields === undefined)
+                    continue;
+                const content = asObject(fields['content']);
+                const parts = content?.['parts'];
+                if (Array.isArray(parts))
+                    for (const part of parts)
+                        out.push(...this.#part(asObject(part)));
+                const reason = fields['finishReason'];
+                if (typeof reason === 'string') {
+                    this.#finishReason = reason;
+                    this.#sawFinish = true;
+                }
+            }
+        }
+        const usage = asObject(event['usageMetadata']);
+        if (usage !== undefined)
+            this.#mergeUsage(usage);
+        return out;
+    }
+    /** Absorb one content part. */
+    #part(part) {
+        if (part === undefined)
+            return [];
+        // A thought summary is reasoning text this adapter never requested; keeping
+        // it would need its own signature to replay, which the harness block cannot
+        // carry, so it is dropped rather than made unreplayable.
+        if (part['thought'] === true)
+            return [];
+        const signature = typeof part['thoughtSignature'] === 'string' ? part['thoughtSignature'] : undefined;
+        const call = asObject(part['functionCall']);
+        if (call !== undefined) {
+            const out = this.#closeText();
+            const index = this.#nextIndex;
+            this.#nextIndex += 1;
+            const name = typeof call['name'] === 'string' ? call['name'] : '';
+            const id = typeof call['id'] === 'string' && call['id'].length > 0 ? call['id'] : `call_${index}`;
+            const args = asObject(call['args']) ?? {};
+            this.#replay.push({ type: 'tool-call', ...signature === undefined ? {} : { thoughtSignature: signature } });
+            this.#sawToolCall = true;
+            out.push({ type: 'block-start', index, blockType: 'tool-call' }, { type: 'tool-call-delta', index, id, name, argumentsDelta: JSON.stringify(args) }, { type: 'block-end', index, block: { type: 'tool-call', id, name, arguments: JSON.stringify(args) } });
+            return out;
+        }
+        const text = part['text'];
+        if (typeof text === 'string' && text.length > 0) {
+            const open = this.#open;
+            if (open !== undefined) {
+                open.text += text;
+                if (signature !== undefined)
+                    this.#setSignature(signature);
+                return [{ type: 'text-delta', index: open.index, text }];
+            }
+            const index = this.#nextIndex;
+            this.#nextIndex += 1;
+            this.#open = { index, kind: 'text', text, signature };
+            this.#replay.push({ type: 'text', ...signature === undefined ? {} : { thoughtSignature: signature } });
+            return [{ type: 'block-start', index, blockType: 'text' }, { type: 'text-delta', index, text }];
+        }
+        return [];
+    }
+    /** Replace the open block's recorded signature, if the provider sent one. */
+    #setSignature(signature) {
+        const open = this.#open;
+        if (open === undefined)
+            return;
+        const index = this.#replay.length - 1;
+        const entry = this.#replay[index];
+        if (entry === undefined || entry.type !== open.kind)
+            return;
+        this.#replay[index] = { type: entry.type, thoughtSignature: signature };
+        open.signature = signature;
+    }
+    /** Close an open text block, emitting its authoritative end. */
+    #closeText() {
+        const open = this.#open;
+        if (open === undefined)
+            return [];
+        this.#open = undefined;
+        return [{ type: 'block-end', index: open.index, block: { type: 'text', text: open.text } }];
+    }
+    /** Merge the newest cumulative usage counters. */
+    #mergeUsage(usage) {
+        const merged = takeCounters(usage, [
+            'promptTokenCount',
+            'candidatesTokenCount',
+            'cachedContentTokenCount',
+            'thoughtsTokenCount',
+            'totalTokenCount',
+        ]);
+        // Only a counter the provider actually sent counts as a report.
+        if (Object.keys(merged).length === 0)
+            return;
+        this.#usageReported = true;
+        this.#usage = { ...this.#usage, ...merged };
+    }
+    /** True once the provider reported a finish reason. */
+    get sawFinish() {
+        return this.#sawFinish;
+    }
+    /** True once an in-band error ended the stream, which `handle` already reported. */
+    get failed() {
+        return this.#failed;
+    }
+    /** {@inheritDoc StreamTranslatorLike.terminal} */
+    get terminal() {
+        return this.#failed;
+    }
+    /**
+     * Terminal chunks: the closed tail, usage, and the finish reason.
+     *
+     * Called once, after the body ends. A response that produced nothing at all is
+     * reported as an empty response rather than as a silent success.
+     * @returns the trailing chunks in emission order.
+     */
+    finish() {
+        const out = this.#closeText();
+        const reason = mapGeminiFinishReason(this.#finishReason, this.#sawToolCall);
+        if (this.#replay.length === 0 && reason.kind !== 'error') {
+            return [{
+                    type: 'finish',
+                    reason: {
+                        kind: 'error',
+                        failure: {
+                            message: 'google-vertex: the model completed the response with no content',
+                            code: EMPTY_RESPONSE_CODE,
+                        },
+                    },
+                }];
+        }
+        return [
+            ...out,
+            // Usage accompanies a real provider report; a synthesized zero would
+            // claim a measurement that never happened.
+            ...this.#usageReported ? [{ type: 'usage', usage: mapGeminiUsage(this.#usage) }] : [],
+            { type: 'finish', reason, replayState: geminiReplayState(this.#model, this.#replay) },
+        ];
+    }
+}

package/lib/gemini_adapter.js

@@ -0,0 +1,61 @@
+/**
+ * Provider adapter for Google's own Gemini models on Vertex AI.
+ *
+ * Same credential as the Claude route beside it (one service-account file, one
+ * bearer token per request) over the `publishers/google` endpoint instead of
+ * `publishers/anthropic`. Both live in one plugin row so project, region, and
+ * credentials are configured once.
+ *
+ * The route is text-only: `inputModalities: ['text']` makes `LlmRuntime` project
+ * images and files to placeholder text before dispatch. Tool calling is fully
+ * supported, including Vertex's required thought-signature replay.
+ *
+ * @module dsh-google-vertex/gemini-adapter
+ */
+import { streamVertex, VertexPublisherAdapter, } from './adapter.js';
+import { buildGeminiRequest, DEFAULT_GEMINI_CONTEXT_WINDOW, DEFAULT_GEMINI_MAX_TOKENS, GeminiStreamTranslator, geminiEndpointFor, } from './gemini.js';
+/**
+ * The capacities every Gemini model serves, wherever the id came from. A
+ * catalog entry carries no capacities of its own until a model actually needs
+ * different ones.
+ */
+const GEMINI_CAPACITY = {
+    contextWindow: DEFAULT_GEMINI_CONTEXT_WINDOW,
+    defaultMaxTokens: DEFAULT_GEMINI_MAX_TOKENS,
+};
+/**
+ * Duck-typed adapter over Vertex's Gemini publisher endpoint.
+ *
+ * The metadata face and the streaming pipeline are the shared ones; this class
+ * supplies the Gemini catalog, wording, endpoint, body, and translator.
+ */
+export class GoogleVertexGeminiAdapter extends VertexPublisherAdapter {
+    /**
+     * @param config - the resolved configuration this adapter serves.
+     * @param options - transport, token-source, and discovery overrides for tests.
+     */
+    constructor(config, options = {}) {
+        super({
+            providerName: 'Google Vertex AI (Gemini)',
+            capacity: GEMINI_CAPACITY,
+            describe: row => `Google Gemini on Vertex AI (project ${row.project}, ${row.location}).`,
+        }, config, options);
+    }
+    /**
+     * Stream one completion through `:streamGenerateContent?alt=sse`.
+     *
+     * Gemini has no terminal event: the body simply ends, and the finish reason
+     * rides the last content chunk. A body that ends without one is therefore a
+     * truncated response, which is what {@link GeminiStreamTranslator.sawFinish}
+     * distinguishes, unless an in-band error or the idle watchdog already ended
+     * the turn. The shared pump owns the watchdog, the token mint, and the SSE
+     * loop; this route's finish is built at the end of the body.
+     */
+    stream(options) {
+        return streamVertex(this.config, options, this.fetch, this.tokens, model => new GeminiStreamTranslator(model), {
+            endpoint: (model, config) => geminiEndpointFor(config.project, config.location, model),
+            body: (request, config) => buildGeminiRequest(request, config),
+            truncatedMessage: model => `google-vertex: model "${model}" stream ended before a finish reason`,
+        });
+    }
+}

package/lib/host.js

@@ -0,0 +1,18 @@
+/**
+ * The slice of the DeepSeek Harness host surface this plugin uses, declared
+ * structurally.
+ *
+ * Like the other plugins under `~/dsh-plugins`, this package is installed
+ * outside the harness checkout and cannot resolve `@deepseek-ai/*` from its own
+ * directory, so it carries no runtime dependency on them. `LlmRuntime` reaches
+ * adapters through plain method calls (there is no `instanceof LlmAdapter`
+ * check anywhere in it), so a duck-typed adapter is a supported shape.
+ *
+ * Each declaration is narrowed to what this adapter reads or emits. Fields the
+ * adapter never touches are deliberately absent: a mirrored field that nothing
+ * reads is a field whose absence goes unnoticed. Widen a declaration when the
+ * adapter starts using it, not before.
+ *
+ * @module dsh-google-vertex/host
+ */
+export {};