@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

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.