@khorsheed/dsh-room 0.1.0 → 0.2.0

package/lib/types/index.js

@@ -44,8 +44,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * room host half: the `room` Typert Remote service. (The `room_invite` /
  * `room_task` / `room_message` model tools left this package's profile-root
  * registration in the M4' tool-row split — their definition factories live
- * in ./tool.ts and the companion `@khorsheed/dsh-room-tool` mounts them
- * inside agent-preset compositions.) The room's entire state is the session's `room/*` custom-event
+ * in ./tool-definition.ts and the package's own `./tool` composition entry
+ * mounts them inside agent-preset compositions.) The room's entire state is the session's `room/*` custom-event
  * journal (log-only events — persistence and reload-replay come free, the
  * model never sees them, and harnesses without this plugin replay the session
  * safely); every read folds the journal through the pure replay, and every
@@ -126,6 +126,7 @@ let RoomService = (() => {
     let _closeTask_decorators;
     let _setGoal_decorators;
     let _cancel_decorators;
+    let _cancelChild_decorators;
     return class RoomService extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -146,6 +147,7 @@ let RoomService = (() => {
             _closeTask_decorators = [Remote('closeTask')];
             _setGoal_decorators = [Remote('setGoal')];
             _cancel_decorators = [Remote('cancel')];
+            _cancelChild_decorators = [Remote('cancelChild')];
             __esDecorate(this, null, _isRoom_decorators, { kind: "method", name: "isRoom", static: false, private: false, access: { has: obj => "isRoom" in obj, get: obj => obj.isRoom }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _listProviders_decorators, { kind: "method", name: "listProviders", static: false, private: false, access: { has: obj => "listProviders" in obj, get: obj => obj.listProviders }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getState_decorators, { kind: "method", name: "getState", static: false, private: false, access: { has: obj => "getState" in obj, get: obj => obj.getState }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -163,6 +165,7 @@ let RoomService = (() => {
             __esDecorate(this, null, _closeTask_decorators, { kind: "method", name: "closeTask", static: false, private: false, access: { has: obj => "closeTask" in obj, get: obj => obj.closeTask }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setGoal_decorators, { kind: "method", name: "setGoal", static: false, private: false, access: { has: obj => "setGoal" in obj, get: obj => obj.setGoal }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _cancel_decorators, { kind: "method", name: "cancel", static: false, private: false, access: { has: obj => "cancel" in obj, get: obj => obj.cancel }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _cancelChild_decorators, { kind: "method", name: "cancelChild", static: false, private: false, access: { has: obj => "cancelChild" in obj, get: obj => obj.cancelChild }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         static inject = ['sessions', 'agents'];
@@ -232,9 +235,10 @@ let RoomService = (() => {
                 return { kind: 'enter', messages: [] };
             });
             // The model-facing room tools are deliberately NOT registered here: they
-            // moved to the companion `@khorsheed/dsh-room-tool`, which mounts the
-            // tool row inside agent-preset compositions (session-granted). The
-            // definition factories stay exported from ./tool.ts for that companion.
+            // belong to this package's `./tool` composition entry (src/tool.ts),
+            // which mounts the tool row inside agent-preset compositions
+            // (session-granted). The definition factories live in
+            // ./tool-definition.ts for that row.
         }
         /** Resolve a LIVE session as a room: presence, marker, replayed state. */
         load(sessionId) {
@@ -1169,16 +1173,25 @@ let RoomService = (() => {
             const member = loaded.state.members.find(entry => entry.name === request.name);
             if (member === undefined)
                 return { ok: false, error: { code: 'member-not-found' } };
+            const expected = loaded.state.runs.find(entry => entry.member === request.name && entry.state === 'running');
+            if ((request.expectedRunId !== undefined && expected?.runId !== request.expectedRunId)
+                || (request.expectedStartedAt !== undefined && expected?.startedAt !== request.expectedStartedAt)) {
+                return { ok: true, value: { cancelled: false } };
+            }
             const facade = probeLocalAgent(this.ctx);
-            const hit = facade !== undefined && member.childSessionId !== undefined
+            const native = member.kind === 'main-agent' && expected !== undefined ? this.ctx.agents.get(loaded.session.id) : undefined;
+            if (native !== undefined)
+                native.cancel({ kind: 'user' });
+            const hit = native !== undefined || (facade !== undefined && member.childSessionId !== undefined
                 ? facade.cancel(member.childSessionId)
-                : false;
+                : false);
             if (hit) {
                 const running = loaded.state.runs.find(entry => entry.member === request.name && entry.state === 'running');
                 if (running === undefined)
                     return { ok: true, value: { cancelled: true } };
                 loaded.session.append('room/run-state', {
                     member: request.name, state: 'cancelled', startedAt: running.startedAt,
+                    elapsedMs: Math.max(0, Date.now() - running.startedAt),
                     ...running.runId === undefined ? {} : { runId: running.runId },
                 });
                 // The engine's settle no-ops behind this edge, so the task closing the
@@ -1194,6 +1207,28 @@ let RoomService = (() => {
             }
             return { ok: true, value: { cancelled: false } };
         }
+        /** Native descendant controls share the host's continuation and cancellation channels. */
+        async cancelChild(request) {
+            const loaded = await this.ensureLive(request.sessionId);
+            if (!loaded.ok)
+                return { ok: false, error: loaded.error };
+            const target = this.ctx.sessions.get(request.childSessionId);
+            const seen = new Set([request.childSessionId]);
+            let parent = target?.header.parentSession;
+            while (parent !== undefined && parent !== request.sessionId && !seen.has(parent)) {
+                seen.add(parent);
+                parent = this.ctx.sessions.get(parent)?.header.parentSession;
+            }
+            if (!target || target.id === request.sessionId || parent !== request.sessionId)
+                return { ok: true, value: { cancelled: false } };
+            const facadeHit = probeLocalAgent(this.ctx)?.cancel(target.id) ?? false;
+            const agent = this.ctx.agents.get(target.id);
+            if (agent) {
+                this.ctx.get('subagents')?.interrupt(target.id, { kind: 'user', parentSessionId: target.header.parentSession });
+                agent.cancel({ kind: 'user' });
+            }
+            return { ok: true, value: { cancelled: facadeHit || agent !== undefined } };
+        }
     };
 })();
 export { RoomService };

package/lib/types/journal.d.ts

@@ -18,7 +18,7 @@ export declare const MAIN_AGENT_MEMBER = "dsh";
  * in-place add is that surface's temporary form — migrate to the official
  * one when it lands upstream.
  */
-export declare const ROOM_EVENT_TYPES: readonly ['room/created', 'room/plan-state', 'room/coordinator', 'room/delivery-state', 'room/member-added', 'room/member-updated', 'room/member-removed', 'room/dispatch', 'room/speech', 'room/run-state', 'room/relay', 'room/relay-resolved', 'room/task-added', 'room/task-updated', 'room/task-edited', 'room/goal'];
+export declare const ROOM_EVENT_TYPES: readonly ['room/created', 'room/plan-state', 'room/coordinator', 'room/delivery-state', 'room/member-added', 'room/member-updated', 'room/member-removed', 'room/dispatch', 'room/speech', 'room/run-state', 'room/execution-metadata', 'room/relay', 'room/relay-resolved', 'room/task-added', 'room/task-updated', 'room/task-edited', 'room/goal'];
 /** Whether an event log carries the room identity marker. */
 export declare function isRoomLog(events: readonly SessionEvent[]): boolean;
 /**

package/lib/types/journal.js

@@ -40,6 +40,7 @@ export const ROOM_EVENT_TYPES = [
     'room/dispatch',
     'room/speech',
     'room/run-state',
+    'room/execution-metadata',
     'room/relay',
     'room/relay-resolved',
     'room/task-added',
@@ -114,6 +115,7 @@ export function replay(events) {
     const tasks = [];
     const taskById = new Map();
     const runs = new Map();
+    const executions = new Map();
     let goal;
     let coordinator;
     for (const event of events) {
@@ -160,6 +162,12 @@ export function replay(events) {
                     ...withoutModel,
                     ...event.data.childSessionId === undefined ? {} : { childSessionId: event.data.childSessionId },
                 };
+                // First admission can precede publication of the native child handle.
+                for (const [id, execution] of executions) {
+                    if (execution.memberId === member.id && execution.childSessionId === undefined && patched.childSessionId !== undefined) {
+                        executions.set(id, { ...execution, childSessionId: patched.childSessionId });
+                    }
+                }
                 // A rename migrates every name-keyed projection: the roster key, the
                 // tasks' member (and blockedBy), the relays' from/to, and the runs
                 // key. The child session id rides the member record and stays. A
@@ -288,7 +296,25 @@ export function replay(events) {
                 goal = text === '' ? undefined : text;
                 break;
             }
+            case 'room/execution-metadata': {
+                const previous = executions.get(event.data.runId);
+                if (previous)
+                    executions.set(previous.id, { ...previous, ...event.data });
+                break;
+            }
             case 'room/run-state': {
+                const member = byName.get(event.data.member);
+                const id = event.data.runId ?? `legacy:${member?.id ?? event.data.member}:${event.data.startedAt}`;
+                const previous = executions.get(id);
+                executions.set(id, {
+                    id,
+                    ...member?.id === undefined ? {} : { memberId: member.id },
+                    ...member?.childSessionId === undefined ? {} : { childSessionId: member.childSessionId },
+                    ...member?.provider === undefined ? {} : { provider: member.provider },
+                    ...previous,
+                    ...event.data,
+                    ...event.data.state === 'running' || event.data.elapsedMs !== undefined ? {} : { elapsedMs: Math.max(0, event.time - event.data.startedAt) },
+                });
                 const current = runs.get(event.data.member);
                 // An older turn may finish journaling after core admits its successor.
                 // Its delivery outcome remains durable, but it cannot replace that successor.
@@ -311,7 +337,7 @@ export function replay(events) {
     const planEvent = events.filter(event => event.type === 'room/plan-state').at(-1);
     const plan = planEvent?.type === 'room/plan-state' ? (({ requests: _requests, ...view }) => view)(planEvent.data) : undefined;
     const deliveries = replayDeliveries(events);
-    return { members, relays, tasks, ...plan === undefined ? {} : { plan }, ...deliveries.length === 0 ? {} : { deliveries }, runs: [...runs.values()], ...coordinator === undefined ? {} : { coordinator }, ...goal === undefined ? {} : { goal } };
+    return { members, relays, tasks, ...executions.size === 0 ? {} : { executions: [...executions.values()] }, ...plan === undefined ? {} : { plan }, ...deliveries.length === 0 ? {} : { deliveries }, runs: [...runs.values()], ...coordinator === undefined ? {} : { coordinator }, ...goal === undefined ? {} : { goal } };
 }
 /**
  * The goal progress pair: done tasks over the COUNTABLE total — cancelled

package/lib/types/tool-definition.d.ts

@@ -0,0 +1,56 @@
+import type { RoomAddTaskRequest, RoomAddTaskResult, RoomCloseTaskRequest, RoomCloseTaskResult, RoomGetStateRequest, RoomGetStateResult, RoomInviteRequest, RoomInviteResult, RoomMessageRequest, RoomMessageResult, RoomUpdateTaskRequest, RoomUpdateTaskResult } from './types.ts';
+/** The slice of RoomService the tool drives. */
+export interface RoomInviteToolBackend {
+    /** Validate and journal an invitation (see RoomService.inviteMember). */
+    inviteMember(request: RoomInviteRequest, invitedBy: 'human' | 'agent'): Promise<RoomInviteResult>;
+}
+/**
+ * Build the room_invite tool definition bound to the room service.
+ * @param backend - the room service.
+ * @returns a registry-ready tool definition.
+ */
+export declare function roomInviteTool(backend: RoomInviteToolBackend): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The slice of RoomService the room_task tool drives. */
+export interface RoomTaskToolBackend {
+    /** Open a pending task on a member's lane (see RoomService.addTask). */
+    addTask(request: RoomAddTaskRequest): Promise<RoomAddTaskResult>;
+    /** Close an open task (see RoomService.closeTask). */
+    closeTask(request: RoomCloseTaskRequest): Promise<RoomCloseTaskResult>;
+    /** Edit an open task's title/blockedBy (see RoomService.updateTask). */
+    updateTask(request: RoomUpdateTaskRequest): Promise<RoomUpdateTaskResult>;
+    /** Replay the room state (the error texts read the roster/open tasks from it). */
+    getState(request: RoomGetStateRequest): Promise<RoomGetStateResult>;
+}
+/**
+ * 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.
+ */
+export declare function roomTaskTool(backend: RoomTaskToolBackend): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The slice of RoomService the room_message tool drives. */
+export interface RoomMessageToolBackend {
+    /** Dispatch one message to one member (see RoomService.messageMember). */
+    messageMember(request: RoomMessageRequest): Promise<RoomMessageResult>;
+    /** Replay the room state (the error text reads the live roster from it). */
+    getState(request: RoomGetStateRequest): Promise<RoomGetStateResult>;
+}
+/**
+ * Build the room_message tool definition bound to the room service: the main
+ * agent's way to hand a member a message/task — the model-facing equivalent
+ * of the human's `@member text`, minus the user bubble (the caller is the
+ * room's own agent, not the human).
+ * @param backend - the room service.
+ * @returns a registry-ready tool definition.
+ */
+export declare function roomMessageTool(backend: RoomMessageToolBackend): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Native room tools use the same bounded context reader as the external MCP bridge. */
+export declare function roomReadTool(backend: {
+    readRoomContext(sessionId: string): Promise<string>;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Formal planning uses the same strict command grammar exposed by room_read. */
+export declare function roomPlanTool(backend: {
+    commandPlan(sessionId: string, command: string): Promise<string>;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=tool-definition.d.ts.map

package/lib/types/tool-definition.js

@@ -0,0 +1,393 @@
+/**
+ * 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
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { coordinatorMember, isRoomLog } from './journal.js';
+/**
+ * Build the room_invite tool definition bound to the room service.
+ * @param backend - the room service.
+ * @returns a registry-ready tool definition.
+ */
+export 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.',
+        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.',
+            },
+            name: {
+                type: 'string',
+                required: true,
+                description: 'The member\'s @-addressing name: unique in this room, no whitespace, no "@".',
+            },
+            instructions: {
+                type: 'string',
+                required: true,
+                description: 'The member\'s role instructions (responsibilities, constraints, output expectations).',
+            },
+            firstTask: {
+                type: 'string',
+                description: 'Optional first task, dispatched to the member as soon as it joins.',
+            },
+            cwd: {
+                type: 'string',
+                description: 'Optional working directory for the member (empty: inherits the room session\'s cwd).',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    text: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+        },
+        // Invitations mutate only the room journal; two invites never conflict
+        // beyond a duplicate name, which the result text reports back.
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const agent = exec.agent;
+            if (agent === undefined)
+                return { text: 'room_invite requires a calling agent (exec.agent was undefined).' };
+            // No room gate: inviteMember PROMOTES the calling session into a room.
+            const result = await backend.inviteMember({
+                sessionId: agent.session.id,
+                provider: args.provider,
+                name: args.name,
+                instructions: args.instructions,
+                ...args.firstTask === undefined ? {} : { firstTask: args.firstTask },
+                ...args.cwd === undefined ? {} : { cwd: args.cwd },
+            }, '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.`
+                                : '';
+                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).`,
+            };
+        },
+    });
+}
+/**
+ * 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.
+ */
+export 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 }],
+        },
+        // Board writes mutate only the room journal; two writes never conflict
+        // beyond the validations the result text reports back.
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const agent = exec.agent;
+            if (agent === undefined)
+                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 === undefined || args.member === undefined) {
+                        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 === undefined ? {} : { 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 === undefined) {
+                        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 === undefined) {
+                        return { text: `room_task update requires taskId.${await openTasksHint()}` };
+                    }
+                    const result = await backend.updateTask({
+                        sessionId,
+                        taskId: args.taskId,
+                        ...args.title === undefined ? {} : { title: args.title },
+                        ...args.blockedBy === undefined ? {} : { 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.` };
+                }
+            }
+        },
+    });
+}
+/**
+ * Build the room_message tool definition bound to the room service: the main
+ * agent's way to hand a member a message/task — the model-facing equivalent
+ * of the human's `@member text`, minus the user bubble (the caller is the
+ * room's own agent, not the human).
+ * @param backend - the room service.
+ * @returns a registry-ready tool definition.
+ */
+export 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.',
+        parameters: {
+            member: {
+                type: 'string',
+                required: true,
+                description: 'The addressee\'s roster name (read room_read for current names; new rooms name the native member "dsh").',
+            },
+            text: {
+                type: 'string',
+                required: true,
+                description: 'The message text the member receives as its task.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    text: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+        },
+        // A dispatch mutates only the room journal; two messages never conflict
+        // beyond the roster validation the result text reports back.
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const agent = exec.agent;
+            if (agent === undefined)
+                return { text: 'room_message requires a calling agent (exec.agent was undefined).' };
+            // No room gate: messageMember PROMOTES the calling session into a room.
+            const sessionId = agent.session.id;
+            const result = await backend.messageMember({ sessionId, member: args.member, text: args.text });
+            if (!result.ok) {
+                if (result.error.code === 'member-not-found') {
+                    const state = await backend.getState({ sessionId });
+                    const names = state.ok ? state.value.members.map(member => member.name) : [];
+                    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 === '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.',
+            };
+        },
+    });
+}
+/** Native room tools use the same bounded context reader as the external MCP bridge. */
+export 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.',
+        parameters: {},
+        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) {
+            if (exec.agent === undefined)
+                return { text: 'room_read requires a calling agent.' };
+            try {
+                return { text: await backend.readRoomContext(exec.agent.session.id) };
+            }
+            catch (error) {
+                return { text: String(error) };
+            }
+        },
+    });
+}
+/** Formal planning uses the same strict command grammar exposed by room_read. */
+export function roomPlanTool(backend) {
+    return defineTool({
+        name: 'room_plan',
+        description: 'Organize a requested goal into stages and dependent tasks, submit evidence, review/rework results, and pause/resume. Read room_read for current plan and planCommands JSON schema. Ordinary small tasks use room_message without a formal goal. A native run finishing only submits a result; acceptance requires evidence review.',
+        parameters: { command: { type: 'string', required: true, description: 'JSON command matching room_read planCommands: action, requestId, expectedRevision and action fields. Create mode execute is for authorized execution; draft saves a proposal without dispatch.' } },
+        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) {
+            if (exec.agent === undefined)
+                return { text: 'room_plan requires a calling agent.' };
+            try {
+                return { text: await backend.commandPlan(exec.agent.session.id, args.command) };
+            }
+            catch (error) {
+                return { text: String(error) };
+            }
+        },
+    });
+}