dsh-tmp-hook

English | 中文

One-time ephemeral webhooks for DeepSeek Harness sessions.

A coordinator agent running in dsh often dispatches work to an external, sandboxed, or long-running worker (a container, a remote host, another AgentOS runtime). When the worker finishes, it has to tell the coordinator — without a resident WebSocket and without the coordinator polling.

dsh-tmp-hook gives the agent the request_tmp_hook tool. The call returns a single-use, TTL-bounded HTTPS URL bound to that session. The worker POSTs its result JSON to the URL once; the payload is appended to the requesting session as a user message and the agent wakes immediately. The URL is dead after that: a second POST returns 410.

coordinator ──request_tmp_hook──▶ https://dsh.example.com/api/tmp-hooks/<token>
    │
    │  (hands the URL to the sandboxed worker)
    ▼
worker ──POST {"status":"done","url":"…"}──▶ dsh-tmp-hook ──sessionController.prompt()──▶ coordinator wakes

Install

dsh plugin --profile web add dsh-tmp-hook

dsh plugin add reconciles dsh.profile.bundles for packages that declare dsh.bundle.patch, so the plugin row is registered automatically. Configure it in the profile's own patch layer ($DSH_HOME/profiles/<name>/cordis.patch.yml), which is applied after every bundle layer:

- id: tmp-hook
  config:
    baseUrl: https://dsh.example.com   # optional: overrides the derived origin

baseUrl is the public origin the external worker will call. You usually do not have to set it: a console served behind a reverse proxy must already declare its public domain with --trusted-host <domain> or the browser-trust fence rejects it, and the plugin derives the origin from that same declaration. Set baseUrl explicitly when the deployment declares no port-less domain (an IP-only or loopback-only bind), or to override the derived scheme.

With neither an explicit baseUrl nor a usable declaration, request_tmp_hook fails loudly rather than handing a worker a URL nobody can reach.

To try it from a checkout instead of the registry:

dsh plugin --profile web add /path/to/dsh-tmp-hook

Configuration

key	default	meaning
baseUrl	''	Public origin prepended to every callback URL. Must be an absolute http/https URL; trailing slashes are stripped. Empty means "derive it from the trust fence".
baseUrlScheme	'https'	Scheme assumed for a derived origin. Ignored when baseUrl is set.
pathPrefix	'/api/tmp-hooks'	Path prefix the callback route is registered under. Must be a sub-path; / is rejected.
ttlSeconds	1800	Default token lifetime when the tool call omits ttl_seconds.
minTtlSeconds	30	Lower clamp for a requested ttl_seconds.
maxTtlSeconds	86400	Upper clamp for a requested ttl_seconds.
maxBodyBytes	262144	Maximum accepted callback body. Larger bodies get 413.
sweepIntervalMs	60000	Period between expired-token sweeps. 0 disables the sweeper (records then only die on access).
deliverTimeoutMs	15000	Budget for admitting a delivered message into its session.
allowUnauthenticated	true	Compose with dsh-auth-gate so the callback prefix is reachable without a dsh login session. See below.

Unknown keys and malformed values are rejected at load time: a bad config fails the boot instead of failing the first callback.

Agent tool: request_tmp_hook

The description the model sees states when to reach for the tool: before handing work to anything that finishes after the current turn and cannot be awaited in place — a sandboxed or remote worker, a container or AgentOS task, a CI job, a long-running script, a dispatched agent, or a human replying out of band. It also states when not to: work that completes inside this turn, a result you will poll for anyway, or a channel the worker already holds. The model is told to pass the URL to the worker as part of the task and to record enough detail in purpose to recognize which awaited completion fired.

Arguments (both optional):

• purpose — short description of the work being awaited. Echoed back in the delivered message so a session waiting on several callbacks can tell them apart.
• ttl_seconds — lifetime, clamped to [minTtlSeconds, maxTtlSeconds].

Result (url, token, session_id, expires_at, expires_in_seconds) — hand url to the external worker and nothing else.

HTTP contract

POST <baseUrl><pathPrefix>/<token>. The body is optional and may be anything.

condition	status	body
delivered	200	{"received":true}
unknown token	404	{"received":false,"error":"unknown token"}
TTL elapsed	410	{"received":false,"error":"token expired"}
already delivered	410	{"received":false,"error":"token already used"}
method is not POST	405	{"received":false,"error":"method not allowed"} (Allow: POST)
body over maxBodyBytes	413	{"received":false,"error":"payload too large"}
body could not be read	400	{"received":false,"error":"request aborted"}
session admission failed	502	{"received":false,"error":"delivery failed"}

The response acknowledges admission into the session inbox, not the agent's turn: a slow model never delays the worker.

Any failure before a message was admitted releases the token again (400, 413, 502), so an oversized upload or a transient host error does not burn the worker's one notification. A token is only consumed by a delivery that succeeded.

Payload

The body is not required to be JSON:

• empty body → delivered as (empty);
• valid JSON → delivered pretty-printed, except a bare JSON string ("done"), which is delivered as done;
• anything else → delivered verbatim.

The request's Content-Type is echoed into the delivered message as context. Because callback bodies are frequently not JSON — a build log tail, a worker's stdout, a curl --data-raw string — a body is never rejected for its shape.

Delivered message

The payload arrives in the session as a user message:

[dsh-tmp-hook] One-time callback received at 2026-09-18T11:02:21.513Z.
Token: 523a6527-77f0-44c2-b2fc-db7b9cf36a6a
Purpose: e2e-verify
Content-Type: application/json

Payload:
{
  "status": "done",
  "spec_url": "https://taco.example/spec/42"
}

A non-JSON body renders the same way, with its text in place of the pretty-printed JSON:

[dsh-tmp-hook] One-time callback received at 2026-09-18T11:04:02.171Z.
Token: 6dbe29f9-263e-4234-a1e9-ed1919750f99
Purpose: build finished
Content-Type: text/plain; charset=utf-8

Payload:
build 42 finished
all green

Rendering is bounded (64 KiB) so an oversized payload cannot flood the context window.

Authentication

The callback URL is a capability: the token is a random UUID and is the only credential the external worker needs. Nothing else about the deployment has to be exposed.

By default (allowUnauthenticated: true) the plugin composes with dsh-auth-gate when it is installed: the auth plugin's AuthService.gate field is documented as writable and its guard resolves the gate per request, so the plugin overlays a delegating gate that allows exactly its own path prefix and forwards every other decision to the original gate. Nothing else becomes reachable without a login. The composition is skipped when no auth plugin is present, and restored when the plugin unloads.

Set allowUnauthenticated: false to keep the whole console behind the auth gate — the callback prefix then needs its own ingress rule (an nginx location pointed at the dsh port, or a separate proxy), in which case the auth plugin never sees the callback request.

Rate limiting, TLS, DNS, and reverse-proxy configuration are deployment concerns and are deliberately out of scope for this plugin.

Scope and limits

• Tokens live in the dsh process. A restart invalidates every outstanding callback URL; the worker's POST then returns 404 and the coordinator has to mint a new hook.
• The origin is derived from the deployment's own --trusted-host declarations, never from a request Host header. A Host header is attacker-controlled, so trusting the last-seen one would let anyone who can reach the console poison every future callback URL; an underivable origin fails loudly instead.
• The plugin is host-only: no browser half, no settings page, no UI.
• The plugin imports nothing outside Node's standard library. It composes only the webServer, tools, and sessionController harness services, so it drops into any profile without installing a second copy of the harness packages.

Development

node --test test/*.test.js

The suite covers the token store (single use, expiry, claim/release, sweep), the HTTP handler (every status above, concurrency, payload rendering), config validation, and the tool contract.

The plugin was verified end to end against a live dsh web profile (@deepseek-ai/dsh 0.1.5-rc.1, dsh-auth-gate password mode): the agent called request_tmp_hook, an unauthenticated POST on the returned URL was delivered into the session and produced the agent's next turn, and replay, expiry, 405, 400, 413, and 502 were each exercised against the running server.