Reactive-Resume/packages/dsh-plugin/docs/2026-08-16-design.md

DeepSeek Harness Plugin for Reactive Resume — Design

Date: 2026-08-16 Status: Approved, ready for implementation planning Package: dsh-plugin-reactive-resume

Post-implementation note: the tools config key and ctx.tools.restrict() call described below (Config, apply() step 2, "Tool-name generation and drift detection") were cut from v0.1.0. docs/spikes/2026-08-16-restrict-semantics.md found that restrict() cannot reach tools a plugin's own ctx.plugin(mcpClient, …) registers — it throws when called from an unscoped plugin context, and even from a real agent scope it refuses to touch a scope's own (as opposed to inherited) registrations. There is no arrangement reachable from this plugin's apply(ctx, config) where curation works, so 0.1.0 ships all tools unfiltered, per that spike's documented fallback. The rest of this document is left as originally written for history; it does not describe what shipped.

Goal

Distribute a DeepSeek Harness plugin that connects Harness to a Reactive Resume account, so a DSH user can read, create, and edit resumes and job applications from their agent session with one config row and an API key.

Context

What Reactive Resume already ships

Reactive Resume exposes a complete remote MCP server. Nothing on the server side needs to change for this plugin to work.

• packages/mcp registers 33 tools (list_resumes, read_resume, apply_resume_patch, tailor_resume_for_application, …), 3 prompts, and 2 resources.
• apps/server/src/http/app.ts mounts /mcp and /mcp/* (Streamable HTTP) plus /.well-known/mcp/server-card.json (SEP-1649).
• apps/server/src/mcp/auth.ts accepts either an OAuth Authorization: Bearer token or an x-api-key header. The API key path needs no interactive flow.
• The web app already ships API key management at /dashboard/settings/api-keys, so user provisioning is a solved problem.

What DeepSeek Harness provides

Verified against the published packages, not only the docs.

• A plugin is a TypeScript module exporting name, optional inject, and apply(ctx, config). Config schemas use @deepseek-ai/schemastery.

• @deepseek-ai/dsh-mcp-client (v0.0.1-rc.1) bridges one external MCP server per plugin instance. Its StreamableHttpConfig is exactly:

  interface StreamableHttpConfig {
    transport: 'streamable-http'
    serverName: string      // [A-Za-z0-9_-]{1,32}, unique across live instances
    url: string
    headers: Record<string, string>
    toolCallTimeoutMs: number
    failOnStartupError: boolean
  }
  

  Bridged tools become model-facing as mcp__<serverName>__<rawName>.

• ctx.tools is a ToolRegistry exposing restrict(filter: ToolRestriction): () => void, where ToolRestriction is { allow?: readonly string[]; deny?: readonly string[] }.

• ctx.systemPrompt (from @deepseek-ai/dsh-system-prompt) exposes section(section: PromptSection): () => void, where PromptSection is { name, order, text, complete? }. Convention: -100 is harness identity, 0 the deployment persona, and 100–199 is tool guidance.

• Plugins are distributed on npm and discovered through the dsh-plugin GitHub topic.

The gap this plugin fills

dsh-mcp-client has no tool filtering and no way to contribute prompt text. A user pasting a raw MCP row into cordis.yml gets all 33 tool schemas in their context budget and no guidance on Reactive Resume's JSON Patch semantics. Those two things are the plugin's reason to exist.

Decisions

Decision	Choice	Why
Scope	Thin MCP bridge + prompt section	The tool layer already exists and is maintained in Reactive Resume. Reimplementing 33 tool contracts against oRPC would drift every release.
Repo	Standalone, outside the Reactive Resume monorepo	The plugin imports nothing from Reactive Resume — it speaks HTTP. The monorepo has no npm publish pipeline: root and every package are private: true, there is no build output, no changesets, no NPM_TOKEN, and no publish workflow. Adding one to ship a dependency-free package is cost without benefit.
Auth	x-api-key only	Two clicks in Reactive Resume settings. OAuth needs a token store and an interactive flow for no gain.
Drift protection	Server-card contract test in CI	Replaces the lockstep the monorepo would have given, without the pipeline.

Architecture

Package shape

Namespace plugin, mirroring dsh-mcp-client's own export form:

export const name = 'reactive-resume'
export const inject = ['tools', 'systemPrompt']
export const Config: z<Config>
export async function apply(ctx: Context, config: Config): Promise<void>

@deepseek-ai/cordis, @deepseek-ai/dsh-tools, @deepseek-ai/dsh-system-prompt, and @deepseek-ai/dsh-mcp-client are peerDependencies so the plugin binds to the host's versions rather than installing a second copy of the runtime.

Config

interface Config {
  /** API key from <url>/dashboard/settings/api-keys. */
  apiKey: string
  /** Reactive Resume instance origin. Default 'https://rxresu.me'. */
  url?: string
  /** Tool namespace: tools appear as mcp__<serverName>__<rawName>. Default 'resume'. */
  serverName?: string
  /** Which tool group to expose. Default 'all'. */
  tools?: 'resume' | 'applications' | 'all'
  /** Per-tool-call timeout. Default inherited from dsh-mcp-client. */
  toolCallTimeoutMs?: number
}

url accepts any origin so self-hosted instances work unchanged.

apply()

Three steps, in order:

1. Mount the bridge. ctx.plugin(mcpClient, { transport: 'streamable-http', serverName, url:${url}/mcp, headers: { 'x-api-key': apiKey }, toolCallTimeoutMs, failOnStartupError: true }). failOnStartupError: true turns a bad API key into a loud activation failure instead of tools that silently fail at call time.

2. Curate the tool surface. When tools !== 'all', call ctx.tools.restrict({ deny: [...] }) with the namespaced names of the excluded group, computed from the generated tool-name list. See "Open risk" below.

3. Contribute prompt guidance. ctx.systemPrompt.section({ name: 'reactive-resume', order: 150, text: PATCH_GUIDE }).

All three return disposers; Cordis effect scoping unwinds them on unload, so no manual cleanup is needed beyond returning them where the API expects it.

PATCH_GUIDE

The plugin's substance. Roughly 40 lines covering the failure modes Reactive Resume already encodes as error hints in packages/mcp/src/tools.ts (errorHint) — those hints exist precisely because models get these wrong:

• Call read_resume before apply_resume_patch; never patch blind.
• apply_resume_patch takes RFC-6902 operations against the resume data document.
• Fetch the resume://_meta/schema resource before constructing paths.
• Section entries are arrays of objects keyed by UUID; ids are not indices.
• A locked resume rejects writes — call unlock_resume first.
• list_resumes is the way to recover a valid id after a 404.

Written as static text, not a provider function — it does not vary per assembly.

Tool-name generation and drift detection

Superseded by the move into the monorepo. The plugin now sits beside the MCP server it bridges, so src/tool-names.test.ts reads @reactive-resume/mcp/tool-names directly. A tool rename fails that test on the same pull request. The generated snapshot, the fetch script, and the scheduled network job described below no longer exist.

• Build step fetches <url>/.well-known/mcp/server-card.json and emits src/tool-names.generated.ts containing the raw tool names split into the resume and applications groups.
• The generated file is committed, so npm install never needs network access.
• A scheduled CI job refetches from https://rxresu.me and fails when the committed list no longer matches the live card. That failure is the signal to cut a new plugin release.

Install UX

README's copy-paste block:

- insert:
    - id: reactive-resume
      name: dsh-plugin-reactive-resume
      config:
        apiKey: !!js process.env.RXRESUME_API_KEY

Open risk

ToolRegistry.restrict's contract reads: "Per-scope filter over the tools a scope INHERITS — the global layer and every ancestor layer on its chain. Restrictions intersect, and do not affect the scope's own registrations."

ctx.plugin(mcpClient, …) mounts the bridge in a child scope of the plugin's context. The bridged tools are therefore registered in a descendant, not an ancestor, of the scope calling restrict. Whether a parent-scope restriction reaches them is unverified.

This must be settled by a spike before the config surface is committed, because tools is a public config key and removing it later is a breaking change.

Fallback if restrict does not reach the child scope: ship 0.1.0 without the tools key (equivalent to 'all'), and solve curation in 0.2.0 — possibly by mounting the bridge at the same scope level rather than as a child. The prompt section alone justifies the release.

Testing

• Spike (blocking): run a local Reactive Resume (dotenvx run -f .env.local -- pnpm dev, port 3000), point a scratch Harness config at http://localhost:3000/mcp with an x-api-key, and confirm (a) the Streamable HTTP bridge connects and lists 33 tools, and (b) whether ctx.tools.restrict from the plugin's scope hides bridged tools.
• Unit: Config schema defaults and validation; the deny-list computation from the generated tool names; PATCH_GUIDE section registers at order 150 with the expected name.
• Contract: server-card fetch matches src/tool-names.generated.ts.
• Manual smoke before publish: in a real Harness session against rxresu.me — list resumes, read one, apply a patch, verify the change in the web UI.

Out of scope

OAuth support, ctx.commands shortcuts, a bundled Harness skill, local resume caching, and PDF rendering inside Harness. Each is additive and none blocks a useful 0.1.0.

Build order

0. Spike restrict() semantics and the Streamable HTTP bridge against localhost.
1. Repo scaffold, Config schema, bridge mount, README. End-to-end working install.
2. PATCH_GUIDE prompt section.
3. Tool profiles, generated name list, drift CI.
4. Publish 0.1.0, tag the repo with the dsh-plugin topic, submit to awesome-deepseek-harness.