dsh-api

dsh-api

Local HTTP API for DeepSeek Harness (DSH). Other AI agents use it to control
DSH through plain HTTP instead of the GUI.

Milestone one covers session control: list and create sessions, read history,
send prompts, stream replies, and cancel turns. Everything else remains
available through the raw /api/* passthrough.

Install

Install the plugin into a DSH web profile:

dsh plugin --profile web add link:C:/path/to/dsh-api

The package declares dsh.bundle.patch, so dsh plugin registers it in the
profile's dsh.profile.bundles automatically. No manual cordis patch is
needed. Once published, install from the registry with
dsh plugin --profile web add @kelemiao/dsh-api.

Settings live in the GUI Settings page under dsh-api and apply immediately.

Settings

Field	Type	Default	Notes
enabled	bool	true	server on/off
port	int	4777	1-65535, loopback only
token	secret	generated on first run	fixed bearer token

Endpoints

Method	Path	Purpose
GET	/health	Public health check.
GET	/api/sessions	List sessions: { items: SessionSummary[] }.
POST	/api/sessions	Create session; body { cwd?, workspaceId?, agentPreset? }.
GET	/api/sessions/:id/history	Read history; query beforeSeq?, maxMessages?.
POST	/api/sessions/:id/prompt	Send prompt; body { content, mode? }.
POST	/api/sessions/:id/cancel	Cancel the running turn.
GET	/api/sessions/:id/stream	SSE stream filtered to this session.
POST	/api/*	Raw official ApiProxy JSON RPC passthrough.
GET	/api/events.mux	Raw official aggregated SSE stream.

Convenience routes win over the passthrough; any other request whose path
starts with /api/ is forwarded verbatim to the official ApiProxy transport.

Authentication

All routes except /health require Authorization: Bearer <token>. The
server binds 127.0.0.1 only. Missing or wrong tokens get 401.

SSE

curl -N -H "Authorization: Bearer $DSH_API_TOKEN" \
  http://127.0.0.1:4777/api/sessions/<sessionId>/stream

Frames are official MuxFrame objects, filtered by session id. A prompt whose
single text block starts with / runs as a slash command, like the GUI.

Smoke test

With the plugin enabled in a running DSH:

DSH_API_TOKEN=<token> node scripts/smoke.mjs

DSH_API_URL defaults to http://127.0.0.1:4777.

Scope

Out of milestone one: ergonomic wrappers for approvals, subagents, goals,
jobs, settings, credentials, and workspace mutation; TLS; remote bind;
multi-user tokens.