dsh-openai-responses-bridge

An independent DeepSeek Harness plugin for connecting third-party models through the OpenAI Responses protocol or the native Gemini Generative AI protocol. The current release targets DeepSeek Harness 0.1.2-alpha.2.

The DSH plugin id is llm-openai-responses-bridge. It works through DSH plugin interfaces and does not modify the DeepSeek Harness source tree.

中文说明 | Security | License

Features

• Add third-party OpenAI Responses providers without changing DSH's native provider list.
• Add native Gemini providers in the same Bridge settings section.
• Reuse DSH/Pi native message conversion, reasoning, tool conversion, replay, usage, and stream error handling.
• Enable the remote Responses web_search tool and display its lifecycle, queries, citations, sources, and errors in a DSH conversation card.
• Discover models from an OpenAI-compatible /models endpoint and select them before saving a provider.
• Use the same provider in native mode and Code Mode/PTC without exposing a second provider-specific search tool.
• Store API keys through DSH credentials while keeping the settings file free of secret values.
• Include the dsh-pwsh-sandbox-schem compatibility behavior in the same plugin; no second shim plugin is required.
• Hot-reload provider settings without changing the host source code.

How it works

Protocol routing

Each route in the llm-openai-responses-bridge namespace chooses one native Pi protocol:

Route protocol	Upstream request	Hosted OpenAI tools
openai-responses	OpenAI Responses POST /responses	Supported when enabled
google-generative-ai	Gemini native generateContent	Not supported

The Bridge is a small compatibility layer on top of the native implementation. It does not replace DSH/Pi's general LLM adapter.

OpenAI Responses request flow

1. DSH/Pi builds the normal request from the conversation, reasoning settings, local tools, and model profile.
2. The Bridge removes max_output_tokens, which is rejected by some third-party gateways.
3. When hosted search is enabled, the Bridge appends the configured Responses hosted tool, defaults to web_search, sets tool_choice to auto when it is not already set, and requests search sources.
4. The local Function Tool named web_search is removed only on this hosted search path. Other local tools are preserved.
5. Pi continues to parse messages, reasoning, ordinary tool calls, usage, errors, and replay data from the Responses stream.

The Bridge does not inject a web-search system prompt and does not rewrite max_tokens, text, reasoning, parallel_tool_calls, client_metadata, or other native request fields.

When hosted search is disabled, the route uses Pi's native openAIResponsesApi() path directly.

Code Mode / PTC flow

Code Mode exposes only DSH's existing run_code transport to the model. The Bridge does not register a second web_search_openai tool and does not modify the Code Mode implementation. While an outer run_code call is active, the Bridge observes nested tools.web_search() dispatches and, for an enabled Bridge OpenAI Responses route, sends a minimal hosted Responses request. The result is returned as the native DSH web_search value (content, sources, and truncated), so the Code Mode program keeps its existing SDK contract.

With hosted search disabled, or when the active route is native, Google, or another provider, the nested dispatch calls DSH's normal next() path. native, code, and both therefore share the same provider setting without mixing provider-specific tool names.

Gemini request flow

Routes using google-generative-ai call Pi's native Gemini adapter and preserve the Gemini request body and generateContent stream behavior. OpenAI Responses hosted tool objects are rejected on this route instead of being sent to Gemini.

Settings and credentials

The Client bundle adds a separate Third-party models section. Providers saved there are written only to llm-openai-responses-bridge; they are not inserted into DSH's native Models page or native protocol dropdown.

The section supports:

• protocol selection between OpenAI Responses (Bridge) and Google Generative AI;
• adding, editing, and deleting Bridge providers;
• manual model entry and OpenAI-compatible model discovery;
• a write-only API-key field;
• hosted web_search enable/disable control for OpenAI Responses routes;
• preserving an existing credential when an API-key field is left blank.

The form writes the API key through credentials.set. YAML uses apiKeyEnv as the DSH credential reference; it is not a secret value and should not contain the key itself.

Model discovery is an explicit one-shot request from the editor. For an OpenAI Responses provider, the Bridge sends GET {baseURL}/models with the draft key and returns model candidates without writing settings. Google providers use manual model entries because the Bridge does not probe Gemini's model catalog.

Hosted search events

Responses hosted search events are normalized into the Bridge session event family:

bridge/hosted-web-search/start
bridge/hosted-web-search/update
bridge/hosted-web-search/end

The Client bundle registers a conversation node for these events. It renders a search card with status, query text, safe HTTP(S) sources, citations, and errors. The card is not a local DSH tool/call, and the Bridge never fetches or executes source URLs.

Sandbox schema compatibility

The plugin also registers the adapted dsh-pwsh-sandbox-schem behavior. When the effective session mode is danger-full-access, it makes a copy of the model-facing pwsh, bash, edit, and write schemas and removes only sandbox_permissions and justification from those copies.

Restricted sessions keep the native escalation schema. This changes the schema shown to the model only; it does not change DSH's sandbox policy, approval policy, executor, or filesystem authority.

Requirements

• DeepSeek Harness 0.1.2-alpha.2 APIs;
• an upstream service implementing either OpenAI Responses or native Gemini generateContent;
• Node.js ^22.19.0 or >=24.0.0 and pnpm >=10 when building from source.

For OpenAI Responses routes, baseURL must be an absolute HTTP(S) URL without the /responses suffix. For example, use https://api.example.com/v1; the native client appends /responses.

For Gemini routes, include the native API version path, such as https://generativelanguage.googleapis.com/v1beta.

Install

Install a reviewed GitHub tag or commit SHA so the DSH plugin version is reproducible:

dsh plugin --profile web add 'github:DaoCaoRenH/dsh-openai-responses-bridge#<commit-sha>'

For source development against the target DSH release, place the plugin in a temporary package directory inside a matching DSH checkout:

git clone --branch dsh-v0.1.2-alpha.2 https://github.com/deepseek-ai/deepseek-harness.git
New-Item -ItemType Directory -Force deepseek-harness/packages/bridge | Out-Null
git clone https://github.com/DaoCaoRenH/dsh-openai-responses-bridge.git deepseek-harness/packages/bridge/dsh-openai-responses-bridge
Set-Location deepseek-harness
pnpm install --no-frozen-lockfile --ignore-scripts
pnpm run build:lib
Set-Location packages/bridge/dsh-openai-responses-bridge
pnpm run check
pnpm run build

The source checkout targets DSH 0.1.2-alpha.2 only. Because this is a prerelease, source builds require matching DSH packages from a registry or a matching DSH build. The older 0.1.1-rc.2 API surface is not supported.

For normal use, install the reviewed GitHub ref with the DSH plugin manager instead of installing the unreleased DSH peer packages separately.

Remove the plugin with:

dsh plugin --profile web remove dsh-openai-responses-bridge

Configure a provider

The settings namespace is llm-openai-responses-bridge.

OpenAI Responses provider

Add this shape to $DSH_HOME/settings.yaml, or use the Third-party models settings section:

llm-openai-responses-bridge:
  providers:
    gateway:
      api: openai-responses
      apiKeyEnv: THIRD_PARTY_OPENAI_API_KEY
      displayName: Third-party Responses
      baseURL: https://api.example.com/v1
      models:
        - id: provider-model-id
          name: Provider model
          input: [text]
          contextWindow: 131072
          maxTokens: 32768
          reasoningEfforts:
            off: null
            low: low
            medium: medium
            high: high
            xhigh: xhigh
            max: max
      hostedTools:
        enabled: true
        definitions:
          - type: web_search
        toolChoice: auto

New providers created in the settings card have hosted tools disabled by default. Set hostedTools.enabled to true only when the upstream service supports Responses hosted tools and remote search is needed.

Native Gemini provider

The same namespace can contain a native Gemini route:

    google:
      api: google-generative-ai
      apiKeyEnv: GEMINI_API_KEY
      displayName: Gemini 3.6 Flash
      baseURL: https://generativelanguage.googleapis.com/v1beta
      reasoning: off
      models:
        - id: gemini-3.6-flash
          name: gemini-3.6-flash
          input: [text, image]
          maxTokens: 8192
          reasoningEfforts:
            off: null
            low: low
            medium: medium
            high: high

Gemini 3 Flash uses native MINIMAL, LOW, MEDIUM, and HIGH thinking levels. xhigh and max are not declared in the Gemini example. Actual model and thinking support depends on the configured upstream service.

The default reasoning map for Bridge models is:

reasoningEfforts:
  off: null
  low: low
  medium: medium
  high: high
  xhigh: xhigh
  max: max

Keep API keys in DSH credentials or the launching environment. Do not put a key in settings.yaml, .credentials.yaml, source files, or static headers.

Hosted tools and limits

Tool	Behavior
web_search, web_search_preview	Supported for OpenAI Responses hosted passthrough and search-card events.
web_fetch	Not registered by this plugin; source URLs are displayed as search metadata and are not fetched locally.
file_search	Requires non-empty vector_store_ids; the remote endpoint must support it.
code_interpreter	Remote passthrough only; no local DSH executor or continuation.
mcp, tool_search, namespace	Remote definitions may pass through; secrets in definitions are rejected.
image_generation	Refused in DSH 0.1.2-alpha.2 because no safe image output backend is available.
computer, local_shell, shell, apply_patch, custom	Refused because there is no DSH executor and approval continuation for these remote tools.

Hosted calls are remote calls. A remote code interpreter or MCP service does not receive local filesystem, shell, or DSH approval authority.

The plugin does not implement OAuth login/refresh or provider-specific token exchange. Use a separate authentication strategy when the upstream service requires one.

Update and troubleshooting

Update a Git-installed plugin with:

dsh plugin --profile web update

Common configuration errors:

• MISSING_CREDENTIAL: the apiKeyEnv credential reference has no value;
• invalid baseURL: use an absolute HTTP(S) URL;
• no models: every provider route must declare at least one model;
• hosted validation error: check tool-specific fields such as vector_store_ids, and keep MCP secrets in DSH credentials;
• HTTP/SSE error: verify that the selected upstream implements the expected /responses or Gemini generateContent endpoint and stream format.