dsh-agent-hints
DeepSeek Harness (dsh) 的每次请求服务意图提示：独立的 chat-completions 提供商路由（deepseek-hint），在每次主模型请求中携带 X-Agent-Hint HTTP 标头（UTF-8 JSON、base64url）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:evan7ang/dsh-agent-hints#83ffebbfdd5ec9705690e845596b4bdb0b8a4ca0Agent Hints 以 dsh-agent-hints 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
点击下方 Badge 复制 Markdown，粘贴到 README 即可。
验证 package.json 声明的 GitHub 仓库，即可管理这个公开页面。认领后，Hub 会优先安排当前版本的安全扫描，并在通过后公开展示结果。
认领这个 Plugin →Per-request serving-intent hints for DeepSeek Harness (DSH): every main-line model request carries a structured AgentHint on the X-Agent-Hint HTTP header (UTF-8 JSON, base64url) — session identity, agent status, priority, and cache control — so a serving engine (your inference gateway) can observe and act on what the agent is doing, per the "agent signals, engine consumes" pattern (the same family as NVIDIA Dynamo Agent Hints).
The plugin registers an independent provider route deepseek-hint backed by its own chat-completions adapter. The official deepseek-official route stays mounted and remains the fallback; deployment switches via agent-default-model.provider. Zero harness source modification, zero harness runtime dependencies (cordis is touched as a structural duck type only).
English | 中文
The harness LlmAdapter contract is thin (only stream() is required), and the official adapter builds its HTTP headers inline with no extension point. This plugin therefore ships a self-contained adapter that implements the contract structurally and adds one header:
POST {baseURL}/chat/completions
authorization: Bearer …
content-type: application/json
x-deepseek-harness-session-id: session-… ← identity signal, aligned with the official adapter
x-agent-hint: eyJzZXNzaW9uIjp7InNlc3Npb25faWQi… ← base64url of a UTF-8 JSON AgentHint
The request body stays in the provider's original chat-completions format and never carries hint fields. To an endpoint that does not understand the header, it is a harmless unknown header.
This differs from static header-injection approaches (e.g. wrapping fetch to set fixed headers like a user-agent): here the hint value is derived per request from the session's durable event log (call index, compaction epoch, last tool result time) and the session lineage — there is nothing static to configure.
compaction, session-title purposes) and requests without a session identity carry no hint.strict_priority is never sent by an agent (trusted-control-plane field).prediction is not sent in v1 (it requires an observation statistics engine).x-deepseek-harness-session-id (when a session id exists) and x-deepseek-harness-compact: 1 (on compaction) are sent as-is.X-Agent-Hint payload{
"session": {
"session_id": "session-…",
"agent_type": "agent",
"call_index": 7, // derived from the session's durable log (step/start count); restart-safe
"epoch": 0 // derived from compaction/end count; restart-safe
// "parent_session_id" / "derivation": {"relation": "spawn"|"fork", "join": "sync"|"async"} — lineage sessions only
},
"agent_status": { "state": "running", "state_since_ms": 1760000000000 },
"priority": { "level": 3, "reason": "user_waiting" }, // configured; null omits
"cache_control": [{ "type": "pin", "range": { "end": 1 } }] // configured; null omits
}
Out-of-band status events (tool → running → finalize per working session, incl. awaited tool names and call ids) are reported to the optional statusSink (local JSONL file); the emit() seam is where a gateway client takes over.
Built JS is committed to this repository (lib/), so installing from GitHub needs no build-script permission:
dsh plugin add github:evan7ang/dsh-agent-hints
Pin a commit for reproducibility: dsh plugin add github:evan7ang/dsh-agent-hints#<sha>. An npm package (dsh plugin add dsh-agent-hints) is planned but not yet published.
The plugin is inert until you point it at an upstream. Override the agent-hints row in your profile's cordis.patch.yml (later layers replace the row's entire config value, so restate every key you need):
- id: agent-hints
config:
baseURL: https://your-gateway.example.com
apiKeyEnv: MY_GATEWAY_KEY
Then switch the model route:
# $DSH_HOME/settings.yaml
agent-default-model:
provider: deepseek-hint
model: deepseek-flash
The API key resolves per request: credentials service first ($DSH_HOME/.credentials.yaml / Models page), then the environment variable named by apiKeyEnv — the same order as the official adapter.
| Field | Type | Default | Description |
|---|---|---|---|
baseURL | string | — (required) | Upstream base; every chat request posts to ${baseURL}/chat/completions |
apiKeyEnv | string | — (required) | Environment-variable name resolved per request |
agentType | string | agent | Reported as session.agent_type |
priority | {level, reason} or null | {level: 3, reason: "user_waiting"} | Soft priority; null omits the field |
cacheControl | array or null | [{type: "pin", range: {end: 1}}] | Cache control entries; null omits |
thinking | "enabled" / "disabled" | enabled | disabled limits every conversation request to off |
reasoningEffort | "off"/"low"/"high"/"max" | high | Default reasoning effort when a request carries none |
models | {id, name, contextWindow, maxTokens}[] | DeepSeek-V4 family catalog | Advisory model catalog for resolveModel; provide real limits when pointing at your own gateway (they feed compaction decisions) |
defaultContextWindow | positive integer | 1000000 | Context window assumed for models absent from the catalog |
defaultMaxTokens | positive integer | 256000 | Per-request output cap materialized when callers omit one |
statusSink | string | unset (channel off) | Local JSONL path for out-of-band status events |
subagentToolNames | string[] | ["subagent"] | Tool names treated as subagent delegation for and status naming |
Invalid config aborts composition at load time with a field path — request-time hint construction has no failure path.
UNSUPPORTED_CONTENT), never silently degraded.call_index/epoch/state_since_ms are derived from the session's event log and depend on harness event semantics (step/start precedes dispatch; auxiliary calls do not count as loop steps).derivation.join reads the parent's most recent delegating tool call — parallel delegations share the latest value (accepted approximation).deepseek-official silently drops hints; the e2e wire assertions below are the safety net.npm install
npm run build # src/ → lib/ (built JS is committed)
npm test # node --test against the built JS
e2e/run.sh # keyless wire e2e: local SSE capture stub + hinted route + report assertions
The e2e resolves the dsh runtime from DSH_BIN, PATH, or a deepseek-harness checkout (DSH_CHECKOUT or the sibling directory).
derivation.join