@khorsheed/dsh-room 0.2.2 → 0.2.3

package/lib/tool.js

@@ -1,37 +1,6 @@
-import { i as isRoomLog, r as coordinatorMember } from "./journal-BWL3-i0s.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region lib/types/tool-definition.js
 /**
-* The room's model-facing tool DEFINITIONS, `room_invite`, `room_task`, and
-* `room_message`: the main
-* agent's paths into the room it belongs to. `room_invite` and
-* `room_message` PROMOTE: calling them in a plain session turns it into a
-* room (ensureRoom) instead of rejecting. `room_task` stays gated at execute
-* time — the calling agent's session must be a room (the journal carries
-* `room/created`); anywhere else the tool answers with readable error text
-* instead of throwing, so the model can see the rejection and self-correct.
-* `room_invite` lands in the same invite path as the human dialog
-* (`invitedBy: 'agent'`), producing an identical member record; `room_task`
-* writes the SHARED task board through the very host functions the capsule UI
-* uses (addTask/closeTask, plus the tool-only updateTask), so an agent-written
-* task is indistinguishable from a human-added one; `room_message` dispatches
-* a message to a member through the same engine path as the human's
-* `@member text`, minus the user bubble (the caller is the room's own agent).
-*
-* Since the tool-row split (M4') the core never REGISTERS these tools: the
-* factories are consumed by the package's `./tool` subpath row
-* ({@link file://./tool.ts}), which mounts them inside agent-preset
-* compositions (session-granted, never at the profile root). The definitions
-* are therefore returned UNTAGGED — the registering row applies its own
-* tool-origin tag (AGENTS.md § Tool origin tagging — the owner is whichever
-* package mounts the row).
-*
-* Internal module: not on the package's exports map (consumers reach it only
-* through `./src/*`).
-*
-* @module @khorsheed/dsh-room
-*/
-/**
 * Build the room_invite tool definition bound to the room service.
 * @param backend - the room service.
 * @returns a registry-ready tool definition.
@@ -39,30 +8,42 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 function roomInviteTool(backend) {
 	return defineTool({
 		name: "room_invite",
-		description: "Invite a CLI agent member into the current session (any session works — inviting promotes it into a room: the multi-agent group conversation surface wakes up on it). The member becomes @-addressable by the human and by other members: pick a short unique name (no whitespace, no \"@\", e.g. ada/bill/cathy) — it is the addressing name, decoupled from the provider so two instances of one provider can coexist; prefer a function-style name (e.g. design-review / restart-test) when the member has a standing role, so the human and the other members can tell what it is for. The instructions are the member's role briefing, prepended to its first dispatch and persisted in its own CLI session from then on. Give a firstTask to put the member to work immediately, or omit it to have the member join idle. A member keeps its own CLI session and accumulates context across rounds, so prefer inviting over a one-shot subagent_* delegation whenever the work expects follow-ups with the same agent — reserve one-shot delegations for self-contained tasks with no continuation. The provider must be a registered delegation provider id — an unknown one is rejected with the list of available ids, so retry with one of those.",
+		description: "Invite a CLI agent member into the current session (any session works — inviting promotes it into a room: the multi-agent group conversation surface wakes up on it). The member becomes @-addressable by the human and by other members: pick a short unique name (no whitespace, no \"@\", e.g. ada/bill/cathy) — it is the addressing name, decoupled from the provider so two instances of one provider can coexist; prefer a function-style name (e.g. design-review / restart-test) when the member has a standing role, so the human and the other members can tell what it is for. Give a short public role (what everyone else sees) and private instructions: the instructions are the member's own briefing, prepended to its first dispatch and persisted in its own CLI session from then on. Give a firstTask to put the member to work immediately, or omit it to have the member join idle. A member keeps its own CLI session and accumulates context across rounds, so prefer inviting over a one-shot subagent_* delegation whenever the work expects follow-ups with the same agent — reserve one-shot delegations for self-contained tasks with no continuation. room_read lists the invitable providers and modes (it works before the session is a room too); the provider may be its id or the harness name (e.g. claude-code).",
 		parameters: {
 			provider: {
 				type: "string",
 				required: true,
-				description: "The local-agent delegation provider id (e.g. kimi-cli / codex-cli / claude-code) — the delegation id the family registered, which may differ from the harness's display name. When unsure, call without firstTask first: an unknown id is rejected with the list of available providers to retry with."
+				description: "The CLI to invite: a provider id from room_read, or the harness name / display name (claude-code, Claude Code, codex, kimi). An unknown one is rejected with the available ids."
 			},
 			name: {
 				type: "string",
 				required: true,
 				description: "The member's @-addressing name: unique in this room, no whitespace, no \"@\"."
 			},
+			role: {
+				type: "string",
+				description: "Short public role (≤30 chars, e.g. 代码审查 / 实现 / 测试): what the other members and the human see. Keep it a phrase; details go in instructions."
+			},
 			instructions: {
 				type: "string",
 				required: true,
-				description: "The member's role instructions (responsibilities, constraints, output expectations)."
+				description: "The member's private instructions (responsibilities, constraints, output expectations). Only this member ever reads them."
 			},
 			firstTask: {
 				type: "string",
-				description: "Optional first task, dispatched to the member as soon as it joins."
+				description: "Optional first task, dispatched to the member as soon as it joins. Its result is reported back to you automatically — do not sleep or poll room_read for it."
+			},
+			note: {
+				type: "string",
+				description: "Optional: what you will wait for before acting on the first task's result (e.g. \"wait until every invited member greeted\"). The room uses it to decide when to hand you the report."
 			},
 			cwd: {
 				type: "string",
 				description: "Optional working directory for the member (empty: inherits the room session's cwd)."
+			},
+			mode: {
+				type: "string",
+				description: "The member's dsh mode: a host agent preset id (e.g. dsh-gamedev, dsh-video). The member can then call that mode's plugin tools (and sees its skills) besides its own CLI tools. Omit it to keep this room's own mode — the usual choice; pass the mode the human asked for when they named one, or \"none\" for a member with only its own CLI tools. An unknown id is rejected with the available ids."
 			}
 		},
 		output: {
@@ -88,139 +69,23 @@ function roomInviteTool(backend) {
 				provider: args.provider,
 				name: args.name,
 				instructions: args.instructions,
+				...args.role === void 0 ? {} : { role: args.role },
 				...args.firstTask === void 0 ? {} : { firstTask: args.firstTask },
-				...args.cwd === void 0 ? {} : { cwd: args.cwd }
+				...args.note === void 0 ? {} : { note: args.note },
+				...args.cwd === void 0 ? {} : { cwd: args.cwd },
+				...args.mode === void 0 || args.mode.trim() === "" ? { inheritPreset: true } : args.mode.trim() === "none" ? {} : { preset: args.mode.trim() }
 			}, "agent");
 			if (!result.ok) {
-				const hint = result.error.code === "duplicate-name" ? " Pick a different name and retry." : result.error.code === "invalid-name" ? " Names must be non-empty and free of whitespace and \"@\"; retry with a valid name." : result.error.code === "local-agent-unavailable" ? " The local-agent delegation facade is not mounted; CLI members cannot join right now." : result.error.code === "unknown-provider" ? ` Unknown delegation provider "${result.error.provider}" (it must be the family's delegation provider id, not the harness's display name). Available: ${result.error.available.length === 0 ? "none (no harness with a delegation provider is registered)" : result.error.available.join(", ")}. Retry with one of the available providers.` : "";
+				const hint = result.error.code === "duplicate-name" ? " Pick a different name and retry." : result.error.code === "invalid-name" ? " Names must be non-empty and free of whitespace and \"@\"; retry with a valid name." : result.error.code === "role-too-long" ? " The role must be at most 30 characters; shorten it and move details into instructions." : result.error.code === "local-agent-unavailable" ? " The local-agent delegation facade is not mounted; CLI members cannot join right now." : result.error.code === "unknown-provider" ? ` Unknown delegation provider "${result.error.provider}" (it must be the family's delegation provider id, not the harness's display name). Available: ${result.error.available.length === 0 ? "none (no harness with a delegation provider is registered)" : result.error.available.join(", ")}. Retry with one of the available providers.` : result.error.code === "unknown-preset" ? ` Unknown mode "${result.error.preset}". Available: ${result.error.available.join(", ") || "none"}; or "none" for no mode.` : "";
 				return { text: `Could not invite "${args.name}": ${result.error.code}.${hint}` };
 			}
-			return { text: result.value.pendingFirstTask ? `Member ${result.value.name} joined the room and its first task was dispatched.` : `Member ${result.value.name} joined the room (idle; @-address it to dispatch work).` };
+			return { text: result.value.pendingFirstTask ? `Member ${result.value.name} joined the room and its first task was dispatched.${modeNote(result.value.preset)}` : `Member ${result.value.name} joined the room (idle; @-address it to dispatch work).${modeNote(result.value.preset)}` };
 		}
 	});
 }
-/**
-* Build the room_task tool definition bound to the room service. Every write
-* goes through the same host functions as the capsule UI, so a task the agent
-* opens is a public commitment indistinguishable from a human-added one.
-* @param backend - the room service.
-* @returns a registry-ready tool definition.
-*/
-function roomTaskTool(backend) {
-	return defineTool({
-		name: "room_task",
-		description: "Manage the current room's SHARED task board (only usable inside a room session). This board is public — every room member and the human sees these tasks, so writing here is a public commitment the room coordinates around; for your private work plan use your own todo tool instead. Actions: \"add\" (title + member — the roster name owning the task, use room_read to find your own or another member's name; optional blockedBy names the member the task waits on, display only) opens a pending task and returns its id; \"close\" (taskId) marks an open task done; \"update\" (taskId + a new title and/or blockedBy — null clears the wait) edits an open task. Errors answer with the roster or the open-task list so you can retry with a valid member name or task id.",
-		parameters: {
-			action: {
-				type: "string",
-				enum: [
-					"add",
-					"close",
-					"update"
-				],
-				required: true,
-				description: "add: open a task (title + member). close: mark a task done (taskId). update: edit title/blockedBy (taskId)."
-			},
-			title: {
-				type: "string",
-				description: "Task title. Required for add; optional new title for update."
-			},
-			member: {
-				type: "string",
-				description: "The roster name owning the task (required for add; read room_read for current names)."
-			},
-			taskId: {
-				type: "string",
-				description: "The task id (required for close/update; add's success text returns the new id)."
-			},
-			blockedBy: {
-				oneOf: [{ type: "string" }, { type: "null" }],
-				description: "The member this task waits on (must be on the roster; display only, never an automatic dispatch). Optional on add; on update, a string re-targets the wait and null clears it."
-			}
-		},
-		output: {
-			schema: {
-				type: "object",
-				additionalProperties: false,
-				properties: { text: {
-					type: "string",
-					required: true
-				} }
-			},
-			render: (_args, value) => [{
-				type: "text",
-				text: value.text
-			}]
-		},
-		isConcurrencySafe: () => true,
-		async execute(args, exec) {
-			const agent = exec.agent;
-			if (agent === void 0) return { text: "room_task requires a calling agent (exec.agent was undefined)." };
-			if (!isRoomLog(agent.session.snapshotEvents())) return { text: "The current session is not a room; room_task is only usable inside a room session." };
-			const sessionId = agent.session.id;
-			const ownership = await backend.getState({ sessionId });
-			if (ownership.ok && coordinatorMember(ownership.value)?.kind !== "main-agent") return { text: "Only the current coordinator may manage the shared room task board." };
-			/** The self-correcting roster suffix: the legal member names, for member-not-found. */
-			const rosterHint = async () => {
-				const state = await backend.getState({ sessionId });
-				if (!state.ok) return "";
-				const names = state.value.members.map((member) => member.name);
-				return names.length === 0 ? "" : ` The room roster is: ${names.join(", ")}. Retry with one of these names.`;
-			};
-			/** The self-correcting board suffix: the open tasks (id — title), for task-not-found. */
-			const openTasksHint = async () => {
-				const state = await backend.getState({ sessionId });
-				if (!state.ok) return "";
-				const open = state.value.tasks.filter((task) => task.status === "pending" || task.status === "in_progress");
-				if (open.length === 0) return " The board has no open tasks right now.";
-				return ` Open tasks: ${open.map((task) => `${task.id} — "${task.title}" (${task.member}, ${task.status})`).join("; ")}. Retry with one of these ids.`;
-			};
-			const failureText = async (code) => {
-				switch (code) {
-					case "member-not-found": return `Unknown member.${await rosterHint()}`;
-					case "empty-text": return "The title must be non-blank; retry with a real title.";
-					case "task-not-found": return `No task with that id.${await openTasksHint()}`;
-					case "task-closed": return "That task is already closed (done/cancelled); closed tasks take no further changes.";
-					case "nothing-to-update": return "update needs at least one field to change: a new title and/or blockedBy (null clears the wait).";
-					default: return `The room rejected the write (${code}).`;
-				}
-			};
-			switch (args.action) {
-				case "add": {
-					if (args.title === void 0 || args.member === void 0) return { text: "room_task add requires both title and member (the roster name owning the task; read room_read for current names)." };
-					if (args.blockedBy === null) return { text: "add takes no null blockedBy — simply omit blockedBy for an unblocked task." };
-					const result = await backend.addTask({
-						sessionId,
-						member: args.member,
-						title: args.title,
-						...args.blockedBy === void 0 ? {} : { blockedBy: args.blockedBy }
-					});
-					if (!result.ok) return { text: `Could not add the task: ${result.error.code}. ${await failureText(result.error.code)}` };
-					return { text: `Task "${args.title}" is now on ${args.member}'s lane of the shared room board (id: ${result.value.id}) — visible to every member and the human. Keep the id to update or close the task later.` };
-				}
-				case "close": {
-					if (args.taskId === void 0) return { text: `room_task close requires taskId.${await openTasksHint()}` };
-					const result = await backend.closeTask({
-						sessionId,
-						taskId: args.taskId
-					});
-					if (!result.ok) return { text: `Could not close the task: ${result.error.code}. ${await failureText(result.error.code)}` };
-					return { text: `Task ${result.value.id} is done — the shared board shows it closed.` };
-				}
-				case "update": {
-					if (args.taskId === void 0) return { text: `room_task update requires taskId.${await openTasksHint()}` };
-					const result = await backend.updateTask({
-						sessionId,
-						taskId: args.taskId,
-						...args.title === void 0 ? {} : { title: args.title },
-						...args.blockedBy === void 0 ? {} : { blockedBy: args.blockedBy }
-					});
-					if (!result.ok) return { text: `Could not update the task: ${result.error.code}. ${await failureText(result.error.code)}` };
-					return { text: `Task ${result.value.id} updated on the shared room board.` };
-				}
-			}
-		}
-	});
+/** The invite receipt's mode line, so the caller can tell the human which mode the member runs. */
+function modeNote(preset) {
+	return preset === void 0 ? " Mode: none (its own CLI tools only)." : ` Mode: ${preset}.`;
 }
 /**
 * Build the room_message tool definition bound to the room service: the main
@@ -233,7 +98,7 @@ function roomTaskTool(backend) {
 function roomMessageTool(backend) {
 	return defineTool({
 		name: "room_message",
-		description: "Dispatch a message to a member of the current room (works in any session — it promotes the session into a room if it is not one yet). A member is an independent CLI session: the message runs asynchronously, and the member's reply appears in the room as member speech (the human sees it; you read it through the room's flow). Use this to ask a member something or hand it work — the equivalent of the human typing \"@member <text>\" in the room composer. The member argument is a roster name (read room_read for current names); an unknown name is rejected with the live roster, so retry with one of those.",
+		description: "Send a message to another member of the current room (works in any session — it promotes the session into a room if it is not one yet). A member is an independent session: the message runs asynchronously in its own session. kind \"task\" (default) hands it work — its final reply is reported back to you automatically, quoting the message id, so do not poll; kind \"notify\" is an FYI that is never reported back. After sending, end your turn: never sleep or poll for the result (room_read included) — the report arrives on its own. Writing \"@name\" in a reply reaches nobody; only this tool does. Pass inReplyTo with a message id (e.g. m12) when answering one. The member argument is a roster name (read room_read for current names); an unknown name is rejected with the live roster, so retry with one of those.",
 		parameters: {
 			member: {
 				type: "string",
@@ -243,7 +108,24 @@ function roomMessageTool(backend) {
 			text: {
 				type: "string",
 				required: true,
-				description: "The message text the member receives as its task."
+				description: "The message text the member receives."
+			},
+			kind: {
+				type: "string",
+				enum: ["task", "notify"],
+				description: "task (default): its reply is reported back to you. notify: FYI, no report."
+			},
+			inReplyTo: {
+				type: "string",
+				description: "Optional id of the message this answers (e.g. m12)."
+			},
+			task: {
+				type: "string",
+				description: "Optional: which task this belongs to — \"new\" or a task number from room_read (e.g. \"2\"). Use it when the human's latest message was filed under the wrong task: it re-files that message too. Omit to stay in the current task."
+			},
+			note: {
+				type: "string",
+				description: "Optional: what you will wait for before acting on this result, in your own words (e.g. \"wait until all three greeted, then tell the user once\" / \"hand it to claude for review as soon as it is done\"). The room uses it to decide when to hand you the report."
 			}
 		},
 		output: {
@@ -268,7 +150,11 @@ function roomMessageTool(backend) {
 			const result = await backend.messageMember({
 				sessionId,
 				member: args.member,
-				text: args.text
+				text: args.text,
+				...args.kind === void 0 ? {} : { kind: args.kind },
+				...args.inReplyTo === void 0 ? {} : { inReplyTo: args.inReplyTo },
+				...args.note === void 0 ? {} : { note: args.note },
+				...args.task === void 0 ? {} : { task: args.task }
 			});
 			if (!result.ok) {
 				if (result.error.code === "member-not-found") {
@@ -277,10 +163,14 @@ function roomMessageTool(backend) {
 					const hint = names.length === 0 ? "" : ` The room roster is: ${names.join(", ")}. Retry with one of these names.`;
 					return { text: `Could not message "${args.member}": unknown member.${hint}` };
 				}
+				if (result.error.code === "self-message") return { text: "You cannot message yourself; pick another member." };
+				if (result.error.code === "unknown-task") return { text: `No task "${args.task}" in this room; pass "new" or a task number from room_read.` };
 				if (result.error.code === "empty-text") return { text: "The message text must be non-blank; retry with real content." };
 				return { text: `Could not message "${args.member}": ${result.error.code}.` };
 			}
-			return { text: `Dispatched to ${result.value.member} — the member runs it asynchronously and its reply appears in the room as member speech. Do not wait on it; the human watches the room.` };
+			const value = result.value;
+			if (value.held !== void 0) return { text: value.held === "paused" ? `Held: the room is paused; the message to ${value.member} is delivered when the human resumes it.` : value.held === "hop-limit" ? `Held: this chain of messages reached the room's hop limit; the human decides whether ${value.member} gets it.` : `Held: the room asks the human to confirm member messages; ${value.member} gets it once confirmed.` };
+			return { text: args.kind === "notify" ? `Sent ${value.messageId} to ${value.member} as an FYI; no report will come back.` : `Sent ${value.messageId} to ${value.member}. It runs asynchronously; its final reply comes back to you automatically as a report citing this id. Do not sleep, wait, or poll room_read for it — end your turn; the human already sees the member's reply in the room, so do not repeat it when the report arrives.` };
 		}
 	});
 }
@@ -288,7 +178,7 @@ function roomMessageTool(backend) {
 function roomReadTool(backend) {
 	return defineTool({
 		name: "room_read",
-		description: "Read the current room roster, coordinator, deliveries, recent outcomes and available harness providers. Reading does not wake any member.",
+		description: "Read the current room: roster with each member's role, the coordinator, the tasks with their numbers (for the task parameter), deliveries, recent outcomes and available harness providers. In a session that is not a room yet it returns the invitable providers and modes instead. Reading does not wake any member. Use it to look around, not to wait for a result — reports arrive on their own.",
 		parameters: {},
 		output: {
 			schema: {
@@ -350,6 +240,62 @@ function roomPlanTool(backend) {
 		}
 	});
 }
+/**
+* Build the room_help tool definition bound to the room service.
+* @param backend - the room service.
+* @returns a registry-ready tool definition.
+*/
+function roomHelpTool(backend) {
+	return defineTool({
+		name: "room_help",
+		description: "Ask another session — outside this room — for help: typically the session that built the thing you are stuck on, which still has the whole context. The helper keeps working in its own session (if it is busy, your request waits in its queue) and its final answer plus a short handoff comes back to you on its own, so end your turn after asking; never poll. Name the session by its title, its id, or the @ mention the human wrote. A session that is another room hands the request to its coordinator, or to the member you name (a mention labelled 「成员（房间）」 names one). The first ask of a session the human did not @ in this room waits for the human's approval. To answer the helper's question or ask it more, call again with the help id and no session.",
+		parameters: {
+			session: {
+				type: "string",
+				description: "The session to ask (title, id, or @ mention). Omit when continuing a thread with help."
+			},
+			member: {
+				type: "string",
+				description: "When the session is another room: the member of that room to ask. Omit to let its coordinator decide."
+			},
+			help: {
+				type: "string",
+				description: "The help id of an existing thread, to answer its question or follow up."
+			},
+			text: {
+				type: "string",
+				required: true,
+				description: "What you need, self-contained: the helper does not see this room. Include the error, what you tried, where things are."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { text: {
+					type: "string",
+					required: true
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		isConcurrencySafe: () => true,
+		async execute(args, exec) {
+			const agent = exec.agent;
+			if (agent === void 0) return { text: "room_help requires a calling agent (exec.agent was undefined)." };
+			return { text: await backend.askHelp({
+				sessionId: agent.session.id,
+				text: args.text,
+				...args.session === void 0 ? {} : { session: args.session },
+				...args.member === void 0 ? {} : { member: args.member },
+				...args.help === void 0 ? {} : { help: args.help }
+			}, agent) };
+		}
+	});
+}
 //#endregion
 //#region lib/types/tool.js
 const PACKAGE_NAME = "@khorsheed/dsh-room";
@@ -394,8 +340,8 @@ function apply(ctx) {
 		if (typeof service.commandPlan === "function") toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(roomPlanTool(service))), "room-tool: room_plan tool");
 		if (typeof service.readRoomContext === "function") toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(roomReadTool(service))), "room-tool: room_read tool");
 		toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(roomInviteTool(service))), "room-tool: room_invite tool");
-		toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(roomTaskTool(service))), "room-tool: room_task tool");
 		toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(roomMessageTool(service))), "room-tool: room_message tool");
+		if (typeof service.askHelp === "function") toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(roomHelpTool(service))), "room-tool: room_help tool");
 	});
 }
 //#endregion