@khorsheed/dsh-room 0.2.2 → 0.2.3

package/lib/types/client/team.js

@@ -0,0 +1,187 @@
+/**
+ * The team view's projection: who works for whom in a room, read from the
+ * replayed state the client already holds. A room's members are standing
+ * (one member takes many deliveries), so the member is the node and each
+ * delivery it received hangs under it; edges count what flowed between two
+ * members — tasks handed over, reports that came back, FYIs.
+ *
+ * The tree places every member under whoever handed it the most tasks (the
+ * human included), walking out from the human so the result is always a
+ * tree; a member nobody has tasked yet sits under the coordinator. Edges the
+ * tree does not draw stay available as cross links.
+ *
+ * Outside sessions the room asked for help hang under whoever asked them
+ * (dashed 外援 nodes, grey once every ask has ended); one kept on the member
+ * list (「加入房间成员」) is a solid node still marked 外部会话. Neither counts
+ * in the room's totals: its work and usage belong to its own session.
+ * @module @khorsheed/dsh-room/client/team
+ */
+import { coordinatorMember } from '../journal.js';
+/** The human, as a tree root. */
+export const TEAM_ROOT = 'you';
+const idOf = (member) => member.id ?? member.name;
+/**
+ * Project the room state into the team tree.
+ * @param state - the replayed room state.
+ * @returns nodes in tree order (parents before children), edges and totals.
+ */
+export function teamOf(state) {
+    const coordinator = coordinatorMember(state);
+    const byId = new Map(state.members.map(member => [idOf(member), member]));
+    const nameOf = (id) => id === TEAM_ROOT ? TEAM_ROOT : byId.get(id)?.name ?? id;
+    const edges = new Map();
+    const edge = (from, to) => {
+        const key = `${from}\u0000${to}`;
+        let row = edges.get(key);
+        if (row === undefined)
+            edges.set(key, row = { from, to, tasks: 0, reports: 0, notifies: 0 });
+        return row;
+    };
+    const received = new Map();
+    for (const delivery of state.deliveries ?? []) {
+        if (!byId.has(delivery.memberId) || delivery.origin === 'relay')
+            continue;
+        const from = delivery.origin === 'human' ? TEAM_ROOT
+            : delivery.origin === 'report' ? undefined
+                : delivery.from ?? (delivery.origin === 'coordinator' && coordinator !== undefined ? idOf(coordinator) : undefined);
+        const kind = delivery.origin === 'report' ? 'report' : delivery.kind === 'notify' ? 'notify' : 'task';
+        if (from !== undefined && from !== delivery.memberId) {
+            const row = edge(from, delivery.memberId);
+            if (kind === 'notify')
+                row.notifies++;
+            else {
+                row.tasks++;
+                if (delivery.replyTo !== undefined && ['done', 'failed', 'cancelled', 'uncertain'].includes(delivery.status))
+                    row.reports++;
+            }
+        }
+        const list = received.get(delivery.memberId) ?? [];
+        list.push({ id: delivery.id, seq: delivery.dispatchSeq, from: from === undefined ? '' : nameOf(from), text: delivery.text, status: delivery.status, kind });
+        received.set(delivery.memberId, list);
+    }
+    // Parent = the source that handed this member the most tasks, placed by a
+    // walk from the human so no cycle can form.
+    const best = new Map();
+    for (const member of state.members) {
+        const id = idOf(member);
+        if (coordinator !== undefined && id === idOf(coordinator))
+            continue;
+        const top = [...edges.values()].filter(row => row.to === id && row.tasks > 0).sort((a, b) => b.tasks - a.tasks)[0];
+        if (top !== undefined)
+            best.set(id, top.from);
+    }
+    const parent = new Map();
+    const order = [];
+    const queue = [TEAM_ROOT];
+    if (coordinator !== undefined) {
+        parent.set(idOf(coordinator), TEAM_ROOT);
+    }
+    while (queue.length > 0) {
+        const at = queue.shift();
+        const children = at === TEAM_ROOT && coordinator !== undefined
+            ? [idOf(coordinator), ...state.members.map(idOf).filter(id => best.get(id) === TEAM_ROOT)]
+            : state.members.map(idOf).filter(id => best.get(id) === at);
+        for (const child of children) {
+            if (order.includes(child))
+                continue;
+            parent.set(child, at);
+            order.push(child);
+            queue.push(child);
+        }
+    }
+    for (const member of state.members) {
+        const id = idOf(member);
+        if (order.includes(id))
+            continue;
+        parent.set(id, coordinator !== undefined && idOf(coordinator) !== id ? idOf(coordinator) : TEAM_ROOT);
+        order.push(id);
+    }
+    const memberNodes = order.map((id) => {
+        const member = byId.get(id);
+        const run = state.runs.find(entry => entry.member === member.name);
+        const executions = (state.executions ?? []).filter(row => row.memberId === id);
+        const current = run?.state === 'running'
+            ? (state.deliveries ?? []).find(row => row.memberId === id && row.status === 'running' && (run.runId === undefined || row.id === run.runId))?.text.trim().split('\n', 1)[0]
+            : undefined;
+        const model = executions.findLast(row => row.model !== undefined)?.model ?? member.model;
+        return {
+            id, member, parent: parent.get(id) ?? TEAM_ROOT,
+            coordinator: coordinator !== undefined && idOf(coordinator) === id,
+            status: run?.state === 'running' ? 'running' : run?.state === 'failed' ? 'failed' : 'idle',
+            ...current === undefined ? {} : { current },
+            ...model === undefined ? {} : { model },
+            tokens: executions.reduce((sum, row) => sum + (row.tokens ?? 0), 0),
+            elapsedMs: executions.reduce((sum, row) => sum + (row.elapsedMs ?? 0), 0),
+            rounds: executions.length,
+            deliveries: (received.get(id) ?? []).slice().reverse(),
+        };
+    });
+    const nodes = [...memberNodes, ...externalNodes(state, memberNodes)];
+    const own = nodes.filter(node => node.external === undefined);
+    return {
+        nodes,
+        edges: [...edges.values()],
+        totals: {
+            members: own.length,
+            running: own.filter(node => node.status === 'running').length,
+            deliveries: (state.deliveries ?? []).filter(row => row.origin !== 'report' && row.origin !== 'relay').length,
+            tokens: own.reduce((sum, node) => sum + node.tokens, 0),
+            elapsedMs: own.reduce((sum, node) => sum + node.elapsedMs, 0),
+        },
+    };
+}
+/** The id of an outside session's node. */
+export const externalId = (sessionId, member) => `ext:${sessionId}${member === undefined ? '' : `:${member}`}`;
+/** A help thread's status as a delivery outcome. */
+function helpStatus(help) {
+    return help.state === 'replied' ? 'done' : help.state === 'failed' ? 'failed' : help.state === 'queued' ? 'queued' : 'running';
+}
+/**
+ * The outside sessions' nodes: one per asked target (a room's member counts
+ * as its own target), under whoever asked it last, plus every linked session
+ * nobody has asked yet, under the coordinator.
+ */
+function externalNodes(state, members) {
+    const coordinator = members.find(node => node.coordinator);
+    const linked = new Map((state.linked ?? []).map(entry => [entry.sessionId, entry]));
+    const groups = new Map();
+    for (const help of state.helps ?? []) {
+        const key = externalId(help.target.sessionId, help.target.member);
+        groups.set(key, [...groups.get(key) ?? [], help]);
+    }
+    const nodes = [];
+    for (const [id, helps] of groups) {
+        const last = helps.at(-1);
+        const target = last.target;
+        const asker = members.find(node => node.id === last.from);
+        const title = target.member === undefined ? target.title : `${target.member}（${target.title}）`;
+        const done = helps.every(help => help.state === 'replied' || help.state === 'failed');
+        nodes.push({
+            id, parent: asker?.id ?? coordinator?.id ?? TEAM_ROOT, coordinator: false,
+            member: { name: title, kind: 'cli', invitedBy: 'agent', childSessionId: target.sessionId },
+            status: done ? 'idle' : helps.some(help => help.state === 'running' || help.state === 'asking') ? 'running' : 'idle',
+            tokens: 0, elapsedMs: 0, rounds: helps.length,
+            deliveries: helps.slice().reverse().map(help => ({ id: help.id, seq: 0, from: help.fromName, text: help.text, status: helpStatus(help), kind: 'task' })),
+            external: { sessionId: target.sessionId, linked: target.member === undefined && linked.has(target.sessionId), room: target.room === true, done, helps },
+        });
+    }
+    for (const entry of linked.values()) {
+        if (groups.has(externalId(entry.sessionId)))
+            continue;
+        nodes.push({
+            id: externalId(entry.sessionId), parent: coordinator?.id ?? TEAM_ROOT, coordinator: false,
+            member: { name: entry.title, kind: 'cli', invitedBy: 'human', childSessionId: entry.sessionId },
+            status: 'idle', tokens: 0, elapsedMs: 0, rounds: 0, deliveries: [],
+            external: { sessionId: entry.sessionId, linked: true, room: false, done: false, helps: [] },
+        });
+    }
+    return nodes;
+}
+/** Compact token count: 1.2M / 288k / 512. */
+export function formatTokens(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(tokens >= 10_000_000 ? 0 : 1)}M`;
+    if (tokens >= 1000)
+        return `${Math.round(tokens / 1000)}k`;
+    return String(tokens);
+}

package/lib/types/decisions.d.ts

@@ -0,0 +1,49 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { RoomDecisionCall, RoomDecisionEvent, RoomDecisionScenario } from './types.ts';
+/** The bounded decision-model call. */
+export declare const DECISION_TIMEOUT_MS = 8000;
+/** One fixed question of a scenario (the typesafe wire shape). */
+export interface DecisionQuestion {
+    readonly id: string;
+    readonly type: 'noul' | 'choice';
+    readonly instructions: string;
+    readonly criteria?: Record<string, string>;
+}
+/** The scenario table: each scenario's fixed question (its criteria, when they depend on the room, are filled per call). */
+export declare const DECISION_SCENARIOS: Record<RoomDecisionScenario, {
+    readonly question: DecisionQuestion;
+}>;
+/** A model answer to one question, with the call that produced it. */
+export type DecisionAnswer = {
+    readonly ok: true;
+    readonly answer: unknown;
+    readonly probabilities?: Record<string, number>;
+    readonly call: RoomDecisionCall;
+} | {
+    readonly ok: false;
+    readonly call?: RoomDecisionCall;
+};
+/**
+ * Whether the decision model is mounted.
+ * @param ctx - host context.
+ * @returns true when `typesafe.judge` can be called.
+ */
+export declare function hasDecisionModel(ctx: Context): boolean;
+/**
+ * Ask the decision model one scenario question about a state, recording the
+ * call whatever happens. Never throws: no service, a refusal, a timeout or a
+ * malformed answer all come back as `ok: false` (with the call when one went out).
+ * @param ctx - host context (probes `typesafe`).
+ * @param question - the scenario's question, criteria filled.
+ * @param state - the JSON-safe state the model judges.
+ * @returns the answer and the recorded call.
+ */
+export declare function askDecisionModel(ctx: Context, question: DecisionQuestion, state: unknown): Promise<DecisionAnswer>;
+/**
+ * Build one decision record.
+ * @param scenario - the scenario.
+ * @param fields - outcome, rule or probability, the call, what it was about.
+ * @returns the `room/decision` event data.
+ */
+export declare function decisionRecord(scenario: RoomDecisionScenario, fields: Omit<RoomDecisionEvent, 'id' | 'scenario'>): RoomDecisionEvent;
+//# sourceMappingURL=decisions.d.ts.map

package/lib/types/decisions.js

@@ -0,0 +1,101 @@
+/**
+ * The room's own decisions — one table entry per scenario. A scenario checks
+ * its rules in order (the first that applies decides) and only then asks the
+ * decision model (the optional `typesafe` service, probed — room never
+ * depends on it) one fixed question about a state the room assembles from
+ * its log. Every decision becomes a `room/decision` record: the rule that
+ * decided, or the model call as it went out and came back (state, question,
+ * answer, model, tokens, latency, cache, failure). Settings, the timeline row
+ * and Context Lens all read the same scenario ids.
+ *
+ * Today's scenarios:
+ * - `task-filing`: does an untagged human message continue an open task, or
+ *   start a new one?
+ * - `report-timing`: is an arrived member result handed to the member waiting
+ *   on it now, or held to be handed over together later?
+ * @module @khorsheed/dsh-room/decisions
+ */
+import { randomUUID } from 'node:crypto';
+/** The bounded decision-model call. */
+export const DECISION_TIMEOUT_MS = 8000;
+/** The scenario table: each scenario's fixed question (its criteria, when they depend on the room, are filled per call). */
+export const DECISION_SCENARIOS = {
+    'task-filing': {
+        question: {
+            id: 'task',
+            type: 'choice',
+            instructions: 'A human sent this message to a team of agents that is still working on the open tasks listed. Does the message add to, correct or ask about one of those tasks, or does it start a new one?',
+        },
+    },
+    'report-timing': {
+        question: {
+            id: 'deliver_now',
+            type: 'noul',
+            instructions: 'A coordinating agent delegated work to other agents and their results arrive one by one. The human can already '
+                + 'read every result in the room. Should the results that have arrived be handed to the coordinator now? Answer '
+                + 'yes when they let it move the work forward (start the next step, answer the human, react to a problem) or when '
+                + 'the human has been waiting long enough that an update helps. Answer no when the coordinator said it is waiting '
+                + 'for the remaining results and those are still running normally.',
+        },
+    },
+};
+/** A JSON-safe copy (the record must survive the session log). */
+function json(value) {
+    return JSON.parse(JSON.stringify(value ?? null));
+}
+/**
+ * Whether the decision model is mounted.
+ * @param ctx - host context.
+ * @returns true when `typesafe.judge` can be called.
+ */
+export function hasDecisionModel(ctx) {
+    return typeof ctx.get('typesafe')?.judge === 'function';
+}
+/**
+ * Ask the decision model one scenario question about a state, recording the
+ * call whatever happens. Never throws: no service, a refusal, a timeout or a
+ * malformed answer all come back as `ok: false` (with the call when one went out).
+ * @param ctx - host context (probes `typesafe`).
+ * @param question - the scenario's question, criteria filled.
+ * @param state - the JSON-safe state the model judges.
+ * @returns the answer and the recorded call.
+ */
+export async function askDecisionModel(ctx, question, state) {
+    const service = ctx.get('typesafe');
+    if (typeof service?.judge !== 'function')
+        return { ok: false };
+    const request = { state: json(state), questions: json([question]) };
+    const asked = service.config?.defaultModel ?? 'typesafe';
+    const started = Date.now();
+    try {
+        const result = await service.judge({ state, questions: [question] }, { timeoutMs: DECISION_TIMEOUT_MS, fresh: true });
+        if (!result.ok) {
+            return { ok: false, call: { model: asked, latencyMs: Date.now() - started, request, failure: { reason: result.reason, ...result.detail === undefined ? {} : { detail: result.detail } } } };
+        }
+        const judgement = result.judgement;
+        // Only what the service reported: an absent field stays absent (the log takes JSON only).
+        const call = {
+            model: typeof judgement.model === 'string' && judgement.model !== '' ? judgement.model : asked,
+            latencyMs: typeof judgement.latencyMs === 'number' ? judgement.latencyMs : Date.now() - started,
+            ...typeof judgement.cached === 'boolean' ? { cached: judgement.cached } : {},
+            request, response: json(judgement.decisions),
+            ...judgement.usage === undefined ? {} : { inputTokens: judgement.usage.inputTokens, outputTokens: judgement.usage.outputTokens },
+        };
+        const decision = judgement.decisions.find(entry => entry.id === question.id);
+        if (decision === undefined)
+            return { ok: false, call: { ...call, failure: { reason: 'decode', detail: 'no answer to the question' } } };
+        return { ok: true, answer: decision.answer, ...decision.probabilities === undefined ? {} : { probabilities: decision.probabilities }, call };
+    }
+    catch (error) {
+        return { ok: false, call: { model: asked, latencyMs: Date.now() - started, request, failure: { reason: 'transport', detail: String(error) } } };
+    }
+}
+/**
+ * Build one decision record.
+ * @param scenario - the scenario.
+ * @param fields - outcome, rule or probability, the call, what it was about.
+ * @returns the `room/decision` event data.
+ */
+export function decisionRecord(scenario, fields) {
+    return { id: randomUUID(), scenario, ...fields };
+}

package/lib/types/deliveries.d.ts

@@ -1,5 +1,21 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
 import type { RoomDelivery } from './types.ts';
-/** Accepted delivery intents and their latest durable outcomes. */
+/** Whether an event is a message the human typed (not a producer's followup); an in-place edit of one (message-tools) is the human's text too. */
+export declare function isHumanMessage(event: SessionEvent): event is SessionEvent<'user/message'>;
+/** Every human message's latest task link (message id → task root id). */
+export declare function taskLinks(events: readonly SessionEvent[]): Map<string, string>;
+/** The task a human message belongs to: its latest link, else its own id (a task of its own). */
+export declare function linkedTask(links: ReadonlyMap<string, string>, messageId: string): string;
+/**
+ * Accepted delivery intents and their latest durable outcomes, with the
+ * timing edges the task views draw (dispatched, admitted, settled, held,
+ * released). A delivery's task is its dispatch's `task`; dispatches written
+ * before tasks were recorded fall back by cause: a report or release takes
+ * its source's task, anything else the task of the latest human message
+ * before it (the turn that sent it), and a human dispatch with no message
+ * (an invite's first task) is a task of its own.
+ * @param events - the room log.
+ * @returns the deliveries in dispatch order.
+ */
 export declare function replayDeliveries(events: readonly SessionEvent[]): RoomDelivery[];
 //# sourceMappingURL=deliveries.d.ts.map

package/lib/types/deliveries.js

@@ -1,19 +1,95 @@
-/** Accepted delivery intents and their latest durable outcomes. */
+/** Whether an event is a message the human typed (not a producer's followup); an in-place edit of one (message-tools) is the human's text too. */
+export function isHumanMessage(event) {
+    if (event.type !== 'user/message')
+        return false;
+    const source = event.data.source;
+    return source.kind === 'user' || (source.kind === 'message-tools' && source.op === 'edit');
+}
+/** Every human message's latest task link (message id → task root id). */
+export function taskLinks(events) {
+    const links = new Map();
+    for (const event of events)
+        if (event.type === 'room/task-link')
+            links.set(event.data.message, event.data.task);
+    return links;
+}
+/** The task a human message belongs to: its latest link, else its own id (a task of its own). */
+export function linkedTask(links, messageId) {
+    return links.get(messageId) ?? messageId;
+}
+/**
+ * Accepted delivery intents and their latest durable outcomes, with the
+ * timing edges the task views draw (dispatched, admitted, settled, held,
+ * released). A delivery's task is its dispatch's `task`; dispatches written
+ * before tasks were recorded fall back by cause: a report or release takes
+ * its source's task, anything else the task of the latest human message
+ * before it (the turn that sent it), and a human dispatch with no message
+ * (an invite's first task) is a task of its own.
+ * @param events - the room log.
+ * @returns the deliveries in dispatch order.
+ */
 export function replayDeliveries(events) {
     const rows = new Map();
+    const taskBySeq = new Map();
+    const links = new Map();
+    let lastHuman;
+    const set = (id, patch) => {
+        const row = rows.get(id);
+        if (row !== undefined)
+            rows.set(id, { ...row, ...patch });
+    };
     for (const event of events) {
-        if (event.type === 'room/dispatch' && event.data.targetIds !== undefined) {
-            for (const memberId of event.data.targetIds) {
+        if (isHumanMessage(event)) {
+            lastHuman = { id: event.data.id, seq: event.seq };
+        }
+        else if (event.type === 'room/task-link') {
+            links.set(event.data.message, event.data.task);
+        }
+        else if (event.type === 'room/dispatch' && event.data.targetIds !== undefined) {
+            const data = event.data;
+            const targetIds = data.targetIds ?? [];
+            const sourceSeq = data.reportFor !== undefined && /^\d+:/.test(data.reportFor) ? Number(data.reportFor.split(':', 1)[0]) : data.releases?.[0];
+            const task = data.task
+                ?? (sourceSeq === undefined ? undefined : taskBySeq.get(sourceSeq))
+                ?? (data.origin === 'human' && lastHuman === undefined ? data.id : undefined)
+                ?? (lastHuman === undefined ? data.id : linkedTask(links, lastHuman.id));
+            if (task !== undefined)
+                taskBySeq.set(event.seq, task);
+            for (const memberId of targetIds) {
                 const id = `${event.seq}:${memberId}`;
-                if (!rows.has(id))
-                    rows.set(id, { id, dispatchSeq: event.seq, memberId, status: 'queued', text: event.data.text, origin: event.data.origin ?? 'human', ...event.data.plan === undefined ? {} : { plan: event.data.plan } });
+                if (rows.has(id))
+                    continue;
+                rows.set(id, {
+                    id, dispatchSeq: event.seq, memberId, status: data.held === true ? 'held' : 'queued', text: data.text,
+                    origin: data.origin ?? 'human', queuedAt: event.time,
+                    ...data.replyTo === undefined ? {} : { replyTo: data.replyTo },
+                    ...data.from === undefined ? {} : { from: data.from },
+                    ...data.kind === undefined ? {} : { kind: data.kind },
+                    ...data.plan === undefined ? {} : { plan: data.plan },
+                    ...task === undefined ? {} : { task },
+                    ...data.parent === undefined ? {} : { parent: data.parent },
+                    ...data.held === true ? { heldAt: event.time } : {},
+                });
             }
         }
         else if (event.type === 'room/delivery-state') {
             const row = rows.get(event.data.id);
             if (row === undefined || row.memberId !== event.data.memberId || row.dispatchSeq !== event.data.dispatchSeq)
                 continue;
-            rows.set(row.id, { ...row, status: event.data.state, ...event.data.error === undefined ? {} : { error: event.data.error } });
+            const terminal = event.data.state !== 'running';
+            rows.set(row.id, {
+                ...row, status: event.data.state,
+                ...event.data.error === undefined ? {} : { error: event.data.error },
+                ...event.data.state === 'running' && row.startedAt === undefined ? { startedAt: event.time } : {},
+                ...terminal ? { endedAt: event.time } : {},
+            });
+        }
+        else if (event.type === 'room/report-gate') {
+            const id = `${event.data.dispatchSeq}:${event.data.memberId}`;
+            if (event.data.verdict === 'hold')
+                set(id, { heldAt: event.time });
+            else if (event.data.verdict === 'release' && rows.get(id)?.releasedAt === undefined)
+                set(id, { releasedAt: event.time });
         }
     }
     return [...rows.values()];

package/lib/types/dispatch.d.ts

@@ -1,7 +1,8 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { Session } from '@deepseek-ai/dsh-session';
+import { SessionId, type Session } from '@deepseek-ai/dsh-session';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
 import { type ContextFormed, type MessageSource } from '@deepseek-ai/dsh-llm';
-import type { RoomState } from './types.ts';
+import type { RoomMember, RoomState } from './types.ts';
 /**
  * The room producer's durable identity in its two historical forms: the
  * released V3 wrapper's `plugin` value (`@khorsheed/dsh-room` — the official
@@ -22,6 +23,27 @@ declare module '@deepseek-ai/dsh-llm' {
 }
 /** The producer-owned source of a room main-agent followup. */
 export declare function roomSource(): MessageSource;
+/**
+ * A run-state edge's child-session identity: the main agent runs on the room
+ * itself, external members on their child session. Optional — a fresh CLI
+ * member's early running edge predates the child handle's publication (the
+ * terminal edge and the journal backfill cover it).
+ */
+export declare function runChildSessionId(roomId: SessionId, member: RoomMember | undefined): SessionId | undefined;
+/**
+ * The child session round a run reached: the last turn/start the child wrote.
+ * Live sessions only — a reconcile path whose child is not in memory omits it.
+ */
+/**
+ * The id of the last assistant message a session's log holds after `afterSeq`:
+ * the message a member's round closed with, which per-message tools (Context
+ * Lens) address in the member's own session.
+ * @param session - the member's session.
+ * @param afterSeq - only messages after this seq count.
+ * @returns the message id, or undefined when the round produced none.
+ */
+export declare function lastAssistantMessageId(session: Session | undefined, afterSeq?: number): string | undefined;
+export declare function runChildTurn(session: Session | undefined): number | undefined;
 /**
  * Whether a durable source belongs to the room producer, in every form the
  * log can hold: the current producer-owned kind (`room`), the V3→V4 migrated
@@ -43,6 +65,20 @@ export interface DispatchOptions {
     /** Relays this dispatch DELIVERS (confirmRelay's own payloads). */
     readonly relayIds?: readonly string[];
 }
+/**
+ * Reports held for a member that it has not yet seen in a round: hold
+ * verdicts without a later release.
+ */
+export declare function pendingHolds(events: readonly SessionEvent[], recipientId: string): readonly number[];
+/**
+ * The held reports of a member as one prompt section (their envelopes and
+ * texts), or undefined when nothing is held — what a turn the room did not
+ * start (a human waking the agent directly) must still carry.
+ */
+export declare function heldReportsText(events: readonly SessionEvent[], recipientId: string): {
+    readonly text: string;
+    readonly seqs: readonly number[];
+} | undefined;
 export interface RunOutcome {
     readonly state: 'done' | 'cancelled' | 'failed';
     readonly text?: string;
@@ -65,6 +101,16 @@ export declare class DispatchEngine {
     private readonly queues;
     private readonly scheduled;
     private readonly inFlight;
+    /** room + recipient → the wake-anyway timer for its held reports. */
+    private readonly holdTimers;
+    /**
+     * room id → member ids whose FIRST start is in flight: the member has no
+     * child session id in the journal yet, but its process may already be
+     * asking the host for its mode tools (claude lists MCP tools at spawn).
+     */
+    private readonly freshStarts;
+    /** Members of this room whose first start is in flight (see {@link freshStarts}). */
+    startingMembers(roomId: string): readonly string[];
     /**
      * @param ctx - host context carrying the session store and agents registry.
      */
@@ -87,19 +133,61 @@ export declare class DispatchEngine {
     recover(room: Session): Promise<void>;
     /** Execute one dispatch: run-state running → member turn → settle edges. */
     private run;
-    private report;
+    /**
+     * Report one delivery's outcome to whoever is waiting on it (the
+     * coordinator for plan work, else the dispatch's `replyTo`), at most once
+     * per delivery. Public so a removal can settle the waits it breaks.
+     */
+    reportOutcome(room: Session, dispatchSeq: number, deliveryId: string, fromId: string, outcome: string, text: string): Promise<void>;
     /**
      * Mark the relays this run delivered as sent. Delivery = the member's own
      * session received the prompt (the followup accepted / the CLI run
      * started): the text lives in the member's private context from then on,
      * so a later run failure cannot un-deliver it.
      */
+    /**
+     * A round of this member started: every report held for it is now in its
+     * context — carried by this prompt (`seqs`) or already in its inbox — so
+     * close those holds and drop the member's wake timer.
+     */
+    markHeldReleased(room: Session, member: RoomMember, seqs: readonly number[]): Promise<void>;
+    private holdKey;
+    private clearHoldTimer;
+    /**
+     * Keep a report for later: journal it as a held dispatch and arm the
+     * wake-anyway timer. It is NOT pushed into an agent inbox: the host runs
+     * one turn per queued inbox message, so held reports would each wake their
+     * own turn. They ride the recipient's next round instead — the room's own
+     * prompt, or (a human waking a native agent directly) the turn's first step
+     * through {@link heldReportsMessage}.
+     */
+    private holdReport;
+    /**
+     * Wake a member for the reports held for it (the hold timeout, a human's
+     * 「现在交给」, or a restart). One short release round: an inbox already
+     * holds the reports; a CLI member gets them carried by the round's prompt.
+     * A no-op when nothing is held any more.
+     * @returns whether a release round was dispatched.
+     */
+    releaseHeld(room: Session, recipientId: string, reason: string): Promise<boolean>;
     private markSent;
     /** Main-agent member turn: a producer-sourced followup on the room's own agent. */
     private runMainAgent;
+    /**
+     * The native member's agent: live, resumed from its session after a
+     * restart, or created on its first round — a child session + agent in this
+     * host process (owned by the room's agent when live), composing the
+     * member's preset at creation. The handle is journaled before any prompt.
+     */
+    private nativeAgent;
+    /**
+     * Native member turn: a room-sourced followup on the member's own agent,
+     * mirrored into the room as speech like a CLI member's reply.
+     */
+    private runNativeMember;
     /** CLI member turn: facade start (first round) or resume, then the speech mirror. */
     private runCliMember;
-    /** Settle only this execution and its own task rows, preserving newer runs. */
+    /** Settle only this execution, preserving newer runs. */
     private settle;
 }
 //# sourceMappingURL=dispatch.d.ts.map