dsh-mcp-panel: Instructions file for Codex

AGENTS.md

Standalone DeepSeek Harness plugin repository (dsh-mcp-panel). Development follows the dsh-plugin-guide skill and the official plugin contract; this file records repo-local decisions.

Layout

• src/index.ts — function-plugin contract (name/inject/Config/apply; NO default export — the Loader unwraps exports.default ?? exports).
• src/service.ts — McpPanelService (TypertRemoteService, namespace mcpPanel): read-only snapshot assembly from loader rows + tool registry + upstream status observations. Serves mcpPanel/status, starts panel-only probes through mcpPanel/probe (probe(serverName); needs ctx.jobs, streamable-http and stdio rows), appends CRUD fragments through mcpPanel/writePatch (approval-gated, backup-first, and RE-VERIFIED against the loader's re-applied state — a skipped patch never reads as success; writeVerifyEnabled/writeVerifyTimeoutMs tune the gate), and trials tools (including the three shared resource tools) through mcpPanel/callTool. Resources capability = ctx.mcpResources present AND the three shared tools registered in this scope.
• src/wire.ts — the snapshot vocabulary, its zod v4 wire schema, and the single mcpPanel/status invocation descriptor shared verbatim by the host ./typert manifest (src/typert.host.ts) and the client Remote contribution (src/client/remote.ts) — one canonical source so the two codecs can never drift.
• src/upstream.ts — the proposed upstream mcp/status seam (event + query service face), declared here via cordis declaration merging and consumed with feature detection; when upstream ships it, its identical declarations merge cleanly and a conflicting signature fails this compile (intended tripwire). Proposal text: docs/upstream-proposal.md in the deepseek-harness repo. Resources are bridged by the SHIPPED @deepseek-ai/dsh-mcp-resources service; this file declares its minimal structural face (mcpResources) for presence detection only — resource trials go through the OFFICIAL shared tools, never provider internals.
• src/sanitize.ts — display redaction (URL query credentials, userinfo passwords, header values, bearer tokens, JWTs). Pure; extreme-case tests in tests/sanitize.spec.ts.
• src/grouping.ts / src/aggregate.ts — pure enumeration/grouping and status aggregation with missing-field tolerance.
• src/command.ts — the /mcp command (standard CommandResult; logged via command/run + command/done).
• src/patch.ts — pure module: config validation against the official client's face, keep-semantics merging, and the loader-dialect fragment renderer. CRUD emits insert (add) and id-targeted overrides (- id: + name: + disabled:/config:) — the harness patch dialect has NO set and no remove, so disabling a row IS the canonical removal (issue #27).
• src/trial.ts — the official-pipeline trial caller: mcp__* tools plus the three shared resource tools list_mcp_resources / list_mcp_resource_templates / read_mcp_resource, with the requested server injected into their arguments (conflicts fail closed).
• src/probe.ts — optional mcp_probe background-job tool (unowned job: panel-only results). Both transports probe: streamable-http via one initialize POST; stdio via spawning the row's command/args under scrubbedParentEnv (the same base the mcp-client bridge uses, imported from @deepseek-ai/dsh-subprocess) + explicit env/cwd, one initialize handshake over stdin/stdout, sanitized serverInfo or failure detail.
• src/client/ — browser half: $mount the Remote contribution, register the settings.plugins.tab entry id mcp, pure presenter in present.ts, inline scoped stylesheet in styles.ts (standalone bundles cannot use the in-repo CSS-module pipeline).
• tests/ — vitest; REAL Context + Session/ToolRuntime/CommandRuntime from the 0.1.7-rc.2 peers, fake Loader face, fake Agent, optional fake jobs.