Skip to content

dsh-google-vertex

Verified

@ostapyrih/dsh-google-vertex Β· v0.16.4 Β· MIT Β· Web UI

Google Vertex AI provider for DeepSeek Harness: service-account auth for Claude, Gemini, and DeepSeek models

Install

dsh plugin add @ostapyrih/dsh-google-vertex

Confirm the layer applied with dsh --profile default --dump-config β€” see the install guide.

Source

Creators

Readme

dsh-google-vertex

One Google service-account JSON file unlocks Claude, Gemini, and DeepSeek models inside DeepSeek Harness: Claude Opus 4.6, Sonnet 4.6, Opus 4.5, Sonnet 4.5, Haiku 4.5, Gemini 3.5 Flash, 3.1 Pro Preview, 3 Flash Preview, 2.5 Pro, 2.5 Flash, 2.5 Flash-Lite, and DeepSeek models on Vertex Model Garden (DeepSeek-V3, DeepSeek-R1, DeepSeek-V4.1-Flash). Install it when your model capacity already lives in a Google Cloud project and you would rather point Harness at a credential file than paste an API key. Nothing is copied into the harness credential store: the file is read once at mount, and each request trades a signed RS256 assertion for a cached OAuth token.

What you get

  • Three provider routes from one configuration row (google-vertex-anthropic for Claude, google-vertex-gemini for Gemini, and google-vertex-deepseek for DeepSeek), all in the Web model picker.
  • Service-account auth with no API key: a path in config, or GOOGLE_APPLICATION_CREDENTIALS.
  • Streaming with tool calling across routes:
    • Claude emits raw JSON argument deltas.
    • Gemini emits complete function calls and replays thought signatures.
    • DeepSeek connects to Vertex Model Garden's OpenAI-compatible completions endpoint, streaming argument deltas and seamlessly mapping DeepSeek-R1 reasoning (delta.reasoning_content and streamed <think>...</think> tags) to Harness thought blocks.
  • Live catalog auto-discovery across all three routes (Gemini, Claude, and DeepSeek) from Vertex AI behind a five-minute cache, with built-in fallbacks. When omitted in config, catalogs are automatically discovered; pinning models (models, geminiModels, deepseekModels) is optional. DeepSeek aliases (deepseek-v3, deepseek-r1, deepseek-v4.1-flash) remain supported.
  • A Refresh models control on this plugin's row page, which drops cached catalogs and re-reads the model picker without restarting dsh web.
  • Claude prompt-cache breakpoints on tools, system, and the final conversation block, with cache read/write counts reported as usage.
  • Failure codes the harness can act on: 429 β†’ RATE_LIMIT, 5xx β†’ SERVER, RESOURCE_EXHAUSTED β†’ QUOTA, oversized β†’ CONTEXT_WINDOW_EXCEEDED, a stalled stream β†’ TIMEOUT.
  • Environment fallbacks for the credential, project, and region.

Install

Requires DeepSeek Harness >=0.2.0 <0.3.0.

Install the plugin from the GitHub repository into your active DSH profile (desktop for the desktop application, or web for dsh web):

# For the desktop application:
dsh plugin --profile desktop add github:ostapyrih/dsh-google-vertex

# Or for the web profile:
dsh plugin --profile web add github:ostapyrih/dsh-google-vertex

Alternatively, if you are developing locally from a cloned checkout:

dsh plugin --profile desktop add /path/to/dsh-google-vertex

The package declares dsh.bundle, so dsh plugin add automatically adds it to dsh.profile.bundles and the bundle's cordis.patch.yml registers the google-vertex row. Restart DeepSeek Harness after installation.

Configure

Override the row configuration by editing cordis.patch.yml in your profile directory:

  • Desktop app: ~/.dsh/profiles/desktop/cordis.patch.yml
  • Web app: ~/.dsh/profiles/web/cordis.patch.yml
- id: google-vertex
  config:
    serviceAccountFile: ~/.secrets/my-gcp-key.json
    project: my-gcp-project-id
    location: us-central1

Note on location: DeepSeek Model Garden endpoints typically run in specific regions such as us-central1. Claude is supported in regions like us-east5 and europe-west1 (or global). When using DeepSeek, set location to your Vertex AI region.

~ is expanded, and the file is read once at mount, so a typo fails loudly instead of mid-turn. A patch replaces the targeted row's whole config, so restate every key you keep. This file is live-watched: saving it remounts the plugin, no restart.

Key Default Meaning
serviceAccountFile $GOOGLE_APPLICATION_CREDENTIALS Path to the service-account JSON; ~ is expanded. Nothing is copied into the harness credential store: the file is the credential, and it is read once at mount.
project $GOOGLE_CLOUD_PROJECT, $GCLOUD_PROJECT, then the file's project_id Google Cloud project id, used by all routes.
location $GOOGLE_CLOUD_LOCATION, then global Region for endpoints, or global for aiplatform.googleapis.com. Note: DeepSeek Model Garden endpoints typically run in regions such as us-central1.
models auto-discovered (or built-in fallback) Claude ids to advertise; pins the catalog and turns live discovery off. If omitted, models are dynamically discovered from Vertex (publishers/anthropic/models).
geminiModels auto-discovered (or built-in fallback) Gemini ids to advertise; pins the catalog and turns live discovery off. If omitted, models are dynamically discovered from Vertex (publishers/google/models).
deepseekModels auto-discovered (or built-in fallback) DeepSeek ids to advertise; pins the catalog and turns live discovery off. If omitted, models are dynamically discovered from Vertex Model Garden (publishers/* /models).
contextWindow 200000 Claude context window reported per model.
maxTokens 32000 Claude output cap applied when a caller omits one.
streamIdleTimeoutMs 300000 Bound on the interval between two stream reads, on all routes.

Environment variables are read from process.env of the harness process.

Routes and models

Vertex serves models over different API shapes, which is why one row registers three routes. The service-account path, project, and region are configured once.

Route Provider path Serves
google-vertex-anthropic publishers/anthropic/models/{model}:streamRawPredict Claude, picker group Google Vertex AI (Anthropic)
google-vertex-gemini publishers/google/models/{model}:streamGenerateContent?alt=sse Gemini, picker group Google Vertex AI (Gemini)
google-vertex-deepseek endpoints/openapi/chat/completions DeepSeek, picker group Google Vertex AI (DeepSeek)

Claude defaults. Every listed family serves 200k context and caps output at 32k unless a caller asks otherwise:

Picker label Model id
Claude Opus 4.6 (Vertex) claude-opus-4-6
Claude Sonnet 4.6 (Vertex) claude-sonnet-4-6
Claude Opus 4.5 (Vertex) claude-opus-4-5
Claude Sonnet 4.5 (Vertex) claude-sonnet-4-5
Claude Haiku 4.5 (Vertex) claude-haiku-4-5

Gemini defaults. Every entry serves the same context/output pair:

Picker label Model id Context Max output
Gemini 3.5 Flash (Vertex) gemini-3.5-flash 1,048,576 65,535
Gemini 3.1 Pro Preview (Vertex) gemini-3.1-pro-preview 1,048,576 65,535
Gemini 3 Flash Preview (Vertex) gemini-3-flash-preview 1,048,576 65,535
Gemini 2.5 Pro (Vertex) gemini-2.5-pro 1,048,576 65,535
Gemini 2.5 Flash (Vertex) gemini-2.5-flash 1,048,576 65,535
Gemini 2.5 Flash-Lite (Vertex) gemini-2.5-flash-lite 1,048,576 65,535

The Gemini cap is one below Vertex's own ceiling on purpose: maxOutputTokens: 65536 is refused with "supported range is from 1 (inclusive) to 65536 (exclusive)".

DeepSeek defaults on Vertex Model Garden:

Picker label Model id Aliases Context Max output
DeepSeek-V3 (Vertex Model Garden) deepseek-ai/DeepSeek-V3 deepseek-v3 128,000 16,384
DeepSeek-R1 (Vertex Model Garden) deepseek-ai/DeepSeek-R1 deepseek-r1 128,000 16,384
DeepSeek-V4.1-Flash (Vertex Model Garden) deepseek-ai/deepseek-v4.1-flash-maas deepseek-v4.1-flash 1,000,000 16,384

DeepSeek-R1 reasoning tokens and inline <think>...</think> tags are translated into Harness reasoning blocks seamlessly. Streaming tool calling is fully supported.

Ids are Vertex's aliases, so a promoted release needs no edit here. Both catalogs are overridable from configuration for a deployment that pins dated versions.

Discovery and refresh

The lists above are the fallback, not the whole catalog. By default, all three routes dynamically discover available models from Vertex AI:

  • Gemini: fetched from Vertex's publishers/google/models catalog (filtering out embedding, TTS, image, Live, and audio variants).
  • Claude: fetched directly from publishers/anthropic/models, automatically picking up newer families (such as Claude Opus 5, Sonnet 5.5, Fable, etc.) as Google publishes them.
  • DeepSeek: fetched from Vertex Model Garden's catalog (publishers/* /models with is_hf_wildcard(false) filter in us-central1), automatically discovering servable MaaS models.

Discovered models are cached for five minutes so opening the model picker is fast and doesn't spam the network. If any discovery call fails, the adapter seamlessly falls back to the static defaults.

The picker re-reads the catalogs when the host says a model input changed. This plugin's row page also carries the control that forces an immediate re-read: open Plugins in the sidebar, open the dsh-google-vertex bundle, and configure the google-vertex row. Refresh models drops all cached catalogs and re-fetches them from Vertex AI.

Try it

  1. Restart dsh web, then open a session.
  2. Type /model in the composer, or click the model seat beside it.
  3. Pick Google Vertex AI (Anthropic) β†’ Claude Sonnet 4.6 (Vertex), or the Gemini group for a Gemini model. Selecting a model also makes it the default for new sessions; a session that already sent a request keeps the model recorded in its own log.
  4. Type a prompt that needs a tool:
List the files in this directory and tell me which one is largest.

The agent runs a shell tool and answers from its output. The same works on the Gemini group, including the signed replay of the model's function call.

How it works

Failed HTTP requests forward valid Retry-After seconds or HTTP dates to the harness retry policy. Invalid, non-positive, and past delays are omitted.

  • Auth. The service-account JSON is read once at mount. Per request, a JWT is signed with its private key, sent to the file's token_uri (or Google's public token endpoint when the file omits one), and traded for an access token (https://www.googleapis.com/auth/cloud-platform), which is cached and refreshed five minutes before expiry. The request carries it as a bearer token. A credential problem reports AUTH; a token-endpoint transport problem reports TRANSPORT.
  • Streaming. Both routes bound every read by streamIdleTimeoutMs, including HTTP error bodies. The watchdog owns its own controller, so a stalled read is torn down and the turn ends with a single TIMEOUT failure instead of hanging. Caller cancellation ends as an aborted finish, not a provider error.
  • Failure classification. A refused HTTP response and an in-band provider error envelope classify the same way: a named cause first (RESOURCE_EXHAUSTED β†’ QUOTA, oversized prompt β†’ CONTEXT_WINDOW_EXCEEDED), then the numeric code (429 β†’ RATE_LIMIT, 5xx β†’ SERVER, 404 β†’ NOT_FOUND). Gemini has no terminal event, so a body that ends without a finish reason is a truncated response unless the watchdog or an in-band error already ended the turn.
  • Replay. Gemini 3 signs its function calls, and a replay that drops the signature is refused with 400 INVALID_ARGUMENT: Function call is missing a thought_signature in functionCall parts. The adapter stores each emitted block's thoughtSignature in the harness replay envelope and echoes it on the next request. Signatures are per model, so a cross-model replay sends the call unsigned rather than failing. No thinkingConfig is ever sent: Gemini's dynamic-thinking default is what keeps gemini-2.5-pro working. Thinking tokens still arrive in usageMetadata and count as output.
  • Attribution. Requests carry attributionHeaders() from @deepseek-ai/dsh-llm rather than a pinned release line, so User-Agent cannot drift from the installed harness.

Limits

  • Text only. Both routes declare inputModalities: ['text'], so the harness projects images and files to placeholder text before dispatch. Claude and Gemini on Vertex both accept images; wiring the attachment service into these adapters is the work that would add it.
  • No extended thinking on Claude. That route never sends a thinking block, and replaying one needs a thinking signature the harness reasoning block cannot hold. Enabling thinking without it makes every tool round trip fail.
  • Gemini thought summaries are dropped for the same signature reason, so only answer text is shown.
  • Gemini output limits. A thought-only MAX_TOKENS response keeps its length stop and usage counters. A complete function call remains executable at that limit; safety and malformed-call errors still take precedence. Empty normal completions retain their reported usage.
  • Vertex AI API must be enabled on the project, and the service account needs roles/aiplatform.user.
  • Claude is not servable in every region. global, us-east5, and europe-west1 answered; us-central1 returned 400 FAILED_PRECONDITION: … is not servable in region us-central1. A 404 NOT_FOUND naming the publisher model means the id does not exist on Vertex; 429 RESOURCE_EXHAUSTED is the project's quota, not a bad request.
  • Claude prompt caching has provider-side minimums. Blocks under the cacheable minimum are accepted and simply not cached.

The pi-ai google-vertex route

Harness already ships a pi-ai-backed google-vertex route that serves Gemini from a credential record carrying the same three environment values. It accepts images and surfaces thinking summaries; this plugin's Gemini route is text-only and drops them. Choose it when those matter. Its record in ~/.dsh/.credentials.yaml (owner-only, mode 600, live-watched):

records:
  llm-pi-ai/google-vertex:
    kind: api-key
    env:
      GOOGLE_APPLICATION_CREDENTIALS: /path/to/service-account.json
      GOOGLE_CLOUD_PROJECT: global-claude-project
      GOOGLE_CLOUD_LOCATION: global

Two of its catalog entries disagree with Vertex's own limits, so those models need an override in ~/.dsh/settings.yaml under llm-pi-ai.providers.google-vertex.modelOverrides: gemini-2.5-pro needs reasoningEfforts: false (Vertex rejects thinkingBudget: 0 with 400 INVALID_ARGUMENT), and gemini-2.5-flash-lite needs maxTokens: 65535. This plugin's own Gemini route needs neither.

Development

bun test           # hermetic, stubbed transport, no network
bun run build      # tsc -p tsconfig.build.json β†’ lib/index.js + lib/types/
bun run typecheck  # tsc -p tsconfig.json

The package ships the built lib/ and declares dsh.bundle, so a change to src/ needs bun run build before it takes effect. For local development, run bun run build, then dsh plugin --profile <name> add <path-to-checkout> and restart dsh web. lib/client.js is the exception: the browser half is authored directly as plain JavaScript in the client module loader's factory format and is not produced by tsc.

Coverage: the signed assertion, token caching and refresh, both auth failure classes, request projection, cache breakpoints, Gemini request projection with signature replay, SSE framing across split chunks, every terminal finish class (including the stream idle bound and an in-band provider error envelope), usage reported only when the provider reported it, and configuration validation. A real Cordis Context mount proves both routes are registered and withdrawn with the fiber, and that the plugin's settings change drops both cached catalogs. The browser half is imported from lib/client.js under a stub of the module loader's own registration format, which is how its slot, its Refresh control, and its write are covered without a browser.

dsh loads plugins on Node ^22.19.0 || >=24.0.0; development and tests run on bun.

Licence

MIT. See LICENSE.