@khorsheed/dsh-local-agent 0.2.0-rc.1 → 0.2.0

package/lib/member-bridge.js

@@ -21,15 +21,22 @@ const MEMBER_BRIDGE_TOKEN_ENV = "DSH_MEMBER_TOKEN";
 * 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`.
+* `notifications/initialized`, `ping`, `tools/list`, `tools/call`. A member
+* with a mode also gets that preset's plugin tools: `tools/list` asks the
+* host for them and any other tool name is forwarded as a mode-tool 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."
+	"Send a message to another member of this room/session group.",
+	"`to` is the member name (or its dsh child session id).",
+	"kind \"task\" (default) hands it work: in a room, its final reply is reported back to you automatically, citing the message id — do not poll.",
+	"kind \"notify\" is an FYI and is never reported back. Pass inReplyTo (e.g. m12) when answering a message.",
+	"Never sleep or poll for the result (room_read included): end your turn, the report arrives on its own.",
+	"Writing \"@name\" in a reply reaches nobody; only this tool does.",
+	"Optional note: what you will wait for before acting on the result; optional task: \"new\" or a task number from room_read.",
+	"The receipt is returned verbatim: sent #m<id> … / pending-confirm … / busy / an error reason."
 ].join(" ");
 const TOOL_SCHEMA = {
 	type: "object",
@@ -40,7 +47,24 @@ const TOOL_SCHEMA = {
 		},
 		text: {
 			type: "string",
-			description: "The notification text, delivered with your provenance."
+			description: "The message text, delivered with your provenance."
+		},
+		kind: {
+			type: "string",
+			enum: ["task", "notify"],
+			description: "task (default): the reply is reported back to you; notify: FYI only."
+		},
+		inReplyTo: {
+			type: "string",
+			description: "Optional id of the message this answers, e.g. m12."
+		},
+		note: {
+			type: "string",
+			description: "Optional: what you will wait for before acting on the result (the room uses it to decide when to hand you the report)."
+		},
+		task: {
+			type: "string",
+			description: "Optional: \"new\" or a task number from room_read; omit to stay in the task you are working on."
 		}
 	},
 	required: ["to", "text"],
@@ -62,7 +86,7 @@ const ROOM_TOOLS = [
 	},
 	{
 		name: "room_read",
-		description: "Read your room roster, coordinator, deliveries, recent outcomes and available harness providers. Identity comes from the host.",
+		description: "Read your room: roster with roles, coordinator, tasks with their numbers, deliveries, recent outcomes and available harness providers. Identity comes from the host. Use it to look around, not to wait for a result.",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -77,27 +101,128 @@ const ROOM_TOOLS = [
 			properties: {
 				provider: { type: "string" },
 				name: { type: "string" },
-				instructions: { type: "string" },
+				note: {
+					type: "string",
+					description: "What you will wait for before acting on the first task result."
+				},
+				role: {
+					type: "string",
+					description: "Short public role (≤30 chars) the other members see, e.g. 代码审查."
+				},
+				instructions: {
+					type: "string",
+					description: "Private instructions only this member reads."
+				},
 				cwd: { type: "string" },
 				model: { type: "string" },
-				firstTask: { type: "string" }
+				firstTask: { type: "string" },
+				mode: {
+					type: "string",
+					description: "The member's dsh mode (a host preset id, e.g. dsh-gamedev). Omit to keep this room's own mode; \"none\" for only its own CLI tools."
+				}
 			},
 			required: ["provider", "name"],
 			additionalProperties: false
 		}
 	},
+	{
+		name: "ask_user_question",
+		description: "Ask the human questions they answer by picking options (or typing), instead of writing the questions into your reply. Use it whenever you need the human to decide or fill in something before you go on: give each question 2-4 short options with a one-line description each. The call waits for the answer and returns {answers:[{id, selected:[labels], custom?}]}; if nobody answers it fails — then go on with your best judgement and say what you assumed.",
+		inputSchema: {
+			type: "object",
+			properties: { questions: {
+				type: "array",
+				description: "At most 4 questions.",
+				items: {
+					type: "object",
+					properties: {
+						id: {
+							type: "string",
+							description: "Short unique id, echoed in the answer."
+						},
+						question: {
+							type: "string",
+							description: "The full question."
+						},
+						header: {
+							type: "string",
+							description: "Optional 2-6 word topic chip."
+						},
+						options: {
+							type: "array",
+							items: {
+								type: "object",
+								properties: {
+									label: { type: "string" },
+									description: { type: "string" }
+								},
+								required: ["label"]
+							}
+						},
+						multi_select: {
+							type: "boolean",
+							description: "True when several options may be picked."
+						}
+					},
+					required: ["id", "question"]
+				}
+			} },
+			required: ["questions"],
+			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.",
+		description: "Send a room member a message by name (same as member_message). kind \"task\" (default): its reply comes back to you as a report citing the message id; kind \"notify\": FYI only. Do not poll.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				member: { type: "string" },
-				text: { type: "string" }
+				text: { type: "string" },
+				kind: {
+					type: "string",
+					enum: ["task", "notify"]
+				},
+				inReplyTo: { type: "string" },
+				note: {
+					type: "string",
+					description: "What you will wait for before acting on the result."
+				},
+				task: {
+					type: "string",
+					description: "\"new\" or a task number; omit to stay in your current task."
+				}
 			},
 			required: ["member", "text"],
 			additionalProperties: false
 		}
+	},
+	{
+		name: "room_help",
+		description: "Ask another session outside this room for help — typically the one that built what you are stuck on. It works in its own session (a busy one queues you); its final answer plus a short handoff comes back to you on its own, so end your turn after asking and do not poll. Name the session by title, id or the @ mention the human wrote; a session that is another room goes to its coordinator, or to the member you name. The first ask of a session the human did not @ in the room waits for their approval. To answer its question or ask more, call again with the help id and no session.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				session: {
+					type: "string",
+					description: "The session to ask (title, id, or @ mention). Omit when continuing a thread."
+				},
+				member: {
+					type: "string",
+					description: "When the session is another room: the member to ask. Omit to let its coordinator decide."
+				},
+				help: {
+					type: "string",
+					description: "The help id of an existing thread."
+				},
+				text: {
+					type: "string",
+					description: "What you need, self-contained: the helper does not see this room."
+				}
+			},
+			required: ["text"],
+			additionalProperties: false
+		}
 	}
 ];
 async function callRoomCommand(env, name, args) {
@@ -116,6 +241,35 @@ async function callRoomCommand(env, name, args) {
 		return toolText(`Room command unavailable: ${String(error)}`, true);
 	}
 }
+/** The member's mode tools (the preset's plugin tools), empty when it has none or the host is unreachable. */
+async function listModeTools(env) {
+	if (env.socket === void 0 || env.token === void 0) return [];
+	try {
+		const outcome = await callHost(env.socket, {
+			token: env.token,
+			modeTools: { list: true }
+		});
+		return outcome.ok && Array.isArray(outcome.tools) ? outcome.tools : [];
+	} catch {
+		return [];
+	}
+}
+/** Run one mode tool on the host; the host's MCP result passes through. */
+async function callModeTool(env, name, args) {
+	if (env.socket === void 0 || env.token === void 0) return toolText("member channel is not configured for this run", true);
+	try {
+		const outcome = await callHost(env.socket, {
+			token: env.token,
+			modeTools: { call: {
+				name,
+				arguments: args
+			} }
+		});
+		return outcome.ok && outcome.result !== void 0 ? outcome.result : toolText(outcome.error ?? `Tool ${name} failed`, true);
+	} catch (error) {
+		return toolText(`Mode tool 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) => {
@@ -163,7 +317,11 @@ async function callMemberMessage(env, args) {
 		const outcome = await callHost(env.socket, {
 			token: env.token,
 			to: args.to,
-			text: args.text
+			text: args.text,
+			...args.kind === "task" || args.kind === "notify" ? { kind: args.kind } : {},
+			...typeof args.inReplyTo === "string" ? { inReplyTo: args.inReplyTo } : {},
+			...typeof args.note === "string" ? { note: args.note } : {},
+			...typeof args.task === "string" ? { task: args.task } : {}
 		});
 		if (outcome.ok) return toolText(outcome.receipt ?? "sent");
 		return toolText(outcome.error ?? "member channel rejected the message", true);
@@ -229,15 +387,19 @@ function serveMemberBridge(env, input, output) {
 				});
 				return;
 			case "tools/list":
-				write({
+				listModeTools(env).then((modeTools) => write({
 					jsonrpc: "2.0",
 					id: id ?? null,
-					result: { tools: [{
-						name: MEMBER_MESSAGE_TOOL,
-						description: TOOL_DESCRIPTION,
-						inputSchema: TOOL_SCHEMA
-					}, ...ROOM_TOOLS] }
-				});
+					result: { tools: [
+						{
+							name: MEMBER_MESSAGE_TOOL,
+							description: TOOL_DESCRIPTION,
+							inputSchema: TOOL_SCHEMA
+						},
+						...ROOM_TOOLS,
+						...modeTools.filter((tool) => tool["name"] !== "member_message" && !ROOM_TOOLS.some((room) => room.name === tool["name"]))
+					] }
+				}));
 				return;
 			case "tools/call": {
 				const params = request.params;
@@ -250,14 +412,22 @@ function serveMemberBridge(env, input, output) {
 					return;
 				}
 				if (params?.name !== "member_message") {
-					write({
+					if (typeof params?.name !== "string") {
+						write({
+							jsonrpc: "2.0",
+							id: id ?? null,
+							error: {
+								code: -32602,
+								message: "tools/call requires a tool name"
+							}
+						});
+						return;
+					}
+					callModeTool(env, params.name, params.arguments ?? {}).then((result) => write({
 						jsonrpc: "2.0",
 						id: id ?? null,
-						error: {
-							code: -32602,
-							message: `unknown tool ${String(params?.name)}`
-						}
-					});
+						result
+					}));
 					return;
 				}
 				callMemberMessage(env, params.arguments ?? {}).then((result) => {
@@ -295,4 +465,4 @@ if (isMain()) serveMemberBridge({
 	token: process.env[MEMBER_BRIDGE_TOKEN_ENV]
 }, process.stdin, process.stdout);
 //#endregion
-export { MEMBER_MESSAGE_TOOL, callMemberMessage, callRoomCommand, serveMemberBridge };
+export { MEMBER_MESSAGE_TOOL, callMemberMessage, callModeTool, callRoomCommand, listModeTools, serveMemberBridge };

package/lib/tool-factory.js

@@ -1,4 +1,6 @@
+import { randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
+import { SessionId } from "@deepseek-ai/dsh-session";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region lib/types/tool-factory.js
 /**
@@ -17,9 +19,15 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 * The tool instead carries the handle as a first-class `resume` parameter and
 * resolves it through the localAgent service, which rejects any handle that
 * does not name a delegation recorded for THIS parent session and provider.
-* Continuation rounds still go through `ctx.subagents.start()`, so lifecycle
-* events (`subagent/start`/`subagent/end`) and the standard 子代理 surface are
-* unchanged.
+* Continuation rounds still go through `ctx.subagents.startActivation()` with
+* caller delivery, so lifecycle events (`subagent/start`/`subagent/end`) and
+* the standard 子代理 surface are unchanged.
+*
+* Host 0.2.1 note: `startActivation` rejects a provider run id that names a
+* live Session (DUPLICATE_CHILD) — and every family provider's child session
+* IS live. Providers therefore publish per-execution run ids, and the durable
+* dsh child session id is minted HERE (the tool), staged on the delegation
+* intent, and re-attached to the run adapter the rest of the family tracks.
 *
 * This module used to ship as the standalone companion package
 * `@khorsheed/dsh-local-agent-tool-subagent` (0.1.x); the family fold moved it
@@ -84,8 +92,10 @@ function stopReasonError(result) {
 /**
 * Fuse a caller-owned controller with the tool execution's signal so EITHER
 * abort cancels the run — the same shape the facade's tracked controller
-* uses. The active-delegation registry's stop lever aborts the controller;
-* the tool's own execution abort flows through the execution signal.
+* uses. The fused signal reaches `startActivation`'s `spec.signal`, which
+* owns cancellation only until publication (host 0.2.1); the published
+* activation's `dispose()` is the post-publication channel, wired below in
+* the exec body and in the registry's stop lever.
 */
 function fusedSignal(controller, caller) {
 	return caller === void 0 ? controller.signal : AbortSignal.any([controller.signal, caller]);
@@ -205,7 +215,11 @@ function mountSubagentDelegationTool(ctx, config, owner) {
 					provider: config.provider,
 					parentSessionId
 				});
-				if (resumeHandle === void 0) ctx.localAgent.stageDelegationIntent(parentSessionId, config.provider, { kind: "fresh" });
+				const childSessionId = resumeHandle ?? randomUUID();
+				if (resumeHandle === void 0) ctx.localAgent.stageDelegationIntent(parentSessionId, config.provider, {
+					kind: "fresh",
+					childSessionId
+				});
 				else if (resume !== void 0) {
 					await ctx.localAgent.ensureChildLive?.(resumeHandle);
 					ctx.localAgent.stageDelegationIntent(parentSessionId, config.provider, {
@@ -214,27 +228,46 @@ function mountSubagentDelegationTool(ctx, config, owner) {
 						cliSessionId: resume.cliSessionId
 					});
 				}
-				const request = {
-					label: args.description,
-					prompt: [{
-						type: "text",
-						text: args.prompt
-					}],
-					parent
-				};
 				const controller = new AbortController();
-				const run = await ctx.subagents.start(config.provider, {
-					...request,
-					signal: fusedSignal(controller, exec.signal)
+				const activation = await ctx.subagents.startActivation({
+					provider: config.provider,
+					label: args.description,
+					request: {
+						prompt: [{
+							type: "text",
+							text: args.prompt
+						}],
+						parent
+					},
+					signal: fusedSignal(controller, exec.signal),
+					delivery: "caller"
 				});
+				const dispose = () => activation.dispose();
+				const onExecAbort = () => {
+					dispose().catch((error) => {
+						ctx.logger.warn(`subagent tool: execution-signal disposal of ${childSessionId} failed: ${String(error)}`);
+					});
+				};
+				exec.signal.addEventListener("abort", onExecAbort, { once: true });
+				activation.result.then(() => exec.signal.removeEventListener("abort", onExecAbort), () => exec.signal.removeEventListener("abort", onExecAbort));
+				const run = {
+					id: SessionId(childSessionId),
+					result: activation.result,
+					dispose
+				};
 				const registry = ctx.localAgent;
-				if (typeof registry.trackDelegationRun === "function") registry.trackDelegationRun(String(run.id), run, () => controller.abort());
+				if (typeof registry.trackDelegationRun === "function") registry.trackDelegationRun(childSessionId, run, () => {
+					controller.abort();
+					dispose().catch((error) => {
+						ctx.logger.warn(`subagent tool: stop disposal of ${childSessionId} failed: ${String(error)}`);
+					});
+				});
 				const settled = await settleForegroundRun(run);
 				if (resume === void 0) return {
 					...settled,
 					output: [...settled.output, {
 						type: "text",
-						text: `${RESUME_HINT_PREFIX}${run.id}"`
+						text: `${RESUME_HINT_PREFIX}${childSessionId}"`
 					}]
 				};
 				return settled;