Skip to main content
U

dsh-nodes

unera/dsh-nodes

Run commands on remote machines from a DSH session: sandboxed (ro/rw/full), policy-controlled, audited

Install

dsh plugin --profile web add github:unera/dsh-nodes

README

dsh-nodes

Remote execution for DSH: nodes anywhere (a laptop, a router, a CI box) announce their own APIs, and the model calls their methods through a small set of tools.

The server keeps a registry of nodes and a catalog of APIs, so adding a node does not cost context: the model sees four tools, not every method of every machine.

nodes_list()      → nodes: aliases, online, uptime, which APIs they hold
nodes_catalog()   → catalog: id, name, methods
nodes_api(api)    → methods of one API with their argument schemas
nodes_call(node, api, method, data, timeout?, sandbox?)

The pair is two packages: this plugin (server side) and a client that runs on the node. Two clients are shipped and both speak the same protocol — pick whichever machine you want to reach:

ClientWhat it runs onWhere it lives
@dr-co/dsh-node-clienta desktop or a server: Linux, macOS, systemd, bwrap sandbox, shell jobs, file transfers, approval dialogsGitHub · npm
dshnc for Androida phone: shell with the app's own permissions, files, camera, apps, notifications, and questions to the person (dialog.ask)GitHub

Install the desktop one with npm install -g @dr-co/dsh-node-client; the Android one is an APK from the releases page of its repository.

How it works

model ──nodes_call──▶ plugin ──queue──▶ client on the node ──▶ sandbox ──▶ shell
                        ▲                     │
                        └──── result ◀────────┘
  • The command is handed out once. GET /v1/commands takes a batch from the head of the queue and marks it processing. There is no lease and no redelivery: taken means either executed or attempted. A node that dies mid command gets its command closed as lost after the timeout, so the model gets an answer instead of silence.
  • Results are accepted late. A model that already saw a timeout does not break anything.
  • Presence rides a WebSocket (/v1/ws) and speaks exactly two frames each way: the client sends state ("I am waiting, generation is this") and ping, the server answers state ("there is work, go fetch it") and pong. The server generation epoch is the identity token of a connection, and the client's own client_epoch keeps an older instance of a node from pushing out a newer one. Only announce with epoch: null closes in-flight commands. Command data always travels over HTTP.

Install

The released package is on npm (npm view @dr-co/dsh-nodes version — 0.3.25 at the time of writing, and this checkout is ahead of it; CHANGELOG.md lists what came after):

npm install -g @dr-co/dsh-nodes

To install exactly this checkout instead:

npm install /path/to/dsh-nodes

Default config ships in cordis.patch.yml. State lives in $DSH_HOME/storages/dsh-nodes.sqlite; the admin token sits next to it in dsh-nodes-admin.token (0600) unless configured.

Connect a node

Open /api/dsh-nodes/admin (behind the DSH login) and generate a pairing link https://host/dsh-nodes/pair?v=<code>, valid for 10 minutes. On the node:

dshnc connect 'https://host/dsh-nodes/pair?v=<code>'
dshnc daemon

The client exchanges the code for a token itself — nothing to approve in the panel. The code is stored hashed only: reuse gives 409, an expired code 410.

What a device sends to the host

The full vocabulary — command, voice, new-session, voice-warmup, notify-button, notify-session, bug-report, form — lives in docs/device-events.md, and the same list is machine-readable in x-device-events of the schema. A test compares the two, so neither can quietly fall behind. The reference is the single source of truth for messages a device starts itself; everything else here is a command the host sends.

Calling a node from another plugin

The tools above are for the model. A plugin that needs to ask a device something gets the nodes service instead, which is the same queue and the same audit trail without the approval dialogue a tool call goes through:

const nodes = ctx.get('nodes')            // or declare `nodes` in your own inject map
const answer = await nodes.call('phone', 'voice', 'record', { mode: 'ptt' }, { timeout: 45 })
if (answer.status === 'ok') use(answer.payload)

call(node, api, method, data, options) accepts an alias or a node id, an API name or id, checks the arguments against the declared schema, and returns {status, code, message, results, payload} — payload being the parsed JSON of the device's last result block.

devices() answers the roster without touching a single device — a settings page must not wait for hardware that is asleep:

nodes.devices()
// [{ id: 19, name: 'Телефон', alias: 'A059P', online: true, version: 'android-0.10.22' }]

Audio pushed by a device

POST /v1/upload-file?type=voice&filetype=wav&id=take-1
authorization: Bearer <node token>
x-seconds: 4.8            (optional)
<wav bytes>
→ 202 {"accepted":true,"id":"take-1","path":"…/cache/voice/incoming/take-1.wav","bytes":N,"seconds":4.8}

Optional measurement headers, all epoch milliseconds: x-record-start, x-record-stop, x-sent-at (a nonsense value is ignored, never a reason to refuse a recording). They arrive in the event as at: {recordStart, recordStop, sentAt, receivedAt}, where receivedAt is stamped by the server before the first byte.

synth=device|host tells the host which side speaks the answer: device (default, and what a typo becomes) means the phone reads the text itself and the host does no synthesis at all; host means the host renders the audio and the device only plays it.

No seq, no command: the device pushes, the host receives. filetype is one of wav ogg opus mp3 m4a flac; the path is chosen by the server, never by the device; the write is atomic (.inprogress → rename) and bounded by maxTransferBytes. After the file is stored the host emits dsh-nodes/voice {node, nodeName, id, path, bytes, seconds}.

Event types

POST /v1/events names what happened in type — notify-button, notify-session, new-session, voice-warmup, bug-report, or form (reserved, answered 501). Anything else is 400 bad_type. Only the first two are delivered into a session: a warm-up, a report about the app and a request for a new conversation are facts for the plugin that listens, and nothing reaches a session with them. Each type, its fields and its answer are in docs/device-events.md.

An event without type (and the old type: "notify") is still read by its fields and logged once as a guess: an installed app cannot be updated in the same minute as the server.

Devices can also ask the host for attention without producing a message: POST /v1/events with { "voice": { "want": "record", "mode": "ptt" } } and no type answers 202 and emits dsh-nodes/voice-want for whoever listens. Nothing is delivered to a session, and no session is required. The shape is deprecated but supported — see the same reference.

Are events allowed at all?

Events are a privilege the owner grants, not something a paired device gets for free. The node row carries events_enabled INTEGER NOT NULL DEFAULT 0: a node that was never allowed sends nothing. The switch is on the node's page in the panel ("Events allowed"), and the admin API sets the same flag either as {"op": "update", "id": N, "body": {"events_enabled": true}} or as {"op": "events", "id": N, "body": {"enabled": true}}; the flag is also read in nodeView as eventsEnabled.

Off means off for the event routes only. POST /v1/events answers 403 events_disabled for notify-button, notify-session, new-session, voice-warmup, bug-report and the legacy voice.want. Everything else keeps working: the socket stays up, GET /v1/state and GET /v1/commands serve the node, commands run, and a recording still arrives at POST /v1/upload-file?type=voice — the microphone is not the switch, and the panel says so next to the checkbox.

Upgrading from 0.3.x turns events off on every existing node, because that is the default. The device is not broken: it stays connected and commands go through, only the event routes answer 403 until the owner flips the switch. A voice plugin therefore stops receiving voice-warmup and new-session — the first thing to check after an upgrade.

Access control on a node

The owner of the machine decides how much the server may do there. Three values, set on the node (dshnc policy), not on the server:

valuemeaning
basemode a command starts in; a confirmed command is not lowered by it
maxabsolute ceiling; nothing goes wider, not even with approval
approverwho may answer a question about a wider mode: local, server, none

Modes are ro (read only), rw (write inside allowed roots), full (no sandbox). If a command is denied and approver is not none, the node is asked in its own way — a dialog on that machine (zenity and friends), or the DSH approval dialog on the server side.

approver: local is a promise: the node must announce the session.approve method. The server checks this and falls back to none, otherwise it would queue an approval command the node cannot execute.

Who is in charge. Three of these four values (access, base, allowEscalation, approver) can be written by two sides: the owner in the admin panel, and the node in its own PUT /v1/announce. The owner wins. An announcement can narrow those rights and never widen them — a node whose panel says ro stays ro even if it announces full, and allowEscalation: false is not switched back on. What was refused comes back in the answer's warnings (and into the log as policy-narrowed), so a client author sees it instead of guessing. Only a field the owner has never set (none, or empty) is filled in by the node itself.

Approval covers exactly one command and one step (ro → rw → full, up to two steps). The command is then re-run from the beginning, which the dialog says explicitly: a command that already did half the work before the denial will do that half again.

Audit

Two places, two purposes:

  • the journal — one line per event with a syslog priority (<6> info, <4> warning), rotated by systemd. Long memory: journalctl --user -u dsh-server | grep 'audit:';
  • the database — a ring buffer (2000 rows, 7 days, command text up to 1000 chars) that feeds the admin panel. Bounded on purpose: an audit nobody reads must not grow to gigabytes.

Three kinds of events: exec (ran, in full or with approval), denied (the kernel refused) and approve (what the human answered).

Uptime

The client sends uptimeSeconds — time since its process started. The server converts it to its own clock at the moment of the message and only adds its own delta afterwards, so a node with a wrong clock cannot produce a negative or absurd uptime.

Routes

Public: POST /v1/enroll, GET /v1/enroll/{uuid}, POST /v1/pair. Node (Bearer): PUT /v1/announce, GET /v1/state, GET /v1/commands, POST /v1/commands/{seq}/result, GET /v1/ws (upgrade), POST /v1/events, POST /v1/upload-file, POST /v1/download-file (the last three are the device side: events a device starts, and files in both directions). There is no /v1/catalog route: the API catalog is read through the admin side. Admin: /api/dsh-nodes/* — private, behind the DSH session.

The client-facing protocol is in spec/openapi.yaml (English, like this file). It is the source of truth; the Russian translation in docs/openapi.ru.yaml lags behind it (it does not describe the device routes yet), so a client author should read the English one. The admin API is deliberately not in the spec: it is private and no third-party client should depend on it.

Development

node --test test/*.test.mjs

Tests start a real http.createServer with the plugin handler — no cordis, no mocks of the protocol.

Design notes and open questions live in docs/plan.md (Russian, as are the other documents in docs/).

Related plugins