@khorsheed/dsh-room 0.2.2 → 0.2.4

package/lib/types/jobs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tasks (jobs): what the human asked for and everything it set in motion.
+ * A task starts at a human message that led to work — at least one
+ * delivery carries its id — and gathers the follow-up messages attributed to
+ * it (`room/task-link`, by the composer's tag, the coordinator or the
+ * decision model) and every delivery recorded under it: delegations,
+ * members' sub-delegations, reports. Plain chat that dispatched nothing is
+ * not a task. Pure: the host replay and the client views share it.
+ * @module @khorsheed/dsh-room/jobs
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { RoomDelivery, RoomJob } from './types.ts';
+/**
+ * Fold the room log into its tasks, newest first.
+ * @param events - the room log.
+ * @param deliveries - the replayed deliveries (their `task` already resolved).
+ * @returns the tasks.
+ */
+export declare function replayJobs(events: readonly SessionEvent[], deliveries: readonly RoomDelivery[]): RoomJob[];
+/** Resolve the coordinator's `task` argument (`new`, a 「任务 N」 number, or a root id) against the room's tasks. */
+export declare function resolveTaskRef(jobs: readonly RoomJob[], ref: string): string | 'new' | undefined;
+//# sourceMappingURL=jobs.d.ts.map

package/lib/types/jobs.js

@@ -0,0 +1,77 @@
+import { isHumanMessage } from './deliveries.js';
+/** The text of a message's text blocks. */
+function textOf(content) {
+    return content.flatMap(block => block.type === 'text' && typeof block.text === 'string' ? [block.text] : []).join('\n');
+}
+/**
+ * Fold the room log into its tasks, newest first.
+ * @param events - the room log.
+ * @param deliveries - the replayed deliveries (their `task` already resolved).
+ * @returns the tasks.
+ */
+export function replayJobs(events, deliveries) {
+    const messages = new Map();
+    const links = new Map();
+    const stopped = new Set();
+    const dispatchById = new Map();
+    for (const event of events) {
+        if (isHumanMessage(event))
+            messages.set(event.data.id, { id: event.data.id, time: event.time, text: textOf(event.data.content) });
+        else if (event.type === 'room/task-link') {
+            links.set(event.data.message, { task: event.data.task, by: event.data.by, ...event.data.probability === undefined ? {} : { probability: event.data.probability } });
+        }
+        else if (event.type === 'room/job-stopped')
+            stopped.add(event.data.task);
+        else if (event.type === 'room/dispatch' && event.data.id !== undefined)
+            dispatchById.set(event.data.id, { time: event.time, text: event.data.text });
+    }
+    const byTask = new Map();
+    for (const row of deliveries) {
+        if (row.task === undefined)
+            continue;
+        const list = byTask.get(row.task) ?? [];
+        list.push(row);
+        byTask.set(row.task, list);
+    }
+    const roots = [...byTask.keys()]
+        .map(id => ({ id, root: messages.get(id) ?? dispatchById.get(id) }))
+        .filter((entry) => entry.root !== undefined)
+        .sort((a, b) => a.root.time - b.root.time);
+    const jobs = roots.map(({ id, root }, index) => {
+        const rows = byTask.get(id) ?? [];
+        const follow = [...links.entries()]
+            .filter(([message, link]) => link.task === id && message !== id)
+            .flatMap(([message, link]) => {
+            const found = messages.get(message);
+            return found === undefined ? [] : [{ ...found, by: link.by, ...link.probability === undefined ? {} : { probability: link.probability } }];
+        });
+        const open = rows.some(row => row.status === 'queued' || row.status === 'running' || row.status === 'held');
+        const attention = rows.some(row => row.status === 'uncertain');
+        // A round with an unknown outcome needs the human even in a stopped task.
+        const status = attention ? 'attention' : stopped.has(id) && !open ? 'stopped' : open ? 'running' : 'done';
+        const ended = Math.max(...rows.map(row => row.endedAt ?? row.queuedAt));
+        const goal = rows.find(row => row.plan !== undefined)?.plan?.goalId;
+        return {
+            id, number: index + 1,
+            // Leading @-mentions address members; the request is what follows.
+            title: (root.text.replace(/^(?:@\S+\s+)+/, '').split('\n', 1)[0] ?? '').slice(0, 120),
+            messages: [{ id, time: root.time, text: root.text }, ...follow].sort((a, b) => a.time - b.time),
+            status, startedAt: root.time,
+            ...open ? {} : { endedAt: ended },
+            deliveries: rows.map(row => row.id),
+            members: [...new Set(rows.map(row => row.memberId))],
+            ...goal === undefined ? {} : { goalId: goal },
+        };
+    });
+    return jobs.reverse();
+}
+/** Resolve the coordinator's `task` argument (`new`, a 「任务 N」 number, or a root id) against the room's tasks. */
+export function resolveTaskRef(jobs, ref) {
+    const value = ref.trim().replace(/^任务\s*/, '').replace(/^#/, '');
+    if (value === 'new' || value === '新')
+        return 'new';
+    const number = Number(value);
+    if (Number.isInteger(number) && number > 0)
+        return jobs.find(job => job.number === number)?.id;
+    return jobs.find(job => job.id === value)?.id;
+}

package/lib/types/journal.d.ts

@@ -1,11 +1,13 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
-import type { RoomMember, RoomState, RoomTask, RoomTaskProgress } from './types.ts';
+import type { RoomMember, RoomSettings, RoomState, RoomTask, RoomTaskProgress } from './types.ts';
 /**
  * The native DSH member's addressing name in new rooms. It starts as the
  * coordinator; bare messages follow the selected coordinator thereafter.
  * Existing journals retain their recorded names, including legacy main.
  */
 export declare const MAIN_AGENT_MEMBER = "dsh";
+/** Longest accepted public member role (`RoomMember.role`), in characters. */
+export declare const ROOM_ROLE_MAX = 30;
 /**
  * Every `room/*` session-event type this package introduces. Room registers
  * them into the harness's KNOWN_SESSION_EVENT_TYPES persistence catalog at
@@ -18,7 +20,9 @@ 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/execution-metadata', '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/approval', 'room/approval-resolved', 'room/question', 'room/question-resolved', 'room/task-added', 'room/task-updated', 'room/task-edited', 'room/goal', 'room/settings', 'room/report-gate', 'room/decision', 'room/task-link', 'room/job-stopped', 'room/help', 'room/help-message', 'room/help-state', 'room/help-in', 'room/help-link', 'room/help-unlink', 'room/help-nudge-dismissed'];
+/** Collaboration settings of a room that never changed them. */
+export declare const DEFAULT_ROOM_SETTINGS: RoomSettings;
 /** Whether an event log carries the room identity marker. */
 export declare function isRoomLog(events: readonly SessionEvent[]): boolean;
 /**
@@ -32,20 +36,6 @@ export declare function parseMentions(raw: string): {
     readonly targets: readonly string[];
     readonly text: string;
 };
-/**
- * The fallback notification channel: a member reply's TRAILING own line of
- * the form `@name <content>` (the format the roster injection teaches).
- * Only the last line counts — an `@name` inside prose is a mention, not a
- * notification. Leading whitespace on that line is tolerated (models indent
- * under their own bullet/list style). The caller checks the target against
- * the roster.
- * @param text - the member's reply text.
- * @returns the parsed directive, or undefined.
- */
-export declare function parseRelayDirective(text: string): {
-    readonly to: string;
-    readonly content: string;
-} | undefined;
 /**
  * Fold a session's event log into the room state.
  *
@@ -81,20 +71,20 @@ export declare function taskProgress(tasks: readonly RoomTask[]): RoomTaskProgre
  */
 export declare function previousCursor(events: readonly SessionEvent[], member: string, beforeSeq: number): number | undefined;
 /**
- * Whether the roster a member was last told about is stale: any roster-visible
- * change with a seq past their dispatch cursor — a member-added or
- * member-removed, or a member-updated that touches what the roster section
- * shows (instructions = the one-line role, rename = the addressing name). A
- * childSessionId/cwd/model-only update is NOT roster-visible (the delegation
- * handle is journaled right after a first run; counting it would re-send the
- * roster on every member's next dispatch for nothing — the model intent never
- * enters any prompt either). A member with no cursor has
- * never seen the roster, so their first dispatch always counts as stale.
+ * What changed in the room since a member's last dispatch, as one-line
+ * notes for the next prompt: other members joining or leaving, renames, role
+ * changes, the member's own role change, and a goal change. The full roster
+ * rides only the first dispatch's briefing; later dispatches carry these
+ * deltas instead (the member's own session holds the rest), and a member who
+ * wants the whole picture calls `room_read`. Model, cwd and delegation-handle
+ * updates never reach a prompt. A member with no cursor gets no deltas — the
+ * briefing already covers everything.
  * @param events - the session's event log.
  * @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
- * @returns true when the next dispatch must carry the roster section.
+ * @param self - the member's CURRENT name (its own rename is not news to it).
+ * @returns the change notes (empty when nothing changed).
  */
-export declare function rosterStaleSince(events: readonly SessionEvent[], cursor: number | undefined): boolean;
+export declare function roomChangesSince(events: readonly SessionEvent[], cursor: number | undefined, self: string): readonly string[];
 /**
  * The role-instructions carry for the next dispatch to a member: 'initial'
  * when the member has never been dispatched (their instructions open the

package/lib/types/journal.js

@@ -11,12 +11,16 @@
  * @module @khorsheed/dsh-room/journal
  */
 import { replayDeliveries } from './deliveries.js';
+import { replayJobs } from './jobs.js';
+import { replayHelps, replayLinks } from './helps.js';
 /**
  * The native DSH member's addressing name in new rooms. It starts as the
  * coordinator; bare messages follow the selected coordinator thereafter.
  * Existing journals retain their recorded names, including legacy main.
  */
 export const MAIN_AGENT_MEMBER = 'dsh';
+/** Longest accepted public member role (`RoomMember.role`), in characters. */
+export const ROOM_ROLE_MAX = 30;
 /**
  * Every `room/*` session-event type this package introduces. Room registers
  * them into the harness's KNOWN_SESSION_EVENT_TYPES persistence catalog at
@@ -43,11 +47,29 @@ export const ROOM_EVENT_TYPES = [
     'room/execution-metadata',
     'room/relay',
     'room/relay-resolved',
+    'room/approval',
+    'room/approval-resolved',
+    'room/question',
+    'room/question-resolved',
     'room/task-added',
     'room/task-updated',
     'room/task-edited',
     'room/goal',
+    'room/settings',
+    'room/report-gate',
+    'room/decision',
+    'room/task-link',
+    'room/job-stopped',
+    'room/help',
+    'room/help-message',
+    'room/help-state',
+    'room/help-in',
+    'room/help-link',
+    'room/help-unlink',
+    'room/help-nudge-dismissed',
 ];
+/** Collaboration settings of a room that never changed them. */
+export const DEFAULT_ROOM_SETTINGS = { memberMessages: 'free', hopLimit: 10, paused: false, reportTiming: 'judge', autoTaskFiling: true, reportThreshold: 0.5, reportWaitMinutes: 3, helpReminderMinutes: 30 };
 /** Whether an event log carries the room identity marker. */
 export function isRoomLog(events) {
     return events.some(event => event.type === 'room/created');
@@ -64,7 +86,9 @@ export function parseMentions(raw) {
     let rest = raw.trim();
     for (;;) {
         const match = /^@(\S+)(?:\s+|$)/.exec(rest);
-        if (match === null)
+        // A host reference (`@[title](dsh-session:…)`, the @ menu's session chip)
+        // names another session, never a member: it stays in the text.
+        if (match === null || match[1].startsWith('['))
             break;
         const name = match[1];
         if (!targets.includes(name))
@@ -73,26 +97,6 @@ export function parseMentions(raw) {
     }
     return { targets, text: rest };
 }
-/**
- * The fallback notification channel: a member reply's TRAILING own line of
- * the form `@name <content>` (the format the roster injection teaches).
- * Only the last line counts — an `@name` inside prose is a mention, not a
- * notification. Leading whitespace on that line is tolerated (models indent
- * under their own bullet/list style). The caller checks the target against
- * the roster.
- * @param text - the member's reply text.
- * @returns the parsed directive, or undefined.
- */
-export function parseRelayDirective(text) {
-    const trimmed = text.trimEnd();
-    if (trimmed === '')
-        return undefined;
-    const last = trimmed.slice(trimmed.lastIndexOf('\n') + 1).trimStart();
-    const match = /^@(\S+)\s+(\S[\s\S]*)$/.exec(last);
-    if (match === null)
-        return undefined;
-    return { to: match[1], content: match[2].trim() };
-}
 /**
  * Fold a session's event log into the room state.
  *
@@ -111,15 +115,26 @@ export function replay(events) {
     const members = [];
     const byName = new Map();
     const relays = [];
+    const approvals = new Map();
+    const questions = new Map();
     const relayById = new Map();
     const tasks = [];
     const taskById = new Map();
     const runs = new Map();
     const executions = new Map();
     let goal;
+    let settings = DEFAULT_ROOM_SETTINGS;
     let coordinator;
+    let latestReplySeq;
+    let latestSpeechSeq;
     for (const event of events) {
         switch (event.type) {
+            case 'room/speech':
+                latestSpeechSeq = event.seq;
+                // A reply to the room (not a report to another member).
+                if (event.data.reportedTo === undefined)
+                    latestReplySeq = event.seq;
+                break;
             case 'room/coordinator': {
                 if (event.data.revision > (coordinator?.revision ?? 0))
                     coordinator = event.data;
@@ -135,8 +150,11 @@ export function replay(events) {
                     invitedBy: event.data.invitedBy,
                     ...event.data.provider === undefined ? {} : { provider: event.data.provider },
                     ...event.data.instructions === undefined ? {} : { instructions: event.data.instructions },
+                    ...event.data.role === undefined ? {} : { role: event.data.role },
+                    ...event.data.preset === undefined ? {} : { preset: event.data.preset },
                     ...event.data.cwd === undefined ? {} : { cwd: event.data.cwd },
                     ...event.data.model === undefined ? {} : { model: event.data.model },
+                    ...event.data.effort === undefined ? {} : { effort: event.data.effort },
                     ...event.data.childSessionId === undefined ? {} : { childSessionId: event.data.childSessionId },
                 };
                 byName.set(added.name, added);
@@ -152,14 +170,20 @@ export function replay(events) {
                 const withoutInstructions = event.data.instructions === null
                     ? (({ instructions: _cleared, ...rest }) => rest)(member)
                     : { ...member, ...event.data.instructions === undefined ? {} : { instructions: event.data.instructions } };
+                const withoutRole = event.data.role === null
+                    ? (({ role: _cleared, ...rest }) => rest)(withoutInstructions)
+                    : { ...withoutInstructions, ...event.data.role === undefined ? {} : { role: event.data.role } };
                 const withoutCwd = event.data.cwd === null
-                    ? (({ cwd: _cleared, ...rest }) => rest)(withoutInstructions)
-                    : { ...withoutInstructions, ...event.data.cwd === undefined ? {} : { cwd: event.data.cwd } };
+                    ? (({ cwd: _cleared, ...rest }) => rest)(withoutRole)
+                    : { ...withoutRole, ...event.data.cwd === undefined ? {} : { cwd: event.data.cwd } };
                 const withoutModel = event.data.model === null
                     ? (({ model: _cleared, ...rest }) => rest)(withoutCwd)
                     : { ...withoutCwd, ...event.data.model === undefined ? {} : { model: event.data.model } };
+                const withoutEffort = event.data.effort === null
+                    ? (({ effort: _cleared, ...rest }) => rest)(withoutModel)
+                    : { ...withoutModel, ...event.data.effort === undefined ? {} : { effort: event.data.effort } };
                 const patched = {
-                    ...withoutModel,
+                    ...withoutEffort,
                     ...event.data.childSessionId === undefined ? {} : { childSessionId: event.data.childSessionId },
                 };
                 // First admission can precede publication of the native child handle.
@@ -233,11 +257,25 @@ export function replay(events) {
                     content: event.data.content,
                     state: 'pending',
                     ...event.data.provenance === undefined ? {} : { provenance: event.data.provenance },
+                    ...event.data.reason === undefined ? {} : { reason: event.data.reason },
+                    ...event.data.intent === undefined ? {} : { intent: event.data.intent },
                 };
                 relayById.set(relay.id, relay);
                 relays.push(relay);
                 break;
             }
+            case 'room/approval':
+                approvals.set(event.data.id, { id: event.data.id, member: event.data.member, tool: event.data.tool, ...event.data.reason === undefined ? {} : { reason: event.data.reason }, time: event.time });
+                break;
+            case 'room/question':
+                questions.set(event.data.id, { id: event.data.id, member: event.data.member, questions: event.data.questions, time: event.time });
+                break;
+            case 'room/question-resolved':
+                questions.delete(event.data.id);
+                break;
+            case 'room/approval-resolved':
+                approvals.delete(event.data.id);
+                break;
             case 'room/relay-resolved': {
                 const relay = relayById.get(event.data.id);
                 if (relay === undefined)
@@ -284,12 +322,26 @@ export function replay(events) {
                 const edited = {
                     ...base,
                     ...event.data.title === undefined ? {} : { title: event.data.title },
+                    ...event.data.member === undefined ? {} : { member: event.data.member },
                     updatedAt: event.time,
                 };
                 taskById.set(edited.id, edited);
                 tasks[tasks.indexOf(task)] = edited;
                 break;
             }
+            case 'room/settings': {
+                settings = {
+                    memberMessages: event.data.memberMessages ?? settings.memberMessages,
+                    hopLimit: event.data.hopLimit ?? settings.hopLimit,
+                    paused: event.data.paused ?? settings.paused,
+                    reportTiming: event.data.reportTiming ?? settings.reportTiming,
+                    autoTaskFiling: event.data.autoTaskFiling ?? settings.autoTaskFiling,
+                    reportThreshold: event.data.reportThreshold ?? settings.reportThreshold,
+                    reportWaitMinutes: event.data.reportWaitMinutes ?? settings.reportWaitMinutes,
+                    helpReminderMinutes: event.data.helpReminderMinutes ?? settings.helpReminderMinutes,
+                };
+                break;
+            }
             case 'room/goal': {
                 // Latest goal event wins; a blank text clears the goal.
                 const text = event.data.text.trim();
@@ -337,7 +389,14 @@ 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, ...executions.size === 0 ? {} : { executions: [...executions.values()] }, ...plan === undefined ? {} : { plan }, ...deliveries.length === 0 ? {} : { deliveries }, runs: [...runs.values()], ...coordinator === undefined ? {} : { coordinator }, ...goal === undefined ? {} : { goal } };
+    const jobs = deliveries.length === 0 ? [] : replayJobs(events, deliveries);
+    const helps = replayHelps(events);
+    const links = replayLinks(events);
+    return {
+        ...helps.length === 0 ? {} : { helps },
+        ...links.linked.length === 0 ? {} : { linked: links.linked },
+        ...links.nudgesDismissed.length === 0 ? {} : { helpNudgesDismissed: links.nudgesDismissed }, members, relays, ...approvals.size === 0 ? {} : { approvals: [...approvals.values()] }, ...questions.size === 0 ? {} : { questions: [...questions.values()] }, tasks, ...executions.size === 0 ? {} : { executions: [...executions.values()] }, ...plan === undefined ? {} : { plan }, ...deliveries.length === 0 ? {} : { deliveries }, runs: [...runs.values()], ...coordinator === undefined ? {} : { coordinator }, ...goal === undefined ? {} : { goal }, ...latestReplySeq === undefined ? {} : { latestReplySeq }, ...latestSpeechSeq === undefined ? {} : { latestSpeechSeq }, settings, ...jobs.length === 0 ? {} : { jobs }
+    };
 }
 /**
  * The goal progress pair: done tasks over the COUNTABLE total — cancelled
@@ -371,32 +430,50 @@ export function previousCursor(events, member, beforeSeq) {
     return cursor;
 }
 /**
- * Whether the roster a member was last told about is stale: any roster-visible
- * change with a seq past their dispatch cursor — a member-added or
- * member-removed, or a member-updated that touches what the roster section
- * shows (instructions = the one-line role, rename = the addressing name). A
- * childSessionId/cwd/model-only update is NOT roster-visible (the delegation
- * handle is journaled right after a first run; counting it would re-send the
- * roster on every member's next dispatch for nothing — the model intent never
- * enters any prompt either). A member with no cursor has
- * never seen the roster, so their first dispatch always counts as stale.
+ * What changed in the room since a member's last dispatch, as one-line
+ * notes for the next prompt: other members joining or leaving, renames, role
+ * changes, the member's own role change, and a goal change. The full roster
+ * rides only the first dispatch's briefing; later dispatches carry these
+ * deltas instead (the member's own session holds the rest), and a member who
+ * wants the whole picture calls `room_read`. Model, cwd and delegation-handle
+ * updates never reach a prompt. A member with no cursor gets no deltas — the
+ * briefing already covers everything.
  * @param events - the session's event log.
  * @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
- * @returns true when the next dispatch must carry the roster section.
+ * @param self - the member's CURRENT name (its own rename is not news to it).
+ * @returns the change notes (empty when nothing changed).
  */
-export function rosterStaleSince(events, cursor) {
+export function roomChangesSince(events, cursor, self) {
     if (cursor === undefined)
-        return true;
+        return [];
+    const notes = [];
+    let goal;
     for (const event of events) {
         if (event.seq <= cursor)
             continue;
-        if (event.type === 'room/member-added' || event.type === 'room/member-removed')
-            return true;
-        if (event.type === 'room/member-updated'
-            && (event.data.instructions !== undefined || event.data.rename !== undefined))
-            return true;
+        if (event.type === 'room/member-added' && event.data.name !== self && event.data.kind !== 'main-agent') {
+            const detail = [event.data.role, event.data.provider].filter(Boolean).join(' · ');
+            notes.push(`${event.data.name} 加入${detail === '' ? '' : `（${detail}）`}`);
+        }
+        else if (event.type === 'room/member-removed' && event.data.name !== self) {
+            notes.push(`${event.data.name} 离开`);
+        }
+        else if (event.type === 'room/member-updated') {
+            if (event.data.rename !== undefined && event.data.rename !== self)
+                notes.push(`${event.data.name} 改名为 ${event.data.rename}`);
+            if (event.data.role !== undefined) {
+                const who = event.data.rename ?? event.data.name;
+                const subject = who === self ? '你的职责' : `${who} 的职责`;
+                notes.push(event.data.role === null ? `${subject}已清除` : `${subject}改为：${event.data.role}`);
+            }
+        }
+        else if (event.type === 'room/goal') {
+            goal = { text: event.data.text.trim() };
+        }
     }
-    return false;
+    if (goal !== undefined)
+        notes.push(goal.text === '' ? '房间目标已清除' : `房间目标更新为：${goal.text}`);
+    return notes;
 }
 /**
  * The role-instructions carry for the next dispatch to a member: 'initial'

package/lib/types/messaging.d.ts

@@ -0,0 +1,65 @@
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { RoomHeldDispatch, RoomHoldReason, RoomMember, RoomRelay, RoomState } from './types.ts';
+/** `RoomHeldDispatch.task` marker: this send starts a task rooted at the dispatch itself. */
+export declare const SELF_TASK = "@self";
+/** The id members and the UI use for a dispatch. */
+export declare function messageId(seq: number): string;
+/** Parse `m12` / `#m12` / `12` back to a dispatch seq. */
+export declare function parseMessageRef(ref: string | undefined): number | undefined;
+/** The hop a dispatch sits at (legacy dispatches count as a chain start). */
+export declare function dispatchHop(events: readonly SessionEvent[], seq: number): number;
+/**
+ * The hop of whatever a member is working on right now: its running
+ * delivery's hop, or 0 when it is not inside a room delivery (a human
+ * chatting with the room's agent directly) so its sends start a chain.
+ */
+export declare function workingHop(events: readonly SessionEvent[], state: RoomState, member: RoomMember): number;
+/**
+ * Why a message must wait for the human, if it must. A paused room holds
+ * everything agents send; a chain past the limit stops; `confirm` holds
+ * member-to-member messages only (never the coordinator's delegations or
+ * reports, which the human already asked for).
+ */
+export declare function holdReason(state: RoomState, hop: number, origin: RoomHeldDispatch['origin']): RoomHoldReason | undefined;
+/** One outgoing agent message. */
+export interface OutgoingMessage {
+    readonly to: RoomMember;
+    readonly text: string;
+    readonly intent: RoomHeldDispatch;
+    /** Sender's display name for a held card (`from`). */
+    readonly fromName: string;
+}
+/** What {@link sendOrHold} did. */
+export type SendOutcome = {
+    readonly delivered: true;
+    readonly seq: number;
+} | {
+    readonly delivered: false;
+    readonly reason: RoomHoldReason;
+    readonly relayId: string;
+};
+/**
+ * Journal one agent message: a dispatch or a held relay with its intent. The caller
+ * flushes and, on delivery, hands `seq` to the engine.
+ * @param session - the room session.
+ * @param message - recipient, text and the would-be dispatch.
+ * @param skipHold - release path: deliver regardless of the hold rules.
+ * @returns the dispatch seq, or the hold.
+ */
+export declare function sendOrHold(session: Session, message: OutgoingMessage, skipHold?: boolean): SendOutcome;
+/**
+ * The would-be dispatch of a held relay, re-anchored for release: a chain
+ * the human lets continue past the hop limit starts a fresh budget.
+ */
+export declare function releaseIntent(relay: RoomRelay): RoomHeldDispatch | undefined;
+/**
+ * The envelope line a delivered message opens with, or undefined for a
+ * dispatch without one (legacy journals). Names resolve against the CURRENT
+ * roster, falling back to the last known name of a member who left.
+ * @param events - the room log.
+ * @param seq - the dispatch being delivered.
+ * @returns the envelope line.
+ */
+export declare function envelopeLine(events: readonly SessionEvent[], seq: number): string | undefined;
+//# sourceMappingURL=messaging.d.ts.map