dsh-sess API Reference

Target: dsh-v0.1.2-alpha.5.

This document is the wire contract between the browser half and the host half, plus the official services the host half consumes. Browser-visible copy is localized (zh/en); error codes are the stable contract — never parse messages.

1. Transport

• Channel: /dsh-sess (plugin-private; the shared /api channel is owned by the official api gateway).
• Method: HTTP POST to /dsh-sess/<endpoint> with the connection layer's standard client-request envelope; the browser calls through ctx.connection.rpc.call('/dsh-sess', endpoint, payload).
• Responses use the standard envelope:

{ ok: true,  value: ... }
{ ok: false, error: { code, message, details } }

2. Endpoints

dshSess.deleteSession

Permanently delete one session.

Payload

{ "sessionId": "session-12" }

Success value

{ "deleted": "session-12" }

Behavior (all host-side, official services only):

1. The id is validated (see below); an invalid id is a bad-request.
2. A session currently open in this process is refused (agent-busy).
3. The session must exist in durable persistence (session-not-found otherwise).
4. The durable artifact located by the official persistence backend is removed under structural guards.
5. Workspace accounting is released through the official registry detach API.

dshSess.renameSession

Rename one (e.g. archived, cold) session through the official session controller.

Payload

{ "sessionId": "session-12", "title": "New title" }

Success value

{ "title": "New title" }

Behavior:

1. The id is validated; the title must be a non-empty string (after trimming) of at most 512 characters (bad-request otherwise).
2. Delegates to ctx.sessionController.rename when that service is mounted; otherwise service-unavailable.
3. Official rejections map to title-invalid / session-not-found.

3. Session id validation

Ids accepted by both endpoints are single clean path segments over [A-Za-z0-9._-], 1–128 characters, never ./.. and never containing ... This is deliberately a subset of the harness's own mint charset: the JSONL backend stores these ids verbatim as directory names, so the artifact-removal guard can require an exact name match without reimplementing the backend's path encoder. ~ is rejected because the encoder escapes it.

4. Error codes

code	meaning	details
bad-request	invalid payload (id/title shape)	optional { sessionId }
session-not-found	no stored session with that id	{ sessionId }
agent-busy	session is retained by this process; deletion refused	{ sessionId, reason?: 'idle'|'running', retained?: 'session' }
title-invalid	official controller rejected the title	{ sessionId }
service-unavailable	required official service not mounted	{ reason }
internal	unexpected failure (message has details)	{}

The browser maps each code to localized copy (error.<code> in the dsh-sess dictionary); agent-busy is refined from the diagnostics: a running reason gets the running message, anything else gets the "retained" message including the exact session id the host saw. Unknown codes surface the host message verbatim. Deleting the session currently viewed in the browser is refused client-side before any RPC (the host cannot know the browser's current session).

5. Official services the host half consumes

The host half reads the following public service keys from the host context (listed with the package that provides them in dsh-v0.1.2-alpha.5):

ctx key	provided by	used for
ctx.connection / ctx.webServer	@deepseek-ai/dsh-client-connection / @deepseek-ai/dsh-host-webserver	serving /dsh-sess
ctx.sessions	@deepseek-ai/dsh-session	live-session guard (get)
ctx.sessionPersistence	@deepseek-ai/dsh-session-persistence (backend …-jsonl)	existence check (list), artifact location (locate)
ctx.workspaceRegistry	@deepseek-ai/dsh-workspace	accounting release (list, entity detachSession)
ctx.sessionController	@deepseek-ai/dsh-api-session-controller	rename (optional; degraded when absent)

Only the narrow documented surface of each service is touched; the code keeps structural faces for these so tests can fake them.

6. Client services the browser half consumes

The browser half registers dictionaries through the locale service and a Settings section through the slots service, and reads:

• ctx.sessions.list (snapshot + subscribe) and ctx.sessions.refresh();
• ctx.workspaces.list (snapshot + subscribe);
• ctx.connection.rpc for the /dsh-sess calls;
• ctx.locale.register/bind and ctx.slots.inject/register.

The client bundle's only runtime module requires are the baseline platform words (react, react/jsx-runtime, @deepseek-ai/dsh-client-ui-primitives).