@khorsheed/dsh-local-agent 0.1.0-rc.6

package/lib/invariant.js

@@ -0,0 +1,85 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@khorsheed/dsh-local-agent`.
+* @module @khorsheed/dsh-local-agent/invariant
+*/
+const PACKAGE_NAME = "@khorsheed/dsh-local-agent";
+/** Cordis companion plugin name. */
+const name = "local-agent-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/u;
+/**
+* Audit the harness registry lifecycle: a registered harness must carry a
+* valid, unique command-prefix name, a home environment variable, and a
+* records adapter, and a removed name must have been registered first.
+*/
+function auditLifecycle(ctx, fail) {
+	const known = /* @__PURE__ */ new Set();
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName === "localAgent/harness-added") {
+			const harness = args[0];
+			if (!NAME_PATTERN.test(harness.name)) fail(`localAgent/harness-added names a harness with invalid name ${JSON.stringify(harness.name)}`);
+			if (known.has(harness.name)) fail(`localAgent/harness-added repeats name ${JSON.stringify(harness.name)}`);
+			if (harness.homeEnvVar.length === 0) fail(`localAgent/harness-added for ${harness.name} has an empty homeEnvVar`);
+			known.add(harness.name);
+			return;
+		}
+		if (eventName !== "localAgent/harness-removed") return;
+		const name = args[0];
+		if (!known.delete(name)) fail(`localAgent/harness-removed names unknown harness ${JSON.stringify(name)}`);
+	}, { global: true });
+}
+/**
+* Cross-check delegation claims against the mounted subagent providers after
+* the composition settles. A harness whose {@link LocalAgentHarness.delegationProvider}
+* names a provider the tree does not mount means "identity present, delegation
+* 404" — a typo in either the record or the bundle patch — and fails loud.
+* A composition without the subagent seam (record-and-login only) skips the
+* check; so does a harness without a delegation provider.
+*/
+async function auditDelegationClaims(ctx, fail) {
+	await ctx.get("loader")?.await();
+	const subagents = ctx.get("subagents");
+	if (subagents === void 0) return;
+	const registry = ctx.get("localAgent");
+	if (registry === void 0) return;
+	for (const name of registry.list()) {
+		const providerName = registry.get(name)?.delegationProvider;
+		if (providerName === void 0) continue;
+		if (subagents.getProvider(providerName) === void 0) fail(`local-agent harness ${name} declares delegation provider ${JSON.stringify(providerName)} which is not mounted`);
+	}
+}
+/**
+* Audit the delegation registry: a recorded delegation must name a mounted
+* subagent provider (the record is only useful when a resume round can route
+* back through the same provider). Mirrors the harness-level delegation-claim
+* check with the same "identity present, delegation 404" rationale — a record
+* whose provider the tree does not mount means a provider rename left a stale
+* mapping that would fail loud on the first resume attempt.
+*/
+async function auditDelegationProviders(ctx, fail) {
+	await ctx.get("loader")?.await();
+	const subagents = ctx.get("subagents");
+	if (subagents === void 0) return;
+	const registry = ctx.get("localAgent");
+	if (registry === void 0) return;
+	for (const record of registry.listDelegations()) if (subagents.getProvider(record.provider) === void 0) fail(`local-agent delegation for child session ${record.childSessionId} records provider ${JSON.stringify(record.provider)} which is not mounted`);
+}
+/**
+* Install the package's checks.
+* @param ctx - child context owned by this invariant registration.
+* @param fail - reporter bound to the registering package name.
+*/
+const install = Object.assign((ctx, fail) => {
+	auditLifecycle(ctx, fail);
+	return Promise.all([auditDelegationClaims(ctx, fail), auditDelegationProviders(ctx, fail)]).then(() => {});
+}, {});
+/**
+* Register this package's invariant companion.
+* @param ctx - plugin context carrying the invariant registry.
+* @returns the installed registration's disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/member-bridge.js

@@ -0,0 +1,298 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { connect } from "node:net";
+import { createInterface } from "node:readline";
+//#region lib/types/types.js
+/** Environment variable carrying the member-bridge socket path (spawn env → bridge). */
+const MEMBER_BRIDGE_SOCKET_ENV = "DSH_MEMBER_SOCKET";
+/** Environment variable carrying the per-run member-bridge token. */
+const MEMBER_BRIDGE_TOKEN_ENV = "DSH_MEMBER_TOKEN";
+//#endregion
+//#region lib/types/member-bridge.js
+/**
+* Member bridge: a minimal standalone MCP server (stdio, newline-delimited
+* JSON-RPC) exposing member messaging and room coordination tools to the CLI
+* member that spawned it. Each call is forwarded to the host's member-channel
+* listener over the loopback socket named by `DSH_MEMBER_SOCKET`,
+* authenticated by the per-run token in `DSH_MEMBER_TOKEN`; the host's
+* receipt is the tool result verbatim.
+*
+* The process is dependency-free (node builtins only) because the CLI spawns
+* it bare: `node <this file>`, with the socket path and token in its
+* environment (written into the CLI's scoped MCP config by the provider).
+* Covers the MCP handshake subset a client needs: `initialize`,
+* `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
+* @module @khorsheed/dsh-local-agent/member-bridge
+*/
+/** The one tool this server exposes. */
+const MEMBER_MESSAGE_TOOL = "member_message";
+const TOOL_DESCRIPTION = [
+	"Notify another CLI member of this room/session group (member-to-member message).",
+	"`to` is the target member's dsh child session id (or a member name when a room manages the group).",
+	"The delivery receipt is returned verbatim: sent / pending-confirm / busy / an error reason."
+].join(" ");
+const TOOL_SCHEMA = {
+	type: "object",
+	properties: {
+		to: {
+			type: "string",
+			description: "The target member's child session id (or room-roster name)."
+		},
+		text: {
+			type: "string",
+			description: "The notification text, delivered with your provenance."
+		}
+	},
+	required: ["to", "text"],
+	additionalProperties: false
+};
+const ROOM_TOOLS = [
+	{
+		name: "room_plan",
+		description: "Manage a formal goal with stages, dependent tasks and evidence review. Read room_read for plan state and the command contract. Ordinary small work uses room_message. Workers may submit only their own current attempt.",
+		inputSchema: {
+			type: "object",
+			properties: { command: {
+				type: "string",
+				description: "JSON command with action, requestId and expectedRevision; see room_read planCommands."
+			} },
+			required: ["command"],
+			additionalProperties: false
+		}
+	},
+	{
+		name: "room_read",
+		description: "Read your room roster, coordinator, deliveries, recent outcomes and available harness providers. Identity comes from the host.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		}
+	},
+	{
+		name: "room_invite",
+		description: "Coordinator only: invite a member. An optional firstTask starts in the background and returns its result to you automatically.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				provider: { type: "string" },
+				name: { type: "string" },
+				instructions: { type: "string" },
+				cwd: { type: "string" },
+				model: { type: "string" },
+				firstTask: { type: "string" }
+			},
+			required: ["provider", "name"],
+			additionalProperties: false
+		}
+	},
+	{
+		name: "room_message",
+		description: "Coordinator only: dispatch background work to a room member by name. Returns acceptance immediately; completion arrives as a correlated report. Do not poll.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				member: { type: "string" },
+				text: { type: "string" }
+			},
+			required: ["member", "text"],
+			additionalProperties: false
+		}
+	}
+];
+async function callRoomCommand(env, name, args) {
+	if (env.socket === void 0 || env.token === void 0) return toolText("member channel is not configured for this run", true);
+	if (args === null || typeof args !== "object" || Array.isArray(args)) return toolText("Room tool arguments must be an object", true);
+	try {
+		const outcome = await callHost(env.socket, {
+			token: env.token,
+			command: {
+				name,
+				arguments: args
+			}
+		});
+		return toolText(outcome.ok ? outcome.receipt ?? "accepted" : outcome.error ?? "Room command rejected", !outcome.ok);
+	} catch (error) {
+		return toolText(`Room command unavailable: ${String(error)}`, true);
+	}
+}
+/** One socket round trip: send the request line, read the one-line response. */
+function callHost(socket, payload) {
+	return new Promise((resolve, reject) => {
+		const connection = connect(socket);
+		let buffer = "";
+		connection.on("connect", () => {
+			connection.write(`${JSON.stringify(payload)}\n`);
+		});
+		connection.on("data", (chunk) => {
+			buffer += chunk.toString();
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			connection.end();
+			try {
+				resolve(JSON.parse(buffer.slice(0, newline)));
+			} catch (error) {
+				reject(error instanceof Error ? error : new Error(String(error)));
+			}
+		});
+		connection.on("error", reject);
+	});
+}
+/** A successful MCP tool result carrying the receipt text. */
+function toolText(text, isError = false) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError
+	};
+}
+/**
+* Handle one `member_message` tool call: forward to the host listener and map
+* the outcome to a tool result. Channel failures (missing env, unreachable
+* listener, rejected token) are tool errors; delivery verdicts are text.
+* @param env - the bridge's environment (socket, token).
+* @param args - the tool arguments (`to`, `text`).
+* @returns the MCP tool result object.
+*/
+async function callMemberMessage(env, args) {
+	if (env.socket === void 0 || env.token === void 0) return toolText("member channel is not configured for this run (missing socket/token environment)", true);
+	if (typeof args.to !== "string" || typeof args.text !== "string") return toolText("member_message requires string arguments `to` and `text`", true);
+	try {
+		const outcome = await callHost(env.socket, {
+			token: env.token,
+			to: args.to,
+			text: args.text
+		});
+		if (outcome.ok) return toolText(outcome.receipt ?? "sent");
+		return toolText(outcome.error ?? "member channel rejected the message", true);
+	} catch (error) {
+		return toolText(`member channel unavailable: ${error instanceof Error ? error.message : String(error)}`, true);
+	}
+}
+/**
+* Run the stdio JSON-RPC loop over the given streams (injectable for tests).
+* Unknown methods with an id get a MethodNotFound error; notifications are
+* ignored. Never throws — a malformed line is answered with a parse error and
+* the loop continues.
+* @param env - the bridge's environment.
+* @param input - the stdin side.
+* @param output - the stdout side.
+*/
+function serveMemberBridge(env, input, output) {
+	const write = (message) => {
+		output.write(`${JSON.stringify(message)}\n`);
+	};
+	createInterface({
+		input,
+		terminal: false
+	}).on("line", (line) => {
+		if (line.trim() === "") return;
+		let request;
+		try {
+			request = JSON.parse(line);
+		} catch {
+			write({
+				jsonrpc: "2.0",
+				id: null,
+				error: {
+					code: -32700,
+					message: "parse error"
+				}
+			});
+			return;
+		}
+		const id = request.id;
+		switch (request.method) {
+			case "initialize": {
+				const params = request.params;
+				write({
+					jsonrpc: "2.0",
+					id: id ?? null,
+					result: {
+						protocolVersion: params?.protocolVersion ?? "2024-11-05",
+						capabilities: { tools: {} },
+						serverInfo: {
+							name: "dsh-member-bridge",
+							version: "0.1.0"
+						}
+					}
+				});
+				return;
+			}
+			case "ping":
+				write({
+					jsonrpc: "2.0",
+					id: id ?? null,
+					result: {}
+				});
+				return;
+			case "tools/list":
+				write({
+					jsonrpc: "2.0",
+					id: id ?? null,
+					result: { tools: [{
+						name: MEMBER_MESSAGE_TOOL,
+						description: TOOL_DESCRIPTION,
+						inputSchema: TOOL_SCHEMA
+					}, ...ROOM_TOOLS] }
+				});
+				return;
+			case "tools/call": {
+				const params = request.params;
+				if (ROOM_TOOLS.some((tool) => tool.name === params?.name)) {
+					callRoomCommand(env, params.name, params.arguments ?? {}).then((result) => write({
+						jsonrpc: "2.0",
+						id: id ?? null,
+						result
+					}));
+					return;
+				}
+				if (params?.name !== "member_message") {
+					write({
+						jsonrpc: "2.0",
+						id: id ?? null,
+						error: {
+							code: -32602,
+							message: `unknown tool ${String(params?.name)}`
+						}
+					});
+					return;
+				}
+				callMemberMessage(env, params.arguments ?? {}).then((result) => {
+					write({
+						jsonrpc: "2.0",
+						id: id ?? null,
+						result
+					});
+				});
+				return;
+			}
+			default: if (id !== void 0) write({
+				jsonrpc: "2.0",
+				id,
+				error: {
+					code: -32601,
+					message: `method not found: ${String(request.method)}`
+				}
+			});
+		}
+	});
+}
+/** True when this file is the process entry (`node member-bridge.js`). */
+function isMain() {
+	const entry = process.argv[1];
+	if (entry === void 0) return false;
+	try {
+		return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+	} catch {
+		return false;
+	}
+}
+if (isMain()) serveMemberBridge({
+	socket: process.env[MEMBER_BRIDGE_SOCKET_ENV],
+	token: process.env[MEMBER_BRIDGE_TOKEN_ENV]
+}, process.stdin, process.stdout);
+//#endregion
+export { MEMBER_MESSAGE_TOOL, callMemberMessage, callRoomCommand, serveMemberBridge };

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown