@nexus-aethra/dsh-box-sandbox 0.1.0

package/dist/rpc.d.mts

@@ -0,0 +1,139 @@
+//#region src/rpc.d.ts
+/**
+ * dshbox daemon client: discovery record + loopback JSON-RPC transport.
+ *
+ * dshboxd binds a DYNAMIC loopback port and authenticates every call with a
+ * token minted at launch. Both facts live in a discovery record the daemon
+ * writes atomically to <config-dir>/server/discovery.json and removes on
+ * shutdown. Nothing here is hardcoded: the record is re-read at call time, so
+ * a daemon restart (new port, new token) is transparent to callers instead
+ * of leaving them holding a stale endpoint.
+ *
+ * Wire contract, verified against dshboxd/src/main.rs:
+ *
+ * - POST /rpc is matched EXACTLY (path != "/rpc" -> 404), so the path
+ *   carries no query string.
+ * - The token travels in the JSON BODY, not in an Authorization header. The
+ *   Rust client sends a Bearer header too, but the daemon never reads it --
+ *   sending it is harmless, relying on it silently fails.
+ * - Params are FLATTENED into the top-level request object alongside token
+ *   and method; there is no nested params field.
+ * - Replies are {ok: true, result: ...} for sync methods and
+ *   {ok: true, task: ...} for async ones, or {ok: false, error: ...}.
+ *   The daemon closes the connection after each frame.
+ * - GET /events?token=... is the SSE stream, which takes the token from the
+ *   query string instead.
+ *
+ * @module dsh-box-sandbox/rpc
+ */
+/**
+ * The launch record dshboxd publishes while it is alive.
+ *
+ * 'endpoint' is a legacy Unix-domain-socket field kept only so that stale
+ * records from older daemon builds still deserialize; the daemon never
+ * writes it, so this interface does not model it.
+ */
+interface Discovery {
+  /** Bearer-equivalent secret minted at launch; required on every call. */
+  token: string;
+  /** Owning process id, for liveness checks and diagnostics. */
+  pid: number;
+  /** Unix seconds at launch; a client can use it to spot a stale record. */
+  startedAt: number;
+  /** Dynamic loopback port the daemon is listening on. */
+  port: number;
+}
+/** Constructor options for DshboxRpc. */
+interface DshboxRpcOptions {
+  /**
+   * Directory holding server/discovery.json. Defaults to DSHBOX_CONFIG_DIR
+   * when set, otherwise ~/.dsh-box -- the same precedence that
+   * box_foundation::config_path applies on the Rust side.
+   */
+  configDir?: string;
+  /** Per-attempt request timeout in milliseconds. Default 30000. */
+  timeoutMs?: number;
+}
+/**
+ * Raised when no usable daemon can be reached: the discovery record is
+ * absent, unreadable, or describes an endpoint that refuses connections.
+ *
+ * It is distinct from a daemon-reported failure -- those come back as a
+ * plain Error carrying the daemon's own message, because the daemon was
+ * reached and answered.
+ */
+declare class DshboxUnavailableError extends Error {
+  readonly name = "DshboxUnavailableError";
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Resolve the config directory, honouring DSHBOX_CONFIG_DIR.
+ *
+ * An empty override counts as absent: the plugin config defaults
+ * configDir to the empty string to mean "resolve it the way the daemon
+ * does", and treating that as a real path would look for discovery.json
+ * relative to the process working directory.
+ */
+declare function resolveConfigDir(override?: string): string;
+/** Absolute path of the discovery record for a config directory. */
+declare function discoveryPath(configDir?: string): string;
+/**
+ * Read the discovery record, or null when the daemon is not running.
+ *
+ * A missing file and a malformed one are treated the same way on purpose:
+ * both mean "there is no endpoint to talk to", and the caller surfaces one
+ * actionable message instead of two different failure modes.
+ */
+declare function readDiscovery(configDir?: string): Discovery | null;
+/** Transport for a single discovered daemon. */
+declare class DshboxRpc {
+  readonly configDir: string;
+  private readonly timeoutMs;
+  constructor(options?: DshboxRpcOptions);
+  /**
+   * Return a usable record or explain why there is none.
+   *
+   * The message names the exact path looked at: "dshbox is not running" is
+   * the most common first-run failure, and the user needs to know WHICH
+   * profile directory was consulted before they start the app.
+   */
+  discovery(): Discovery;
+  /** Loopback base URL for the currently discovered endpoint. */
+  endpointUrl(record: Discovery): string;
+  /** SSE stream URL. The token goes in the query string, not a header. */
+  eventsUrl(record: Discovery): string;
+  private send;
+  /**
+   * Invoke one daemon method.
+   *
+   * A transport failure is retried exactly once against a freshly read
+   * discovery record. That single retry is what absorbs a daemon restart:
+   * the first attempt uses the port from the old record, fails to connect,
+   * and the second uses the new one. Failures the daemon itself reports are
+   * never retried -- they are answers, not outages.
+   */
+  call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  /** Liveness probe. Resolves to the daemon's own status frame. */
+  ping(): Promise<{
+    pid: number;
+    status: string;
+    runtime: string;
+    startedAt: number;
+  }>;
+}
+/**
+ * Configuration for the lazily created singleton. Kept structural so rpc.ts
+ * does not have to import the plugin entry that owns the validated Config.
+ */
+interface RpcConfig {
+  configDir?: string;
+  timeoutMs?: number;
+}
+/** The active client, constructed from the given config on first use. */
+declare function getRpc(config?: RpcConfig): DshboxRpc;
+/** Drop the singleton so the next getRpc() picks up fresh config. */
+declare function resetRpc(): void;
+//#endregion
+export { Discovery, DshboxRpc, DshboxRpcOptions, DshboxUnavailableError, RpcConfig, discoveryPath, getRpc, readDiscovery, resetRpc, resolveConfigDir };

package/dist/rpc.mjs

@@ -0,0 +1,186 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+//#region src/rpc.ts
+/**
+* dshbox daemon client: discovery record + loopback JSON-RPC transport.
+*
+* dshboxd binds a DYNAMIC loopback port and authenticates every call with a
+* token minted at launch. Both facts live in a discovery record the daemon
+* writes atomically to <config-dir>/server/discovery.json and removes on
+* shutdown. Nothing here is hardcoded: the record is re-read at call time, so
+* a daemon restart (new port, new token) is transparent to callers instead
+* of leaving them holding a stale endpoint.
+*
+* Wire contract, verified against dshboxd/src/main.rs:
+*
+* - POST /rpc is matched EXACTLY (path != "/rpc" -> 404), so the path
+*   carries no query string.
+* - The token travels in the JSON BODY, not in an Authorization header. The
+*   Rust client sends a Bearer header too, but the daemon never reads it --
+*   sending it is harmless, relying on it silently fails.
+* - Params are FLATTENED into the top-level request object alongside token
+*   and method; there is no nested params field.
+* - Replies are {ok: true, result: ...} for sync methods and
+*   {ok: true, task: ...} for async ones, or {ok: false, error: ...}.
+*   The daemon closes the connection after each frame.
+* - GET /events?token=... is the SSE stream, which takes the token from the
+*   query string instead.
+*
+* @module dsh-box-sandbox/rpc
+*/
+/**
+* Raised when no usable daemon can be reached: the discovery record is
+* absent, unreadable, or describes an endpoint that refuses connections.
+*
+* It is distinct from a daemon-reported failure -- those come back as a
+* plain Error carrying the daemon's own message, because the daemon was
+* reached and answered.
+*/
+var DshboxUnavailableError = class extends Error {
+	name = "DshboxUnavailableError";
+	constructor(message, options) {
+		super(message, options);
+	}
+};
+/**
+* Resolve the config directory, honouring DSHBOX_CONFIG_DIR.
+*
+* An empty override counts as absent: the plugin config defaults
+* configDir to the empty string to mean "resolve it the way the daemon
+* does", and treating that as a real path would look for discovery.json
+* relative to the process working directory.
+*/
+function resolveConfigDir(override) {
+	if (override !== void 0 && override !== "") return override;
+	return process.env.DSHBOX_CONFIG_DIR ?? join(homedir(), ".dsh-box");
+}
+/** Absolute path of the discovery record for a config directory. */
+function discoveryPath(configDir) {
+	return join(resolveConfigDir(configDir), "server", "discovery.json");
+}
+function isDiscovery(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const d = value;
+	return typeof d.token === "string" && d.token.length > 0 && typeof d.port === "number" && Number.isInteger(d.port) && d.port > 0 && d.port <= 65535 && typeof d.pid === "number" && typeof d.startedAt === "number";
+}
+/**
+* Read the discovery record, or null when the daemon is not running.
+*
+* A missing file and a malformed one are treated the same way on purpose:
+* both mean "there is no endpoint to talk to", and the caller surfaces one
+* actionable message instead of two different failure modes.
+*/
+function readDiscovery(configDir) {
+	let text;
+	try {
+		text = readFileSync(discoveryPath(configDir), "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(text);
+		return isDiscovery(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/** True when a failure means "the discovery record is probably stale". */
+function isStaleEndpoint(error) {
+	if (error instanceof DshboxUnavailableError) return true;
+	if (!(error instanceof Error)) return false;
+	const code = error.cause?.code;
+	return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EPIPE";
+}
+/** Transport for a single discovered daemon. */
+var DshboxRpc = class {
+	configDir;
+	timeoutMs;
+	constructor(options = {}) {
+		this.configDir = resolveConfigDir(options.configDir);
+		this.timeoutMs = options.timeoutMs ?? 3e4;
+	}
+	/**
+	* Return a usable record or explain why there is none.
+	*
+	* The message names the exact path looked at: "dshbox is not running" is
+	* the most common first-run failure, and the user needs to know WHICH
+	* profile directory was consulted before they start the app.
+	*/
+	discovery() {
+		const path = discoveryPath(this.configDir);
+		const record = readDiscovery(this.configDir);
+		if (record === null) throw new DshboxUnavailableError("dshbox daemon is not running (no usable discovery record at " + path + "); start DSH Box first");
+		return record;
+	}
+	/** Loopback base URL for the currently discovered endpoint. */
+	endpointUrl(record) {
+		return "http://127.0.0.1:" + record.port;
+	}
+	/** SSE stream URL. The token goes in the query string, not a header. */
+	eventsUrl(record) {
+		return this.endpointUrl(record) + "/events?token=" + encodeURIComponent(record.token);
+	}
+	async send(record, method, params) {
+		const response = await fetch(this.endpointUrl(record) + "/rpc", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				token: record.token,
+				method,
+				...params
+			}),
+			signal: AbortSignal.timeout(this.timeoutMs)
+		});
+		if (response.status === 401) throw new DshboxUnavailableError("dshbox daemon rejected the discovery token (it may have restarted)");
+		if (!response.ok) throw new Error("dshbox daemon returned HTTP " + response.status + " for " + method);
+		const frame = await response.json();
+		if (!frame.ok) throw new Error(frame.error ?? "dshbox daemon reported an unknown error for " + method);
+		return frame.result ?? frame.task ?? null;
+	}
+	/**
+	* Invoke one daemon method.
+	*
+	* A transport failure is retried exactly once against a freshly read
+	* discovery record. That single retry is what absorbs a daemon restart:
+	* the first attempt uses the port from the old record, fails to connect,
+	* and the second uses the new one. Failures the daemon itself reports are
+	* never retried -- they are answers, not outages.
+	*/
+	async call(method, params) {
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const record = this.discovery();
+			try {
+				return await this.send(record, method, params);
+			} catch (error) {
+				if (attempt === 0 && isStaleEndpoint(error)) continue;
+				throw error;
+			}
+		}
+		/* c8 ignore next 2 */
+		throw new DshboxUnavailableError("dshbox daemon unreachable for " + method);
+	}
+	/** Liveness probe. Resolves to the daemon's own status frame. */
+	ping() {
+		return this.call("ping");
+	}
+};
+/**
+* One daemon per host, so the client is a module-level singleton.
+*
+* It is created lazily and torn down by resetRpc() on remount: cordis
+* re-applies a plugin whenever its config changes, and a stale client would
+* keep pointing at the previous config directory.
+*/
+let current = null;
+/** The active client, constructed from the given config on first use. */
+function getRpc(config) {
+	if (current === null) current = new DshboxRpc(config ?? {});
+	return current;
+}
+/** Drop the singleton so the next getRpc() picks up fresh config. */
+function resetRpc() {
+	current = null;
+}
+//#endregion
+export { DshboxRpc, DshboxUnavailableError, discoveryPath, getRpc, readDiscovery, resetRpc, resolveConfigDir };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nexus-aethra/dsh-box-sandbox",
+  "version": "0.1.0",
+  "description": "Host-side bridge from a DSH session to the DSH Box daemon: typed box_* tools an agent can call without a shell.",
+  "keywords": [
+    "dsh",
+    "dsh-box",
+    "cordis",
+    "agent",
+    "box",
+    "tools"
+  ],
+  "homepage": "https://github.com/aethra-tech/DSHBox/tree/main/plugins/dsh-box-sandbox",
+  "bugs": {
+    "url": "https://github.com/aethra-tech/DSHBox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethra-tech/DSHBox.git",
+    "directory": "plugins/dsh-box-sandbox"
+  },
+  "author": "Nexus Aethra",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.mts",
+      "default": "./dist/rpc.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}