@dsh-lattice/adapter-command

DSH Lattice V1 command adapter: safe shell: false execution with persistent or one-shot JSON-lines / JSON-RPC sessions, cancellation, timeouts and output limits.

This package is an independent community adapter, part of the DSH Lattice facade project. It is not affiliated with, endorsed by, or sponsored by DeepSeek AI.

Why it exists

The command adapter turns any executable into a Lattice provider with strict, auditable boundaries. It is the transport seam used by the aggregator's local provider and by the transports' demo engine, and it is safe to point at untrusted tools because:

• No shell, ever. Execution is spawn(executable, args) with an explicit argument vector. shell: true or a command string is rejected at config validation; shell metacharacters in arguments are inert data.
• Deterministic limits. Every run has a timeout (default 120s), per-stream output caps (default 1 MiB) with an explicit truncation marker, and a per-frame cap for persistent protocols.
• Cancellation. Abort signals and per-call timeouts terminate the process tree (process group on POSIX, taskkill /T /F on Windows). Results are never claimed to be exactly-once.
• Environment policy. inherit (default), allowlist, or none.

Modules

Module	Responsibility
config	Strict config validation: executable policy, shell: false enforcement, arg/env validation, defaults
framing	Line framing (one compact JSON frame per \n line) shared by both session protocols — the same framing the DeepSeek Harness SDK protocol uses
runner	One-shot execution: timeout → SIGTERM → SIGKILL, output caps, abort cancellation, process-tree termination
session	Persistent child: request/response correlation, per-call timeouts, cancel notifications, frame caps, bounded stderr, clean teardown
cli	dsh-lattice-command run and dsh-lattice-command serve

Usage

One-shot

import { runOneShot } from "@dsh-lattice/adapter-command";

const result = await runOneShot({
  executable: process.execPath,
  args: ["-e", "console.log('hi')"],
  shell: false,
  mode: "one-shot",
  timeoutMs: 30_000,
  maxOutputBytes: 65_536,
});
// { exitCode: 0, stdout: "hi\n", timedOut: false, truncated: {...} }

Persistent JSON-RPC session

import { CommandSession } from "@dsh-lattice/adapter-command";

const session = new CommandSession({
  executable: "my-agent-server",
  args: ["--stdio"],
  shell: false,
  mode: "persistent",
  protocol: "jsonrpc",
});
session.start();
const result = await session.call("agent/turn", { prompt: "..." }, { timeoutMs: 60_000 });
session.close();

The session protocol speaks one JSON frame per line. jsonrpc frames conform to JSON-RPC 2.0; jsonl frames are { id, method, params }. A cancel notification ({ method: "cancel", params: { id } }) is sent when a call times out or is aborted, so cooperative servers can stop work.

CLI

dsh-lattice-command run --executable node --arg -e --arg "console.log('hi')"
# {"ok":true,"result":{"exitCode":0,"stdout":"hi\n",...}}

dsh-lattice-command serve --executable my-agent-server --arg --stdio --protocol jsonrpc
# proxy: {"jsonrpc":"2.0","id":1,"method":"echo","params":{}} → {"id":1,"result":{...}}

Security

See SECURITY.md. Highlights: shell: false enforced, argument vector only, timeout + output + frame caps, process-tree termination, env allowlist.

Platform caveat (Windows): libuv merges the provided env into the parent environment when spawning on Windows, so allowlist/none overlay their keys but cannot remove inherited keys. On POSIX the environment is replaced exactly. Use POSIX or container isolation for strict environment sandboxing.

Upstream compatibility

The line framing mirrors the DeepSeek Harness SDK protocol transport (JSON-RPC 2.0, one compact JSON frame per \n-terminated line; malformed lines ignored — upstream packages/sdk/protocol/README.md). This is a design reference only; no upstream code is vendored.

Development

pnpm install
pnpm build && pnpm typecheck && pnpm test && pnpm coverage

License

Apache-2.0. See LICENSE and NOTICE.