@khorsheed/dsh-room 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,301 @@
+import { PlanService } from './plan-service.ts';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+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';
+export type * from './types.ts';
+export { MAIN_AGENT_MEMBER, ROOM_EVENT_TYPES } from './journal.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /**
+         * Room service owned by the room plugin: the Typert Remote gateway AND
+         * the in-process service face the local-agent bridge duck-type-calls
+         * (`receiveMemberMessage`). TypertRemoteService's Service base provides
+         * it under 'room'.
+         */
+        room: RoomService;
+    }
+}
+/** A resolved room session plus its replayed state, or the rejection. */
+type RoomLoad = {
+    readonly ok: true;
+    readonly session: Session;
+    readonly state: RoomState;
+} | {
+    readonly ok: false;
+    readonly error: RoomFailure;
+};
+/**
+ * room Remote service: promotion, roster management, the human @-message
+ * intake, the notification gate, the task board, 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).
+ */
+export declare class RoomService extends TypertRemoteService {
+    static inject: string[];
+    /** The dispatch engine executing this service's dispatch records. */
+    readonly plans: PlanService;
+    readonly engine: DispatchEngine;
+    private readonly handoffs;
+    /** sessionId → in-flight cold resume (mutations on a cold room dedupe). */
+    private readonly resumes;
+    /**
+     * @param ctx - host context carrying the session store.
+     */
+    constructor(ctx: Context);
+    /** Resolve a LIVE session as a room: presence, marker, replayed state. */
+    private load;
+    /**
+     * Read a session as a room without side effects: the live store first, then
+     * a persistence inspection (a cold room after a host restart answers from
+     * its durable log; nothing is attached or resumed on a read).
+     */
+    private loadCold;
+    /**
+     * Resolve a room for a MUTATION: the session must be live to take appends,
+     * and dispatch needs its agent live (the delegation facade resolves the
+     * parent through `ctx.agents.get` — live agents only). A cold room is
+     * cold-resumed through the agent factory, which republishes session +
+     * agent under the preset the log records; resumes dedupe per session.
+     */
+    private ensureLive;
+    /** One cold resume: refuse non-rooms before paying an agent composition. */
+    private resumeRoom;
+    /**
+     * Probe whether a session is a room: replay its event log looking for the
+     * `room/created` marker. Side-effect-free: a cold session answers from a
+     * persistence inspection, so opening any session never resumes its agent.
+     * @param request - session identity.
+     * @returns true when the session carries the marker (false for unknown sessions too).
+     */
+    isRoom(request: RoomIsRoomRequest): Promise<boolean>;
+    /**
+     * Resolve a session for a room WRITE, promoting it when it isn't a room
+     * yet: a live plain session gains the `room/created` identity marker and
+     * the main agent's roster seat (the promotion IS the entry model — the
+     * room-session-promotion proposal: any session an agent is invited into
+     * becomes a room). Idempotent — an existing room passes through untouched,
+     * and concurrent promotions converge on the log (the first `room/created`
+     * wins identity). A cold EXISTING room resumes through the normal path;
+     * a cold PLAIN session cannot be promoted sight-unseen (promotion writes
+     * on the live session, and the surfaces that promote — the open session's
+     * invite dialog, the room tools running in their own session — always hold
+     * it live), so it answers `not-a-room`. NOT a Remote — the surfaces reach
+     * it through the write paths (invite/messageMember); public so tests and a
+     * future manual "promote" surface share the one entry.
+     * @param sessionId - the session to write.
+     * @returns the live session plus replayed state, or the rejection.
+     */
+    ensureRoom(sessionId: SessionId): Promise<RoomLoad>;
+    /**
+     * List the invitable CLI providers: the local-agent roster with each
+     * harness's auth state, plus the delegation-facade verdict (absent facade =
+     * CLI members undispatchable; the dialog greys the section instead of
+     * failing). Harnesses without a delegation provider are record-only and
+     * are not invitable.
+     * @param _request - no parameters.
+     * @returns the provider list and the facade verdict.
+     */
+    listProviders(_request: RoomListProvidersRequest): Promise<RoomProviderList>;
+    /**
+     * Replay the room's journal into the derived state (roster, notification
+     * relays, task board, run states).
+     * @param request - room session identity.
+     * @returns the replayed state, or a rejection from the closed failure union.
+     */
+    getState(request: RoomGetStateRequest): Promise<RoomGetStateResult>;
+    /**
+     * Validate, PROMOTE (a plain session becomes a room — see ensureRoom), and
+     * journal an invitation: the name must be parseable by the
+     * composer @-grammar and unique, the provider non-blank AND a registered
+     * delegation provider (the classic slip is the harness name `kimi` where
+     * the family registered `kimi-cli` — validated against the roster's
+     * `delegationProvider` set, the same probe listProviders serves; a roster-
+     * less core skips the check, degrading to the old accept-anything), and
+     * (CLI members are undispatchable without it) the local-agent facade must
+     * be probed. A first task is journaled as a `room/dispatch` (auto-opening
+     * the member's in_progress task) and handed to the engine immediately —
+     * the receipt's `pendingFirstTask` means "dispatched". Shared by the
+     * Remote surface (`invitedBy: 'human'`) and the room_invite tool
+     * (`invitedBy: 'agent'`).
+     * @param request - room session, provider, name, optional cwd, instructions and first task.
+     * @param invitedBy - the invitation's origin.
+     * @returns the invitation receipt, or a rejection.
+     */
+    inviteMember(request: RoomInviteRequest, invitedBy: 'human' | 'agent', actorChildSessionId?: string): Promise<RoomInviteResult>;
+    /**
+     * Invite a CLI member (the human path; see inviteMember).
+     * @param request - room session, provider, name, optional cwd, instructions and first task.
+     * @returns the invitation receipt, or a rejection.
+     */
+    invite(request: RoomInviteRequest): Promise<RoomInviteResult>;
+    /**
+     * Update a member's editable fields: rename (validated like an invite name —
+     * unique, parseable; the main agent is the room itself and cannot be
+     * renamed), role instructions (null or a blank text CLEARS them — later
+     * dispatches inject none), the member-level cwd override (null or a
+     * blank text clears back to inheriting the room cwd; still roster-recorded
+     * only — the delegation facade's per-call cwd override is the family's open
+     * R2), and the intended model (null or a blank text clears it back to the
+     * harness default; roster-recorded intent — the first dispatch binds it as
+     * the facade start's `model` option, and the live member's immediate switch
+     * is the client's localAgentGateway `setMemberModel` call, not this one).
+     * An instructions edit rides the member's next dispatch as a context
+     * update (the CLI session itself is never rewritten); a rename migrates
+     * every name-keyed projection at replay (the journal fold moves the roster
+     * key, tasks' member/blockedBy, relays' from/to, and the runs key).
+     * @param request - room session, member name, and the fields to change.
+     * @returns the update receipt (the CURRENT name), or a rejection.
+     */
+    updateMember(request: RoomUpdateMemberRequest): Promise<RoomUpdateMemberResult>;
+    /** Native preparation creates no unrelated conversation turn and leaves the role unchanged. */
+    prepareMember(request: RoomPrepareMemberRequest): Promise<RoomPrepareMemberResult>;
+    private prepareMemberInRoom;
+    /** A human records the known result before releasing a crashed member's queued work. */
+    reconcileDelivery(request: RoomReconcileDeliveryRequest): Promise<RoomReconcileDeliveryResult>;
+    /** 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.
+     * @param request - room session, member name.
+     * @returns the removal receipt, or a rejection.
+     */
+    removeMember(request: RoomRemoveMemberRequest): Promise<RoomRemoveMemberResult>;
+    /**
+     * Post a human @-message into the room: leading `@name` tokens address
+     * members, and so does the request's `targets` list (the composer's
+     * mention-menu picks — explicit addressing wherever the `@name` sits); the
+     * two union before the roster check (a `room/dispatch` journal record,
+     * executed by the engine, and one auto-opened in_progress task per target).
+     * The human's raw text is
+     * FIRST appended as a standard `user/message` (source kind 'user' — the
+     * human typed it; the official messageDefinition classifies any other kind
+     * as a collapsed context-injection row, not the user bubble), so the words
+     * render as the official user bubble and enter the main agent's
+     * model-visible history. The append wakes nothing: turns start from
+     * prompt/followup calls, never from log appends (the agent is the log's
+     * writer, not a watcher). The `room/dispatch` record stays as pure
+     * bookkeeping (task board, dispatch cursors, replay) — it no longer drives
+     * any chat node. A BARE message is a structured `no-targets` rejection —
+     * defense only: the room composer releases bare messages to the official
+     * submit path (a normal main-agent turn) and never calls this Remote
+     * without addressing.
+     * @param request - room session, raw composer text, and the menu-picked addressees.
+     * @returns the parse receipt, or a rejection.
+     */
+    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.
+     */
+    messageMember(request: RoomMessageRequest, actorChildSessionId?: string): Promise<RoomMessageResult>;
+    /** Host-authenticated actor; model tool arguments never provide the room or sender. */
+    private isCurrentCoordinator;
+    /** 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. */
+    planCommand(request: {
+        sessionId: SessionId;
+        command: string;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /** The actor is derived from the calling native agent or authenticated bridge. */
+    commandPlan(sessionId: string, command: string, actorChildSessionId?: string): Promise<string>;
+    /** 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
+     * 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.
+     */
+    receiveMemberMessage(request: RoomMemberMessage): Promise<RoomMemberMessageReceipt>;
+    /**
+     * Confirm a pending relay: journal the confirmed edge and dispatch the
+     * notification to the recipient as a continuation (`{from} 给你的通知:
+     * {content}`); the engine marks the relay sent once the recipient's own
+     * session receives the prompt.
+     * @param request - room session, relay id.
+     * @returns the resolution receipt, or a rejection.
+     */
+    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.
+     */
+    dismissRelay(request: RoomRelayResolveRequest): Promise<RoomRelayResolveResult>;
+    /**
+     * 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.
+     */
+    addTask(request: RoomAddTaskRequest): Promise<RoomAddTaskResult>;
+    /**
+     * 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.
+     */
+    closeTask(request: RoomCloseTaskRequest): Promise<RoomCloseTaskResult>;
+    /**
+     * 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.
+     */
+    updateTask(request: RoomUpdateTaskRequest): Promise<RoomUpdateTaskResult>;
+    /**
+     * 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
+     * the roster section in every member prompt and drives the dock's goal
+     * capsule. Pure display/coordination text: it never dispatches anything.
+     * @param request - room session and goal text.
+     * @returns the now-current goal (absent after a clear), or a rejection.
+     */
+    setGoal(request: RoomSetGoalRequest): Promise<RoomSetGoalResult>;
+    /**
+     * Cancel a member's in-flight run through the local-agent facade. A hit
+     * journals the terminal `cancelled` edge immediately (the engine's own
+     * settle for that run then no-ops); a miss — no facade, no delegation
+     * handle, or nothing in flight — journals nothing and reports
+     * `cancelled: false`.
+     * @param request - room session, member name.
+     * @returns the cancellation receipt, or a rejection.
+     */
+    cancel(request: RoomCancelRequest): Promise<RoomCancelResult>;
+}
+export default RoomService;
+//# sourceMappingURL=index.d.ts.map