dsh-team-rooms 1.0.0

package/lib/types/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * dsh-team-rooms: persistent, cross-session team rooms for DeepSeek Harness.
+ *
+ * A room is `{members (each an independent session), message bus
+ * (directed/broadcast), task board, shared timeline}` persisted in the
+ * harness's own storage layer — the `team_rooms` storage domain (SQLite or
+ * JSONL backend; the deployment chooses, the plugin adds no service of its
+ * own) — and it recovers across DSH restarts. The `/room` command family
+ * drives rooms from the user; the model gets eight `room_*` tools;
+ * cross-member task handoffs route through the official approval seam; and
+ * member sessions receive a one-line role-statement brief (Minimal persona
+ * style) on join and resume.
+ *
+ * Model-visible ⟺ recorded: every delivered room message is a durable
+ * `user/message` in the member's own session log, and the shared timeline
+ * mirrors as log-only `team-room/fact` events folded by the `teamRoom`
+ * projection the settings panel renders. The storage domain stays the
+ * cross-session authority; the projection is each member's own reconstructed
+ * copy.
+ *
+ * Extracted verbatim from `dsh-background-agents` 0.9.6, whose background-agent
+ * half is superseded by native DSH continuable subagents. Three identity
+ * strings must stay byte-identical to that version so existing profiles keep
+ * working: the storage domain `team_rooms`, the projection key `teamRoom`,
+ * and the session event type `team-room/fact` (plus the client slot id
+ * `team-rooms`).
+ *
+ * This half never touches `ctx.subagents`: no room operation spawns or steers
+ * a child agent, so the package carries no subagent dependency at all.
+ *
+ * @module dsh-team-rooms
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+/** The cordis row name; the mounted graph id and the logger channel share it. */
+export declare const name = "team-rooms";
+/** Hard service dependencies: the tool registry, the agent registry, and the session store. */
+export declare const inject: string[];
+/**
+ * Lifecycle policy. Every tunable is a validated Config field: thresholds and
+ * retentions belong in cordis.yml, never in code. Nothing is required (rooms
+ * mount wherever the storage domain is composed); the Schemastery schema
+ * materializes the documented defaults from {@link DEFAULTS}, and direct
+ * apply() callers keep the same defaults.
+ */
+export interface Config {
+    /** Hard cap on team rooms across the profile. */
+    maxRooms?: number;
+    /** Hard cap on members per room. */
+    maxMembersPerRoom?: number;
+    /** Hard cap on rooms one member session may join. */
+    maxRoomsPerMember?: number;
+    /** Bus messages kept per room (the message retention window). */
+    busRetention?: number;
+    /** Timeline events kept per room. */
+    timelineRetention?: number;
+    /** Completed tasks kept per room; older `done` rows are pruned. */
+    taskRetention?: number;
+    /** Hard cap on one room message's text (rejected above, never truncated). */
+    maxMessageChars?: number;
+    /** Inject the short room brief into member sessions (join + resume). */
+    injectRoomBrief?: boolean;
+    /**
+     * How long the `team_rooms` storage-domain open may take before every
+     * room operation fails loud (`store-unavailable`) instead of hanging.
+     */
+    roomOpenTimeoutMs?: number;
+    /**
+     * Force the log-only `team-room/fact` events even on hosts that drop the
+     * `ignorable` envelope marker (every released rc line through
+     * `0.1.0-rc.8`). Deliberately dangerous: unmarked fact events make
+     * sessions unresumable on stricter harness builds. Default `false` — the
+     * runtime detects such hosts and skips fact appends (the `teamRoom`
+     * projection degrades to an empty fold; the durable store and the
+     * model-visible deliveries keep working).
+     */
+    allowUnmarkedFacts?: boolean;
+    /** Cross-ecosystem inbound bridge (P2) policy; absent = disabled. */
+    inbound?: InboundConfig;
+}
+/** Cross-ecosystem inbound bridge (P2) policy. */
+export interface InboundConfig {
+    /**
+     * Enable the newline-delimited JSON-RPC 2.0 stdio inbound bridge that lets
+     * external agent runtimes (OpenAI Agents SDK / CrewAI) publish into team
+     * rooms. Default `false` (fail-closed — the bridge never spawns unless
+     * explicitly enabled).
+     */
+    enabled?: boolean;
+    /**
+     * External runtime launch command. When `enabled` and present, the plugin
+     * spawns it and listens for notifications on its stdout. Absent or
+     * unspawnable = the bridge stays dormant with a logged warning.
+     */
+    command?: string;
+}
+/**
+ * The single source of truth for every optional policy default: the schema
+ * materializes from it and apply() falls back to it, so the two can never
+ * drift apart.
+ */
+export declare const DEFAULTS: {
+    readonly maxRooms: 16;
+    readonly maxMembersPerRoom: 8;
+    readonly maxRoomsPerMember: 4;
+    readonly busRetention: 200;
+    readonly timelineRetention: 500;
+    readonly taskRetention: 50;
+    readonly maxMessageChars: 4000;
+    readonly injectRoomBrief: true;
+    readonly roomOpenTimeoutMs: 15000;
+    readonly allowUnmarkedFacts: false;
+    readonly inbound: {
+        readonly enabled: false;
+    };
+};
+export declare const Config: Schema<Config>;
+/**
+ * Mount the room hub, the eight `room_*` tools, the `/room` command family,
+ * the `teamRoom` projection unit, and the room prompt section.
+ * @param ctx - context carrying the tool registry, the agent registry, and the session store.
+ * @param config - room policy (Schemastery-validated).
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/room/commands.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The human-facing `/room` command family: create, join, leave, list, send,
+ * tasks, and the task board subcommands (add / assign / claim / done). The
+ * command executes directly against the receiving session's agent — it never
+ * goes through the model — and every write lands on the shared durable room
+ * store. Because the human typed the command, command-side handoffs are
+ * already user-authorized (the model-facing `room_transfer_task` tool is
+ * what routes through the approval seam).
+ *
+ * @module dsh-team-rooms/room/commands
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type RoomHub } from './hub.js';
+/**
+ * Register the `/room` command when the harness composes the command
+ * registry. The handler runs outside any model turn, so it performs the
+ * mutations directly (the typing user is the authorizer). The command surface
+ * is optional: without it the room_* tools still work from the model side.
+ * @returns the exact command disposer, or undefined when no command registry
+ *   is composed.
+ */
+export declare function registerRoomCommand(ctx: Context, hub: RoomHub): (() => void) | undefined;
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/room/domain.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The `team_rooms` storage-domain declaration: rooms, the message bus, the
+ * task board, and the shared timeline as four KV tables over the harness's
+ * own storage layer (SQLite or JSONL backend — the deployment chooses; the
+ * plugin adds no service of its own). Records are validated at the durable
+ * boundary by the same zod schemas the projection and the client share.
+ *
+ * The domain's single write chain is the ordering authority: every bus
+ * append and cursor bump queues on it, so concurrent posters can never
+ * interleave a read-modify-write.
+ *
+ * @module dsh-team-rooms/room/domain
+ */
+/** Branded-ish key aliases: append-table keys are plain `${roomId}/${…}` strings. */
+export type RoomKey = string & {
+    readonly __roomKey?: never;
+};
+export type AppendKey = string & {
+    readonly __appendKey?: never;
+};
+/**
+ * The domain spec: identity, format version, and the four declared tables.
+ * The same schemas validate every record at the durable read boundary.
+ */
+export declare const teamRoomsDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        rooms: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<RoomKey, {
+            name: string;
+            roomId: string;
+            createdAt: number;
+            members: {
+                sessionId: string;
+                role: "owner" | "member";
+                joinedAt: number;
+                lastDeliveredSeq: number;
+                lastFactSeq: number;
+            }[];
+            busNext: number;
+            timelineNext: number;
+        }>;
+        bus: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<AppendKey, {
+            text: string;
+            roomId: string;
+            createdAt: number;
+            seq: number;
+            senderSessionId: string;
+            toSessionId?: string | undefined;
+        }>;
+        tasks: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<AppendKey, {
+            status: "todo" | "in-progress" | "done";
+            title: string;
+            roomId: string;
+            createdAt: number;
+            taskId: string;
+            description: string;
+            assigneeSessionId: string | null;
+            createdBy: string;
+            updatedAt: number;
+            completedAt?: number | undefined;
+        }>;
+        timeline: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<AppendKey, {
+            at: number;
+            data: Record<string, unknown>;
+            roomId: string;
+            seq: number;
+            kind: "room-created" | "member-joined" | "member-left" | "message-posted" | "message-directed" | "task-created" | "task-claimed" | "task-assigned" | "task-completed";
+        }>;
+    };
+};
+//# sourceMappingURL=domain.d.ts.map

package/lib/types/room/events.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The room-owned durable fact event: `team-room/fact`, appended to every
+ * MEMBER session log as a log-only record stamped with the envelope's
+ * `ignorable: true` marker (the same discipline as the background-agents
+ * fact channel). Two invariants hold:
+ *
+ * - model-visible ⟺ recorded: the messages the member's model sees are
+ *   delivered through the official inbox (`agent.followup`/`agent.inject`,
+ *   durable `user/message` events), while the shared timeline rides these
+ *   log-only facts — the room store (`team_rooms` domain) stays the
+ *   cross-session authority;
+ * - catch-up completeness: members offline while a fact landed receive every
+ *   missed fact (and bus message) in store order on their next activation, so
+ *   the `teamRoom` projection always reconstructs the shared view from the
+ *   member's own log.
+ *
+ * Every timeline-bearing fact carries the canonical store `timelineSeq`, so
+ * the folded view orders exactly like the room store.
+ *
+ * @module dsh-team-rooms/room/events
+ */
+import type { RoomMember, TaskRecord, TimelineEvent } from './schema.js';
+/** The log-only fact event type this plugin appends to member sessions. */
+export declare const TEAM_ROOM_FACT: "team-room/fact";
+/** One structured room fact, discriminated on `kind`. */
+export type TeamRoomFact = {
+    /**
+     * This session became a member (create or join). Carries the full
+     * snapshot — room identity, member list, open tasks, and the retained
+     * timeline — so a cold member log reconstructs the shared view without
+     * reading the room store.
+     */
+    readonly kind: 'room-joined';
+    readonly roomId: string;
+    readonly name: string;
+    readonly createdAt: number;
+    readonly members: RoomMember[];
+    readonly tasks: TaskRecord[];
+    readonly timeline: TimelineEvent[];
+} | {
+    /** Another session joined the room. */
+    readonly kind: 'member-joined';
+    readonly roomId: string;
+    readonly sessionId: string;
+    readonly role: RoomMember['role'];
+    readonly joinedAt: number;
+    readonly timelineSeq: number;
+} | {
+    /** A member left (or the room was deleted). */
+    readonly kind: 'member-left';
+    readonly roomId: string;
+    readonly sessionId: string;
+    readonly timelineSeq: number;
+} | {
+    /** One bus message; `toSessionId` marks a directed delivery. */
+    readonly kind: 'message-posted';
+    readonly roomId: string;
+    readonly seq: number;
+    readonly timelineSeq: number;
+    readonly senderSessionId: string;
+    readonly toSessionId?: string;
+    readonly text: string;
+    readonly createdAt: number;
+} | {
+    /** A new task entered the board. */
+    readonly kind: 'task-created';
+    readonly roomId: string;
+    readonly taskId: string;
+    readonly title: string;
+    readonly description: string;
+    readonly assigneeSessionId: string | null;
+    readonly createdBy: string;
+    readonly createdAt: number;
+    readonly timelineSeq: number;
+} | {
+    /** A member claimed a task (assignee + in-progress). */
+    readonly kind: 'task-claimed';
+    readonly roomId: string;
+    readonly taskId: string;
+    readonly assigneeSessionId: string;
+    readonly at: number;
+    readonly timelineSeq: number;
+} | {
+    /** The owner handed a task to another member. */
+    readonly kind: 'task-assigned';
+    readonly roomId: string;
+    readonly taskId: string;
+    readonly assigneeSessionId: string;
+    readonly bySessionId: string;
+    readonly at: number;
+    readonly timelineSeq: number;
+} | {
+    /** A task reached `done`. */
+    readonly kind: 'task-completed';
+    readonly roomId: string;
+    readonly taskId: string;
+    readonly at: number;
+    readonly timelineSeq: number;
+};
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        [TEAM_ROOM_FACT]: TeamRoomFact;
+    }
+}
+//# sourceMappingURL=events.d.ts.map

package/lib/types/room/hub.d.ts

@@ -0,0 +1,243 @@
+/**
+ * RoomHub: the host-side service behind team rooms. It opens the
+ * `team_rooms` storage domain, owns every room mutation (membership, the
+ * message bus, the task board, the timeline), and drives delivery:
+ *
+ * - every write queues on ONE hub chain (the domain's single write chain is
+ *   the ordering authority — concurrent posters cannot interleave a
+ *   read-modify-write, and bus seqs mint strictly in commit order);
+ * - model-visible delivery goes through the official inbox
+ *   (`agent.followup` wakes live members; offline members receive their
+ *   backlog through `agent.inject` when their session next starts), so every
+ *   model-visible room message is a durable `user/message` event in the
+ *   member's own session log — model-visible ⟺ recorded;
+ * - the shared timeline mirrors into every member's log as log-only
+ *   `team-room/fact` events (ignorable), so the `teamRoom` projection
+ *   reconstructs the room view from each member's own durable log;
+ * - per-member delivery is at-least-once and ordered: a crash between bus
+ *   commit and delivery re-delivers on catch-up (the cursor only advances
+ *   after delivery), and per-member chains serialize delivery order.
+ *
+ * @module dsh-team-rooms/room/hub
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { SessionId, type Session } from '@deepseek-ai/dsh-session';
+import { type BusMessage, type RoomMember, type RoomRecord, type TaskRecord, type TimelineEvent } from './schema.js';
+import type { FactAppender } from '../facts.js';
+/** Tunables the room feature honors; every threshold is a validated Config field. */
+export interface RoomConfig {
+    /** Hard cap on rooms across the profile. */
+    readonly maxRooms: number;
+    /** Hard cap on members per room. */
+    readonly maxMembersPerRoom: number;
+    /** Hard cap on rooms one member session may join. */
+    readonly maxRoomsPerMember: number;
+    /** Bus entries kept per room (the message retention window). */
+    readonly busRetention: number;
+    /** Timeline entries kept per room. */
+    readonly timelineRetention: number;
+    /** Completed tasks kept per room (older `done` rows are pruned). */
+    readonly taskRetention: number;
+    /** Hard cap on one bus message's text (rejected above, never truncated). */
+    readonly maxMessageChars: number;
+    /** Inject the short room brief into member sessions (join + resume). */
+    readonly injectRoomBrief: boolean;
+    /**
+     * How long the `team_rooms` storage-domain open may take before every
+     * room operation fails loud (`store-unavailable`) instead of hanging
+     * forever (a stuck storage provider used to leave `/room` commands
+     * without a `command/done`).
+     */
+    readonly roomOpenTimeoutMs: number;
+}
+/** A domain-level rejection with a stable code; tools and commands render it. */
+export declare class RoomError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Read face of the live agent registry (kept narrow for tests). */
+export interface LiveAgents {
+    get(id: SessionId): Agent | undefined;
+}
+/** Read face of the live session store (kept narrow for tests). */
+export interface LiveSessions {
+    get(id: SessionId): Session | undefined;
+}
+/** Bus record the hub mints from a committed post. */
+export interface PostedMessage {
+    readonly roomId: string;
+    readonly seq: number;
+    readonly senderSessionId: string;
+    readonly toSessionId?: string;
+    readonly text: string;
+    readonly createdAt: number;
+}
+/**
+ * The team-room service. Constructed in apply() with the validated room
+ * policy once the storage domain is available; {@link open} opens the
+ * `team_rooms` storage domain and the owning fiber closes it.
+ */
+export declare class RoomHub extends Service {
+    private readonly config;
+    private readonly agents;
+    private readonly sessions;
+    private readonly facts;
+    private rooms?;
+    private bus?;
+    private tasks?;
+    private timeline?;
+    /** One write chain: every mutation (create/join/post/task) queues here. */
+    private tail;
+    /** Per-room delivery chains: posts to one room serialize delivery order. */
+    private readonly roomChains;
+    /** Per-member delivery chains: live delivery and catch-up never interleave. */
+    private readonly memberChains;
+    /** Resolves once the storage domain is open (or failed); gates every operation. */
+    private readonly ready;
+    private readyResolve;
+    private initError;
+    constructor(ctx: Context, config: RoomConfig, agents: LiveAgents, sessions: LiveSessions, facts: FactAppender);
+    /**
+     * Open the `team_rooms` storage domain and load its four tables. Called
+     * once by the mount site after the storage domain becomes available; every
+     * hub operation gates on this resolution. A failed open fails every
+     * operation loud through {@link requireRooms} instead of hanging — and a
+     * STUCK open (a storage provider whose open promise never settles) is cut
+     * off by the `roomOpenTimeoutMs` timer so `/room` commands still settle
+     * with a `store-unavailable` error instead of never emitting
+     * `command/done`.
+     */
+    open(): Promise<void>;
+    /** One room record, or undefined. */
+    room(roomId: string): Promise<RoomRecord | undefined>;
+    /** Every room one session is a member of, in creation order. */
+    roomsOfMember(sessionId: SessionId): Promise<RoomRecord[]>;
+    /** All rooms (used by the command surface for the roster). */
+    allRooms(): Promise<RoomRecord[]>;
+    /** Bus messages of one room with seq > since, in seq order. */
+    busMessages(roomId: string, since?: number): Promise<BusMessage[]>;
+    /** The task board of one room, creation order. */
+    tasksOf(roomId: string): Promise<TaskRecord[]>;
+    /** The timeline of one room with seq > since, in seq order. */
+    timelineOf(roomId: string, since?: number): Promise<TimelineEvent[]>;
+    /** The member slot of one session in one room, or undefined. */
+    memberOf(room: RoomRecord, sessionId: SessionId): RoomMember | undefined;
+    /**
+     * Create one room; the creator becomes its owner member. Enforces the
+     * profile-wide `maxRooms` cap inside the write chain.
+     */
+    createRoom(sessionId: SessionId, name: string, now?: number): Promise<RoomRecord>;
+    /**
+     * Register one session as a member of an existing room (cross-session
+     * membership). Enforces the per-room and per-member caps inside the chain.
+     */
+    joinRoom(sessionId: SessionId, roomId: string, now?: number): Promise<RoomRecord>;
+    /** Remove one member. The owner leaving deletes the room. */
+    leaveRoom(sessionId: SessionId, roomId: string, now?: number): Promise<RoomRecord | undefined>;
+    /** Owner-only room deletion. */
+    deleteRoom(sessionId: SessionId, roomId: string): Promise<void>;
+    /**
+     * Post one message onto the bus: broadcast, or directed when `toSessionId`
+     * names a member. Runs on the per-room delivery chain so per-member
+     * delivery order always equals bus seq order, and commits the store write
+     * before any delivery (cursors advance only after delivery — at-least-once).
+     */
+    postMessage(input: {
+        readonly roomId: string;
+        readonly senderSessionId: SessionId;
+        readonly text: string;
+        readonly toSessionId?: SessionId;
+    }, now?: number): Promise<PostedMessage>;
+    /** Create a task on the board (assignee optional; default unassigned). */
+    createTask(input: {
+        readonly roomId: string;
+        readonly bySessionId: SessionId;
+        readonly title: string;
+        readonly description?: string;
+        readonly assigneeSessionId?: SessionId;
+    }, now?: number): Promise<TaskRecord>;
+    /** Claim a task for the calling member (in-progress + assignee). */
+    claimTask(input: {
+        readonly roomId: string;
+        readonly bySessionId: SessionId;
+        readonly taskId: string;
+    }, now?: number): Promise<TaskRecord>;
+    /**
+     * Hand a task to another member. Callers outside a tool (the /room command)
+     * are the user themselves; the room_transfer_task TOOL gates this same
+     * mutation behind the approval service.
+     */
+    assignTask(input: {
+        readonly roomId: string;
+        readonly bySessionId: SessionId;
+        readonly taskId: string;
+        readonly toSessionId: SessionId;
+    }, now?: number): Promise<TaskRecord>;
+    /** Complete a task (done). Only the assignee or the owner may complete it. */
+    completeTask(input: {
+        readonly roomId: string;
+        readonly bySessionId: SessionId;
+        readonly taskId: string;
+    }, now?: number): Promise<TaskRecord>;
+    /**
+     * Deliver everything a member missed while offline: the log-only facts
+     * (shared timeline) and the model-visible bus backlog, both in store order.
+     * Runs on the member's delivery chain so a live post cannot interleave.
+     * Idempotent: cursors make a second call a no-op.
+     */
+    catchUp(sessionId: SessionId): Promise<void>;
+    /**
+     * The member brief: a SHORT injected paragraph that starts with the
+     * one-line role statement (Minimal-persona style) and names the room id,
+     * the member count, and the collaboration tools. Injected on join and on
+     * every session start (resume included), as a durable user message — the
+     * member's model sees exactly what the member's log records.
+     */
+    injectBrief(sessionId: SessionId, room: RoomRecord): void;
+    /** Build the minimal brief paragraph for one room. */
+    briefText(room: RoomRecord): string;
+    /**
+     * Queue one mutation on the single write chain; rejections are contained.
+     * The previous tail is captured SYNCHRONOUSLY: reading `this.tail` after
+     * `ready` resolves would see the just-assigned tail (a promise that settles
+     * with this very result) and deadlock the whole write chain — the exact
+     * hang that left `/room create` without a `command/done`.
+     */
+    private enqueue;
+    /** Serialize work per room (delivery order = bus order). */
+    private onRoomChain;
+    /** Serialize delivery per member (live delivery vs catch-up). */
+    private onMemberChain;
+    /** One task-board mutation shared by claim/assign/complete. */
+    private mutateTask;
+    /** Append the room-joined snapshot fact to one session's live log. */
+    private appendFactTo;
+    /** Append one fact to every LIVE member session (offline members catch up). */
+    private broadcastFact;
+    /** Deliver one posted message's fact + model-visible copy, per member. */
+    private deliverPosted;
+    /** Advance delivery cursors for the members that just received the post. */
+    private advanceCursors;
+    /** Advance the fact cursor for every member whose session is live now. */
+    private advanceFactsForLive;
+    /** One model-visible delivery: a durable user message with a room header. */
+    private roomUserMessage;
+    /** The room-joined snapshot fact. */
+    private joinFact;
+    /** Rebuild the fact one timeline event corresponds to (catch-up replay). */
+    private factFromTimeline;
+    private taskCreatedFact;
+    private taskMutationFact;
+    private timelineEvent;
+    /** Retention pruning: bus, timeline, and completed tasks. */
+    private pruneRoom;
+    /** Delete every bus/task/timeline row of a deleted room. */
+    private purgeRoom;
+    private requireRoom;
+    private requireRooms;
+    private requireBus;
+    private requireTasks;
+    private requireTimeline;
+}
+//# sourceMappingURL=hub.d.ts.map