@khorsheed/dsh-room 0.2.2 → 0.2.4

package/lib/types/index.d.ts

@@ -1,11 +1,13 @@
 import { PlanService } from './plan-service.ts';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
 import type { LocalAgentMemberRun, MemberRoomCommand, MemberMessageOutcome } from '@khorsheed/dsh-local-agent/types';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { DispatchEngine } from './dispatch.ts';
-import type { RoomAddTaskRequest, RoomAddTaskResult, RoomCancelRequest, RoomCancelResult, RoomCloseTaskRequest, RoomCloseTaskResult, RoomPrepareMemberRequest, RoomPrepareMemberResult, RoomFailure, RoomSetCoordinatorRequest, RoomSetCoordinatorResult, RoomReconcileDeliveryRequest, RoomReconcileDeliveryResult, RoomGetStateRequest, RoomGetStateResult, RoomInviteRequest, RoomInviteResult, RoomIsRoomRequest, RoomListProvidersRequest, RoomMemberMessage, RoomMemberMessageReceipt, RoomMessageRequest, RoomMessageResult, RoomPostMessageRequest, RoomPostMessageResult, RoomProviderList, RoomRelayResolveRequest, RoomRelayResolveResult, RoomRemoveMemberRequest, RoomRemoveMemberResult, RoomSetGoalRequest, RoomSetGoalResult, RoomState, RoomUpdateMemberRequest, RoomUpdateMemberResult, RoomUpdateTaskRequest, RoomUpdateTaskResult } from './types.ts';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { RoomHelpLinkRequest, RoomHelpLinkResult, RoomCancelRequest, RoomCancelResult, RoomPrepareMemberRequest, RoomPrepareMemberResult, RoomFailure, RoomSetCoordinatorRequest, RoomSetCoordinatorResult, RoomReconcileDeliveryRequest, RoomReconcileDeliveryResult, RoomGetStateRequest, RoomGetStateResult, RoomInviteRequest, RoomInviteResult, RoomIsRoomRequest, RoomListProvidersRequest, RoomMemberMessage, RoomMemberMessageReceipt, RoomMessageRequest, RoomReleaseReportsRequest, RoomReleaseReportsResult, RoomSetTaskHintRequest, RoomStopJobRequest, RoomStopJobResult, RoomMessageResult, RoomSetSettingsRequest, RoomSetSettingsResult, RoomPostMessageRequest, RoomPostMessageResult, RoomProviderList, RoomRelayResolveRequest, RoomRelayResolveResult, RoomRemoveMemberRequest, RoomRemoveMemberResult, RoomRestoreMemberRequest, RoomRestoreMemberResult, RoomSetGoalRequest, RoomSetGoalResult, RoomState, RoomUpdateMemberRequest, RoomUpdateMemberResult, RoomAnswerApprovalRequest, RoomAnswerApprovalResult, RoomAnswerQuestionRequest, RoomAnswerQuestionResult, RoomQuestionItem } from './types.ts';
 export type * from './types.ts';
 export { MAIN_AGENT_MEMBER, ROOM_EVENT_TYPES } from './journal.ts';
 declare module '@deepseek-ai/cordis' {
@@ -28,9 +30,25 @@ type RoomLoad = {
     readonly ok: false;
     readonly error: RoomFailure;
 };
+/**
+ * Validate a member's `ask_user_question` questions: an array, or that array
+ * as JSON text (some models only send flat strings). Options may be labels or
+ * `{ label, description }`; `multi_select` (the host tool's spelling) or
+ * `multiSelect` marks a multi-pick question.
+ * @param raw - the tool argument.
+ * @returns the questions, or the error text the model reads.
+ */
+export declare function parseQuestions(raw: unknown): readonly RoomQuestionItem[] | string;
+/**
+ * What a new coordinator reads once, on its first round: who handed over,
+ * the goal and open tasks, and where to look. The conversation itself is
+ * not replayed — a member that was in the room has most of it already, and
+ * re-sending it cost a five-figure prompt; it reads the room when it needs to.
+ */
+export declare function handoffText(_events: readonly SessionEvent[], state: RoomState, sessionId: string, from: string, to: string): string;
 /**
  * room Remote service: promotion, roster management, the human @-message
- * intake, the notification gate, the task board, and run cancellation. A
+ * intake, the notification gate, tasks, and run cancellation. A
  * room IS a normal session; the journal is its only state. A room is never
  * CREATED apart from a session — inviting an agent into any session promotes
  * it (see ensureRoom; the room-session-promotion proposal).
@@ -41,6 +59,11 @@ export declare class RoomService extends TypertRemoteService {
     readonly plans: PlanService;
     readonly engine: DispatchEngine;
     private readonly handoffs;
+    /**
+     * The terminal run-state fields Context Lens correlates on: the child
+     * identity plus the round the run reached (live sessions only).
+     */
+    private terminalRunStateFields;
     /** sessionId → in-flight cold resume (mutations on a cold room dedupe). */
     private readonly resumes;
     /**
@@ -100,7 +123,75 @@ export declare class RoomService extends TypertRemoteService {
      * @param _request - no parameters.
      * @returns the provider list and the facade verdict.
      */
-    listProviders(_request: RoomListProvidersRequest): Promise<RoomProviderList>;
+    listProviders(request: RoomListProvidersRequest): Promise<RoomProviderList>;
+    /** A session's own mode (preset id), live or cold; undefined when unreadable. */
+    private sessionPreset;
+    /** The host's agent presets for a native member, or undefined without a registry. */
+    private listPresets;
+    /** The composer's task tags, consumed by the human's next message in that room. */
+    private readonly taskHints;
+    private consumeTaskHint;
+    /**
+     * File a new human message under a task: the composer's tag when given
+     * (a task root id, or `new`), otherwise — while some task is still open —
+     * the decision model's suggestion; with neither it starts a task of its own.
+     * A filing other than its own task is journaled as a `room/task-link`.
+     * @returns the task root id and, for a model suggestion, the note the coordinator should read.
+     */
+    private fileHumanMessage;
+    /**
+     * Tag the human's next message with a task (the task page's 追问 /
+     * 新任务), or clear the tag.
+     * @param request - room session and the task root id, `new`, or null.
+     * @returns acknowledgement.
+     */
+    setTaskHint(request: RoomSetTaskHintRequest): Promise<{
+        readonly ok: true;
+    }>;
+    /**
+     * Stop a whole task: running rounds of its deliveries are cancelled (the
+     * same cancel the stop button uses), queued and held ones never run, and
+     * ordinary rounds whose outcome a restart lost close as cancelled — the
+     * human gave up on them — which unblocks those members' later messages.
+     * @param request - room session and the task root id.
+     * @returns how many deliveries were stopped.
+     */
+    stopJob(request: RoomStopJobRequest): Promise<RoomStopJobResult>;
+    /**
+     * Route the human's edited message (message-tools replaced the bubble in
+     * place) to the room: the original message's dispatch stops — editing is
+     * changing one's mind — and the edited text dispatches like a new human
+     * message, filed under the original's task, without a second bubble.
+     * Idempotent per edit trigger.
+     */
+    private routeEdit;
+    /**
+     * The human messaging a member moves on from that member's ordinary
+     * rounds a restart left uncertain: they close as not finished, so the new
+     * message runs instead of queueing behind a reconciliation. Formal-goal
+     * attempts keep their explicit reconciliation.
+     */
+    private moveOnFromLostRounds;
+    /**
+     * Where a member's next send belongs: the task and delivery it is working
+     * on (a member inside a room round), or — for the room's own agent answering
+     * the human directly — the task of the human message that started its turn
+     * (`trigger`, which the coordinator may re-file with `task`).
+     */
+    private sendContext;
+    /** The room and member whose held reports a session's agent should carry. */
+    private heldTarget;
+    /**
+     * A native member's own session calling a room tool: the tools see the
+     * child session, so route to its room with the child as the authenticated
+     * actor instead of promoting the child into a room of its own.
+     * @param sessionId - the calling agent's session.
+     * @returns the room and actor, or undefined when the caller is no native member.
+     */
+    nativeRoute(sessionId: string): {
+        readonly roomId: SessionId;
+        readonly actor: string;
+    } | undefined;
     /**
      * Replay the room's journal into the derived state (roster, notification
      * relays, task board, run states).
@@ -160,12 +251,25 @@ export declare class RoomService extends TypertRemoteService {
     /** Explicit human role change; state is committed only after readiness and idle checks. */
     setCoordinator(request: RoomSetCoordinatorRequest): Promise<RoomSetCoordinatorResult>;
     /**
-     * Remove a member from the roster. An in-flight run is NOT interrupted
-     * here — cancel() first when the member is running.
+     * Remove a member and settle everything that depended on it, so the
+     * confirmation's promises hold: a running round is stopped first (the same
+     * cancel the stop button uses), queued messages to it are cancelled, every
+     * member waiting for one of its reports is told it will not come, and only
+     * then does it leave the roster. Its own session and history stay;
+     * {@link restoreMember} brings it back onto them.
      * @param request - room session, member name.
-     * @returns the removal receipt, or a rejection.
+     * @returns what the removal did, or a rejection.
      */
     removeMember(request: RoomRemoveMemberRequest): Promise<RoomRemoveMemberResult>;
+    /**
+     * Undo a removal: the member rejoins under its old identity, provider,
+     * role, instructions and native session, so its memory carries on. Work
+     * the removal cancelled stays cancelled. Rejected when the name was taken
+     * in between or the member was never removed.
+     * @param request - room session, the removed member's name.
+     * @returns the restored name, or a rejection.
+     */
+    restoreMember(request: RoomRestoreMemberRequest): Promise<RoomRestoreMemberResult>;
     /**
      * Post a human @-message into the room: leading `@name` tokens address
      * members, and so does the request's `targets` list (the composer's
@@ -190,18 +294,85 @@ export declare class RoomService extends TypertRemoteService {
      */
     postMessage(request: RoomPostMessageRequest): Promise<RoomPostMessageResult>;
     /**
-     * Dispatch one message to one member (host-only — the `room_message` tool's
-     * path; the model-facing equivalent of the human's `@member text`). Same
-     * dispatch internals as postMessage minus the user/message bubble: the
-     * caller is the room's own main agent, so the text must NOT wear the human
-     * bubble (source kind 'user' would misattribute it). The dispatch record
-     * and the auto-opened in_progress task journal as usual.
-     * @param request - room session, addressee, text.
-     * @returns the dispatch receipt, or a rejection.
+     * Send one message from a member to another (host-only — the `room_message`
+     * tool and the bridge's `member_message`/`room_message` land here; the
+     * human's path is postMessage). Any member may message any other: the
+     * coordinator's sends journal as `coordinator` dispatches, everyone else's
+     * as `member` ones. A `task` (default) has the recipient's final reply
+     * reported back to the sender; a `notify` is FYI. The room's settings may
+     * hold the message for the human instead (see messaging.ts).
+     * @param request - room session, addressee, text, kind, optional reply reference.
+     * @param actorChildSessionId - the authenticated CLI sender; absent = the room's own agent.
+     * @returns the delivery receipt (with its `m<seq>` id) or the hold, or a rejection.
      */
     messageMember(request: RoomMessageRequest, actorChildSessionId?: string): Promise<RoomMessageResult>;
     /** Host-authenticated actor; model tool arguments never provide the room or sender. */
     private isCurrentCoordinator;
+    private readonly equipped;
+    /** Register the helper tools on one helper agent (agent-local: they unwind with it). */
+    private equipHelper;
+    /** A room's display title (its latest `session/title`), else its id. */
+    private roomTitle;
+    /**
+     * Resolve the session a member names: an `@[…](dsh-session:…)` mention, a
+     * session id, or a title (through the host's session-reference discovery).
+     */
+    private resolveHelpTarget;
+    /**
+     * A member asks another session for help, or writes again on a thread
+     * (the `room_help` tool). The first ask of a session the human never
+     * @-mentioned in this room waits for the human's go-ahead.
+     * @param request - the calling session, the target session (new thread) or help id (existing), the text.
+     * @param caller - the calling agent.
+     * @returns the tool's text result.
+     */
+    askHelp(request: {
+        readonly sessionId: string;
+        readonly session?: string;
+        readonly member?: string;
+        readonly help?: string;
+        readonly text: string;
+    }, caller: Agent | undefined, actorChildSessionId?: string): Promise<string>;
+    /**
+     * Hand a help request (or a follow-up on it) to another room: its named
+     * member, else its coordinator, as a `help`-origin dispatch — held like any
+     * agent message while that room is paused — and shown on that room's
+     * timeline. The member's final reply comes back through {@link helpSettled}.
+     */
+    private deliverToRoom;
+    /**
+     * A help dispatch in this room settled: its final reply (or its failure)
+     * goes back to the asking room's thread.
+     * @param room - the room that was asked.
+     * @param dispatchSeq - the settled dispatch.
+     * @param outcome - the run's outcome.
+     */
+    private helpSettled;
+    /** Queue one help message in the helper's session (waking it when cold) and watch its turn. */
+    private deliverHelp;
+    /**
+     * After the helper's turn: a turn that never claimed the message failed the
+     * thread; one that ended without the reply or question tool hands over its
+     * last answer as the reply.
+     */
+    private watchHelp;
+    /** A help request reached the helper's turn: a queued thread is running now. */
+    private markHelpRunning;
+    /** Journal a helper's question or reply and hand it to the asking member. */
+    private recordHelperMessage;
+    /**
+     * The helper's `room_help_reply` / `room_help_ask`: find the thread from
+     * the help requests in the helper's own log, then carry the message back.
+     * @param agent - the helper agent.
+     * @param request - thread (optional when only one), kind, text, handoff.
+     * @returns the tool's text result.
+     */
+    helperMessage(agent: Agent, request: {
+        help?: string;
+        kind: 'question' | 'reply';
+        text: string;
+        handoff?: string;
+    }): Promise<string>;
     /** Bounded shared room context for native and external model tools; reading never wakes an agent. */
     readRoomContext(sessionId: string): Promise<string>;
     /** Human UI and native/external tools share the same durable transition service. */
@@ -216,23 +387,77 @@ export declare class RoomService extends TypertRemoteService {
     }>;
     /** The actor is derived from the calling native agent or authenticated bridge. */
     commandPlan(sessionId: string, command: string, actorChildSessionId?: string): Promise<string>;
+    /**
+     * The mode of an external member — the host preset whose plugin tools its
+     * bridge offers (local-agent's preset tool host runs them) — with its
+     * working directory. Host method for the member channel, never a Remote.
+     * @param actor - the authenticated member run.
+     * @returns the mode, or undefined when the member has none or is not here.
+     */
+    memberMode(actor: LocalAgentMemberRun): Promise<{
+        readonly preset: string;
+        readonly cwd?: string;
+    } | undefined>;
+    /** Pending member tool approvals this process can still answer: approval id → its waiting call. */
+    private readonly approvalWaiters;
+    /** Close approvals no waiting call stands behind any more (a restart lost it). */
+    private expireApprovals;
+    /**
+     * A CLI member's mode tool needs the human's approval: ask in the room's
+     * conversation (a 允许 / 拒绝 line) and resolve when the human answers,
+     * the call is cancelled, or the room is gone. Host method for the member
+     * channel (local-agent's approval hook), never a Remote.
+     * @param actor - the authenticated member run.
+     * @param request - the tool, an optional reason, and the call's signal.
+     * @returns the approval outcome the tool registry expects.
+     */
+    askMemberApproval(actor: LocalAgentMemberRun, request: {
+        readonly toolName: string;
+        readonly reason?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'>;
+    /**
+     * The human answers a member's tool approval from the room.
+     * @param request - room session, approval id, allow once or reject.
+     * @returns ok, or `approval-not-pending` when it already ended.
+     */
+    answerApproval(request: RoomAnswerApprovalRequest): Promise<RoomAnswerApprovalResult>;
+    /** Pending member questions this process can still answer: question id → its waiting call. */
+    private readonly questionWaiters;
+    /** Close question cards no waiting call stands behind any more (a restart lost it). */
+    private expireQuestions;
+    /**
+     * A member asks the human questions (its bridge's `ask_user_question`):
+     * journal a pick-to-answer card in the room and wait for the answer, the
+     * timeout, or the room going away.
+     * @param session - the live room session.
+     * @param member - the asking member.
+     * @param questions - the validated questions.
+     * @param timeoutMs - how long the call waits before it gives up.
+     * @returns the answers, or undefined when nobody answered.
+     */
+    private askQuestions;
+    /**
+     * The human answers a member's question card from the room.
+     * @param request - room session, card id, one answer per question.
+     * @returns ok, or `question-not-pending` when it already ended.
+     */
+    answerQuestion(request: RoomAnswerQuestionRequest): Promise<RoomAnswerQuestionResult>;
     /** Shared backend for external MCP room tools. Not exposed as a browser Remote. */
     receiveMemberCommand(actor: LocalAgentMemberRun, command: MemberRoomCommand): Promise<MemberMessageOutcome>;
     /**
-     * The notification gate entry, verbatim-frozen contract for the local-agent
-     * family bridge (`ctx.get('room')` + duck-typed call). The call crosses an
-     * untyped package boundary, so the message shape is validated at runtime:
-     * a malformed message throws (the bridge treats a rejection as "room does
+     * The bridge's `member_message` entry (contract shared with the local-agent
+     * family: `ctx.get('room')` + duck-typed call). The call crosses an untyped
+     * package boundary, so the message shape is validated at runtime: a
+     * malformed message throws (the bridge treats a rejection as "room does
      * not claim this" and delivers directly) instead of poisoning the journal.
-     * `from`/`to` arrive as roster names OR member child session ids (the
-     * bridge cannot speak names for the sender — only room owns the roster);
-     * both are normalized to roster names when resolvable, so the pending card
-     * and the delivery text (`{from} 给你的通知: …`) read as names. Phase 1's
-     * gate is ALWAYS human confirmation: the relay is journaled pending and
-     * the sender receives 'pending-confirm' (never 'sent' — the bridge keeps
-     * the member's conclusion honest). A non-room parent session throws.
-     * @param request - sender, recipient, content, the shared parent session, provenance.
-     * @returns the gate receipt.
+     * A roster sender (resolved by child session id + provider, never
+     * self-reported) goes through {@link messageMember}: delivered at once or
+     * held by the room's settings. The receipt tells the model what happened
+     * (`sent #m12 …` / `pending-confirm …`). A sender the roster does not know
+     * keeps the legacy pending relay.
+     * @param request - sender, recipient, content, the shared parent session, provenance, kind.
+     * @returns the receipt quoted back to the sending model.
      */
     receiveMemberMessage(request: RoomMemberMessage): Promise<RoomMemberMessageReceipt>;
     /**
@@ -245,38 +470,53 @@ export declare class RoomService extends TypertRemoteService {
      */
     confirmRelay(request: RoomRelayResolveRequest): Promise<RoomRelayResolveResult>;
     /**
-     * Dismiss a pending relay: the notification never reaches anyone.
-     * @param request - room session, relay id.
-     * @returns the resolution receipt, or a rejection.
+     * Deliver a held message as the dispatch it would have been. `force`
+     * (the human's confirm) skips the hold rules; otherwise (resuming a paused
+     * room) they are re-checked, so a message may be held again for another
+     * reason — the old hold is then superseded (dismissed) by the new one.
+     * The caller flushes.
      */
-    dismissRelay(request: RoomRelayResolveRequest): Promise<RoomRelayResolveResult>;
+    private release;
     /**
-     * Add a task to a member's board lane (the human's management entry; @-
-     * dispatches auto-open in_progress tasks, this opens a pending one).
-     * `blockedBy` names the member the task waits on (display only — it never
-     * dispatches anything); it must resolve against the roster.
-     * @param request - room session, member, title, optional blockedBy.
-     * @returns the new task's id, or a rejection.
+     * Hand a member the reports the gate holds for it now (the room's
+     * 「现在交给」 button).
+     * @param request - room session, member name.
+     * @returns whether anything was held.
+     */
+    releaseReports(request: RoomReleaseReportsRequest): Promise<RoomReleaseReportsResult>;
+    /**
+     * Change the room's collaboration settings (any subset). Resuming a paused
+     * room releases everything the pause held, in order.
+     * @param request - room session and the fields to change.
+     * @returns the settings after the change, or a rejection.
      */
-    addTask(request: RoomAddTaskRequest): Promise<RoomAddTaskResult>;
+    setSettings(request: RoomSetSettingsRequest): Promise<RoomSetSettingsResult>;
     /**
-     * Close an open task (done by default, or cancelled). A failed task is
-     * still open for closing — that is the human's dismiss path after a
-     * failed run (the board's [关闭] passes 'cancelled').
-     * @param request - room session, task id, optional closing status.
-     * @returns the closed task's id, or a rejection.
+     * Keep an outside session on the member list (「加入房间成员」): only a
+     * shortcut for asking it — it stays in its own session, asks still go
+     * through room_help, and its usage stays its own.
+     * @param request - room session, the outside session and its title.
+     * @returns ok, or a rejection.
      */
-    closeTask(request: RoomCloseTaskRequest): Promise<RoomCloseTaskResult>;
+    linkSession(request: RoomHelpLinkRequest): Promise<RoomHelpLinkResult>;
     /**
-     * Edit an open task's title and/or blockedBy (the `room_task` tool's update
-     * action; journaled as `room/task-edited`, status changes stay on
-     * closeTask). Host method only — the capsule UI edits nothing but the goal.
-     * `blockedBy: null` clears the wait; a string must resolve against the
-     * roster. A closed task takes no edits.
-     * @param request - room session, task id, and at least one edited field.
-     * @returns the edited task's id, or a rejection.
+     * Take an outside session off the member list (its own session is untouched).
+     * @param request - room session, the outside session.
+     * @returns ok, or `member-not-found` when it was not on the list.
      */
-    updateTask(request: RoomUpdateTaskRequest): Promise<RoomUpdateTaskResult>;
+    unlinkSession(request: RoomHelpLinkRequest): Promise<RoomHelpLinkResult>;
+    /**
+     * Dismiss the 加入房间成员 hint for one outside session (it never shows again).
+     * @param request - room session, the outside session.
+     * @returns ok.
+     */
+    dismissHelpNudge(request: RoomHelpLinkRequest): Promise<RoomHelpLinkResult>;
+    /**
+     * Dismiss a pending relay: the notification never reaches anyone.
+     * @param request - room session, relay id.
+     * @returns the resolution receipt, or a rejection.
+     */
+    dismissRelay(request: RoomRelayResolveRequest): Promise<RoomRelayResolveResult>;
     /**
      * Set (or, with a blank text, clear) the room's goal. The goal is one
      * journaled line — the latest `room/goal` event wins; it rides the top of