@khorsheed/dsh-room 0.2.2 → 0.2.3

package/lib/types/messaging.js

@@ -0,0 +1,160 @@
+/**
+ * Member messaging: one path for every agent-originated message in a room —
+ * the coordinator's delegations, free member-to-member messages (`task`
+ * gets the recipient's reply reported back, `notify` is FYI), and delivery
+ * reports. Each message is either journaled as a `room/dispatch` and handed
+ * to the engine, or HELD as a pending relay carrying its would-be dispatch,
+ * because the room is paused, the causal chain reached the hop limit, or the
+ * room asks the human to confirm member messages. Releasing a held message
+ * creates exactly the dispatch it would have been.
+ *
+ * Every dispatch knows its `hop` (position in the chain that a human message
+ * starts) and renders an envelope line on delivery — who sent it, its
+ * `#m<seq>` id, and whether a reply is expected — so a member can tell
+ * concurrent requests apart and the report names the message it answers.
+ * @module @khorsheed/dsh-room/messaging
+ */
+import { randomUUID } from 'node:crypto';
+import { coordinatorMember, memberId, replay } from './journal.js';
+/** `RoomHeldDispatch.task` marker: this send starts a task rooted at the dispatch itself. */
+export const SELF_TASK = '@self';
+/** The id members and the UI use for a dispatch. */
+export function messageId(seq) {
+    return `m${seq}`;
+}
+/** Parse `m12` / `#m12` / `12` back to a dispatch seq. */
+export function parseMessageRef(ref) {
+    const match = ref === undefined ? null : /^#?m?(\d+)$/.exec(ref.trim());
+    return match === null ? undefined : Number(match[1]);
+}
+/** The hop a dispatch sits at (legacy dispatches count as a chain start). */
+export function dispatchHop(events, seq) {
+    const event = events.find(row => row.seq === seq);
+    return event?.type === 'room/dispatch' ? event.data.hop ?? 1 : 1;
+}
+/**
+ * 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 function workingHop(events, state, member) {
+    const run = state.runs.find(entry => entry.member === member.name && entry.state === 'running');
+    const seq = run?.runId === undefined ? undefined : Number(run.runId.split(':', 1)[0]);
+    return seq === undefined || !Number.isInteger(seq) ? 0 : dispatchHop(events, seq);
+}
+/**
+ * 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 function holdReason(state, hop, origin) {
+    const settings = state.settings;
+    if (settings === undefined)
+        return undefined;
+    if (settings.paused)
+        return 'paused';
+    if (hop > settings.hopLimit)
+        return 'hop-limit';
+    if (origin === 'member' && settings.memberMessages === 'confirm')
+        return 'confirm';
+    return undefined;
+}
+/**
+ * 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 function sendOrHold(session, message, skipHold = false) {
+    const events = session.snapshotEvents();
+    const state = replay(events);
+    const reason = skipHold ? undefined : holdReason(state, message.intent.hop, message.intent.origin);
+    if (reason !== undefined) {
+        const relayId = randomUUID();
+        session.append('room/relay', {
+            id: relayId, from: message.fromName, to: message.to.name, content: message.text, reason, intent: message.intent,
+        });
+        return { delivered: false, reason, relayId };
+    }
+    const targetId = memberId(events, message.to);
+    const intent = message.intent;
+    const id = randomUUID();
+    // A send that starts a task of its own (no human message behind it) roots the task at itself.
+    const task = intent.task === SELF_TASK ? id : intent.task;
+    const dispatch = session.append('room/dispatch', {
+        id, origin: intent.origin,
+        ...task === undefined ? {} : { task },
+        ...intent.parent === undefined ? {} : { parent: intent.parent }, targets: [message.to.name], targetIds: [targetId], text: message.text, hop: intent.hop,
+        ...intent.from === undefined ? {} : { from: intent.from },
+        ...intent.kind === undefined ? {} : { kind: intent.kind },
+        ...intent.inReplyTo === undefined ? {} : { inReplyTo: intent.inReplyTo },
+        ...intent.note === undefined ? {} : { note: intent.note },
+        ...intent.replyTo === undefined ? {} : { replyTo: intent.replyTo },
+        ...intent.reportFor === undefined ? {} : { reportFor: intent.reportFor },
+        ...intent.plan === undefined ? {} : { plan: intent.plan },
+        ...intent.help === undefined ? {} : { help: intent.help },
+    });
+    return { delivered: true, seq: dispatch.seq };
+}
+/**
+ * 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 function releaseIntent(relay) {
+    if (relay.intent === undefined)
+        return undefined;
+    return relay.reason === 'hop-limit' ? { ...relay.intent, hop: 1 } : relay.intent;
+}
+const OUTCOME_LABEL = {
+    done: '完成', cancelled: '已取消', failed: '失败', uncertain: '结果不确定',
+};
+/**
+ * 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 function envelopeLine(events, seq) {
+    const event = events.find(row => row.seq === seq);
+    if (event?.type !== 'room/dispatch')
+        return undefined;
+    const dispatch = event.data;
+    const state = replay(events);
+    const nameOf = (id) => id === undefined ? undefined
+        : state.members.find(member => memberId(events, member) === id)?.name
+            ?? events.reduce((name, row) => row.type === 'room/member-added' && row.data.id === id ? row.data.name : name, undefined);
+    const reply = dispatch.inReplyTo === undefined ? '' : ` · 回复 #${messageId(dispatch.inReplyTo)}`;
+    switch (dispatch.origin) {
+        case 'human':
+        case undefined:
+            // The human's own words need no envelope: an unmarked message is theirs.
+            return undefined;
+        case 'report': {
+            // Plan bookkeeping reports (goal-start:/reconcile:) carry their own text.
+            if (dispatch.reportFor === undefined || !/^\d+:/.test(dispatch.reportFor))
+                return undefined;
+            const source = Number(dispatch.reportFor.split(':', 1)[0]);
+            const sender = nameOf(dispatch.reportFor?.split(':').slice(1).join(':'));
+            const outcome = events.filter(row => row.type === 'room/delivery-state' && row.data.id === dispatch.reportFor).at(-1);
+            const label = outcome?.type === 'room/delivery-state' ? OUTCOME_LABEL[outcome.data.state] ?? outcome.data.state : '';
+            return `【#${messageId(source)} 的回报${sender === undefined ? '' : ` · 来自 ${sender}`}${label === '' ? '' : ` · ${label}`}】（这条回复用户已在房间里看到，不要复述）`;
+        }
+        case 'relay':
+            return undefined;
+        case 'help':
+            return `【来自协作间「${dispatch.help?.roomTitle ?? ''}」· ${dispatch.help?.from ?? ''} 的求助 · #${messageId(seq)}】（对方在另一个会话里，看不到这个房间；你这一轮的最终回复会自动送回对方，写成给对方看的答复，不用另外回复）`;
+        default: {
+            const sender = nameOf(dispatch.from)
+                ?? (dispatch.origin === 'coordinator' ? coordinatorMember(state, events)?.name : undefined) ?? '成员';
+            if (dispatch.kind === 'notify')
+                return `【来自 ${sender} · #${messageId(seq)} · 知会${reply}】`;
+            const back = dispatch.replyTo === undefined && dispatch.plan === undefined ? '' : '（你这一轮的最终回复会自动回报给对方，不用另外回复）';
+            return `【来自 ${sender} · #${messageId(seq)} · 派活${reply}】${back}`;
+        }
+    }
+}

package/lib/types/plan-service.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { coordinatorMember, memberId, replay } from './journal.js';
 import { activePlanMs, dependencyResults, admitPlanAttempt, changePlan, parsePlanCommand, planCommandSignature, queuePlanAttempt, readyPlanTasks, recoverPlan, settlePlanAttempt } from './plan.js';
+import { runChildSessionId, runChildTurn } from './dispatch.js';
 export function readPlan(room) {
     const event = room.snapshotEvents().filter(event => event.type === 'room/plan-state').at(-1);
     return event?.type === 'room/plan-state' ? structuredClone(event.data) : undefined;
@@ -192,9 +193,14 @@ export class PlanService {
             const deliveryId = `${dispatch.seq}:${target}`;
             const member = state.members.find(member => memberId(events, member) === target);
             const run = state.runs.find(run => run.member === member?.name);
-            if (run?.runId === deliveryId && ['running', 'failed'].includes(run.state))
+            if (run?.runId === deliveryId && ['running', 'failed'].includes(run.state)) {
+                const childSessionId = runChildSessionId(room.id, member);
+                const childTurn = runChildTurn(childSessionId === undefined ? undefined : this.ctx.sessions.get(childSessionId));
                 room.append('room/run-state', { member: run.member, runId: run.runId, startedAt: run.startedAt, state: attempt.status === 'submitted' ? 'done' : 'failed',
+                    ...childSessionId === undefined ? {} : { childSessionId },
+                    ...childTurn === undefined ? {} : { childTurn },
                     ...attempt.status === 'failed' ? { error: attempt.submission?.summary ?? 'Human reconciled the attempt as failed' } : {} });
+            }
             room.append('room/delivery-state', { id: deliveryId, dispatchSeq: dispatch.seq, memberId: target,
                 state: attempt.status === 'submitted' ? 'done' : 'failed', text: attempt.submission?.summary ?? 'Human reconciliation' });
             for (const oldReport of events) {

package/lib/types/report-gate.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The report gate: decides only WHEN a delivery's report is handed to the
+ * member waiting on it — now (a round that wakes it), or held in its inbox
+ * until more results arrive. What the recipient then says or does next is
+ * its own call; the gate never edits, drops or summarizes a report, and a
+ * held report still reaches the recipient (a native agent's inbox, or carried
+ * by a CLI member's next round).
+ *
+ * Rules answer first: failures and uncertain outcomes, the last outstanding
+ * result, the `each` setting, and an unavailable decision model all hand the
+ * report over now. Otherwise the decision model answers the `report-timing`
+ * scenario question (decisions.ts) from what the recipient said it waits for,
+ * how long the human has been waiting, and the progress of everything still
+ * out; the room's threshold turns its probability into now / later.
+ * @module @khorsheed/dsh-room/report-gate
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { RoomDecisionCall, RoomDelivery, RoomMember } from './types.ts';
+/** The gate's verdict. */
+export interface GateVerdict {
+    readonly hold: boolean;
+    readonly reason: string;
+    readonly probability?: number;
+    /** The decision-model call behind it, when one went out. */
+    readonly call?: RoomDecisionCall;
+}
+/** One arrived report, as the gate sees it. */
+export interface ArrivedReport {
+    readonly from: string;
+    readonly outcome: string;
+    readonly text: string;
+}
+/** Deliveries still out that report to this member (queued or running), newest first. */
+export declare function outstandingFor(deliveries: readonly RoomDelivery[], recipientId: string, except: string): readonly RoomDelivery[];
+/**
+ * The state the decision model judges.
+ * @param events - the room log.
+ * @param recipient - the member waiting on the report.
+ * @param arrived - this report plus the ones held for the same member.
+ * @param now - the clock.
+ * @returns a JSON-safe state.
+ */
+export declare function gateState(events: readonly SessionEvent[], recipient: RoomMember, arrived: readonly ArrivedReport[], now: number): unknown;
+/**
+ * Decide whether to hand a report over now.
+ * @param ctx - host context (probes `typesafe`).
+ * @param input - what the rules and the model read.
+ * @returns the verdict with its reason.
+ */
+export declare function judgeReport(ctx: Context, input: {
+    readonly timing: 'judge' | 'each';
+    readonly outcome: string;
+    readonly outstanding: number;
+    /** The "hand it over now" probability at or above which the report is delivered (default 0.5). */
+    readonly threshold?: number;
+    readonly state: () => unknown;
+}): Promise<GateVerdict>;
+/** One open task offered to the attribution question. */
+export interface OpenTaskSummary {
+    readonly number: number;
+    readonly title: string;
+    readonly running: readonly string[];
+}
+/**
+ * Suggest which open task a new human message continues, or `new`. Only
+ * asked while some task is still open; the coordinator sees the suggestion
+ * and can override it when it dispatches (`task`).
+ * @param ctx - host context (probes `typesafe`).
+ * @param message - the new human message text.
+ * @param open - the open tasks.
+ * @returns the suggested task number (or `new`) with its probability and the call, or `new` by the `unavailable` rule.
+ */
+export declare function suggestTask(ctx: Context, message: string, open: readonly OpenTaskSummary[]): Promise<{
+    readonly task: number | 'new';
+    /** The rule that decided (`unavailable` after a failed or missing model); absent = the model decided. */
+    readonly rule?: string;
+    readonly probability?: number;
+    readonly call?: RoomDecisionCall;
+}>;
+//# sourceMappingURL=report-gate.d.ts.map

package/lib/types/report-gate.js

@@ -0,0 +1,89 @@
+import { memberId, replay } from './journal.js';
+import { askDecisionModel, DECISION_SCENARIOS, hasDecisionModel } from './decisions.js';
+/** Deliveries still out that report to this member (queued or running), newest first. */
+export function outstandingFor(deliveries, recipientId, except) {
+    return deliveries.filter(row => row.id !== except && row.replyTo === recipientId && (row.status === 'queued' || row.status === 'running'));
+}
+/**
+ * The state the decision model judges.
+ * @param events - the room log.
+ * @param recipient - the member waiting on the report.
+ * @param arrived - this report plus the ones held for the same member.
+ * @param now - the clock.
+ * @returns a JSON-safe state.
+ */
+export function gateState(events, recipient, arrived, now) {
+    const state = replay(events);
+    const recipientId = memberId(events, recipient);
+    const lastHuman = events.filter(event => event.type === 'user/message' && event.data.source.kind === 'user').at(-1);
+    const lastSpoken = events.filter(event => event.type === 'assistant/message' && event.seq > (lastHuman?.seq ?? -1)).at(-1);
+    const nameOf = (id) => state.members.find(member => memberId(events, member) === id)?.name ?? id;
+    const since = lastHuman?.seq ?? -1;
+    const batch = (state.deliveries ?? []).filter(row => row.replyTo === recipientId && row.dispatchSeq > since);
+    const running = (state.executions ?? []).filter(row => row.state === 'running');
+    const notes = batch.flatMap((row) => {
+        const event = events.find(entry => entry.seq === row.dispatchSeq);
+        return event?.type === 'room/dispatch' && event.data.note !== undefined ? [event.data.note] : [];
+    });
+    return {
+        userRequest: lastHuman?.type === 'user/message'
+            ? lastHuman.data.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n').slice(0, 2000) : '',
+        coordinatorNotes: [...new Set(notes)],
+        userWaitingSeconds: Math.max(0, Math.round((now - (lastSpoken?.time ?? lastHuman?.time ?? now)) / 1000)),
+        progress: {
+            done: batch.filter(row => !['queued', 'running'].includes(row.status)).length,
+            total: batch.length,
+            running: batch.filter(row => row.status === 'queued' || row.status === 'running').map((row) => {
+                const execution = running.find(entry => entry.id === row.id);
+                return { member: nameOf(row.memberId), task: row.text.slice(0, 200), seconds: execution === undefined ? 0 : Math.round((now - execution.startedAt) / 1000) };
+            }),
+        },
+        arrived: arrived.map(report => ({ ...report, text: report.text.slice(0, 1500) })),
+    };
+}
+/**
+ * Decide whether to hand a report over now.
+ * @param ctx - host context (probes `typesafe`).
+ * @param input - what the rules and the model read.
+ * @returns the verdict with its reason.
+ */
+export async function judgeReport(ctx, input) {
+    if (input.timing === 'each')
+        return { hold: false, reason: 'setting' };
+    if (input.outcome !== 'done')
+        return { hold: false, reason: 'failure' };
+    if (input.outstanding === 0)
+        return { hold: false, reason: 'last' };
+    if (!hasDecisionModel(ctx))
+        return { hold: false, reason: 'unavailable' };
+    const asked = await askDecisionModel(ctx, DECISION_SCENARIOS['report-timing'].question, input.state());
+    if (!asked.ok || typeof asked.answer !== 'number') {
+        return { hold: false, reason: 'unavailable', ...asked.call === undefined ? {} : { call: asked.call } };
+    }
+    return { hold: asked.answer < (input.threshold ?? 0.5), reason: 'model', probability: asked.answer, call: asked.call };
+}
+/**
+ * Suggest which open task a new human message continues, or `new`. Only
+ * asked while some task is still open; the coordinator sees the suggestion
+ * and can override it when it dispatches (`task`).
+ * @param ctx - host context (probes `typesafe`).
+ * @param message - the new human message text.
+ * @param open - the open tasks.
+ * @returns the suggested task number (or `new`) with its probability and the call, or `new` by the `unavailable` rule.
+ */
+export async function suggestTask(ctx, message, open) {
+    if (!hasDecisionModel(ctx))
+        return { task: 'new', rule: 'unavailable' };
+    const scenario = DECISION_SCENARIOS['task-filing'].question;
+    const criteria = Object.fromEntries(open.map(job => [String(job.number),
+        `Continues task ${job.number}: "${job.title.slice(0, 200)}"${job.running.length === 0 ? '' : ` (still running: ${job.running.join(', ')})`}`]));
+    criteria['new'] = 'Starts a new, unrelated task';
+    const asked = await askDecisionModel(ctx, { ...scenario, criteria }, {
+        message: message.slice(0, 2000),
+        openTasks: open.map(job => ({ number: job.number, title: job.title.slice(0, 200), running: job.running })),
+    });
+    if (!asked.ok || typeof asked.answer !== 'string')
+        return { task: 'new', rule: 'unavailable', ...asked.call === undefined ? {} : { call: asked.call } };
+    const probability = asked.probabilities?.[asked.answer] ?? 0;
+    return { task: asked.answer === 'new' ? 'new' : Number(asked.answer), probability, call: asked.call };
+}

package/lib/types/tool-definition.d.ts

@@ -1,4 +1,29 @@
-import type { RoomAddTaskRequest, RoomAddTaskResult, RoomCloseTaskRequest, RoomCloseTaskResult, RoomGetStateRequest, RoomGetStateResult, RoomInviteRequest, RoomInviteResult, RoomMessageRequest, RoomMessageResult, RoomUpdateTaskRequest, RoomUpdateTaskResult } from './types.ts';
+/**
+ * The room's model-facing tool DEFINITIONS, `room_invite` and
+ * `room_message` (plus `room_read` and `room_plan`): the main
+ * agent's paths into the room it belongs to. `room_invite` and
+ * `room_message` PROMOTE: calling them in a plain session turns it into a
+ * room (ensureRoom) instead of rejecting.
+ * `room_invite` lands in the same invite path as the human dialog
+ * (`invitedBy: 'agent'`), producing an identical member record; `room_message` dispatches
+ * a message to a member through the same engine path as the human's
+ * `@member text`, minus the user bubble (the caller is the room's own agent).
+ *
+ * Since the tool-row split (M4') the core never REGISTERS these tools: the
+ * factories are consumed by the package's `./tool` subpath row
+ * ({@link file://./tool.ts}), which mounts them inside agent-preset
+ * compositions (session-granted, never at the profile root). The definitions
+ * are therefore returned UNTAGGED — the registering row applies its own
+ * tool-origin tag (AGENTS.md § Tool origin tagging — the owner is whichever
+ * package mounts the row).
+ *
+ * Internal module: not on the package's exports map (consumers reach it only
+ * through `./src/*`).
+ *
+ * @module @khorsheed/dsh-room
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { RoomGetStateRequest, RoomGetStateResult, RoomInviteRequest, RoomInviteResult, RoomMessageRequest, RoomMessageResult } from './types.ts';
 /** The slice of RoomService the tool drives. */
 export interface RoomInviteToolBackend {
     /** Validate and journal an invitation (see RoomService.inviteMember). */
@@ -10,25 +35,6 @@ export interface RoomInviteToolBackend {
  * @returns a registry-ready tool definition.
  */
 export declare function roomInviteTool(backend: RoomInviteToolBackend): import("@deepseek-ai/dsh-tools").ToolDefinition;
-/** The slice of RoomService the room_task tool drives. */
-export interface RoomTaskToolBackend {
-    /** Open a pending task on a member's lane (see RoomService.addTask). */
-    addTask(request: RoomAddTaskRequest): Promise<RoomAddTaskResult>;
-    /** Close an open task (see RoomService.closeTask). */
-    closeTask(request: RoomCloseTaskRequest): Promise<RoomCloseTaskResult>;
-    /** Edit an open task's title/blockedBy (see RoomService.updateTask). */
-    updateTask(request: RoomUpdateTaskRequest): Promise<RoomUpdateTaskResult>;
-    /** Replay the room state (the error texts read the roster/open tasks from it). */
-    getState(request: RoomGetStateRequest): Promise<RoomGetStateResult>;
-}
-/**
- * Build the room_task tool definition bound to the room service. Every write
- * goes through the same host functions as the capsule UI, so a task the agent
- * opens is a public commitment indistinguishable from a human-added one.
- * @param backend - the room service.
- * @returns a registry-ready tool definition.
- */
-export declare function roomTaskTool(backend: RoomTaskToolBackend): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** The slice of RoomService the room_message tool drives. */
 export interface RoomMessageToolBackend {
     /** Dispatch one message to one member (see RoomService.messageMember). */
@@ -53,4 +59,21 @@ export declare function roomReadTool(backend: {
 export declare function roomPlanTool(backend: {
     commandPlan(sessionId: string, command: string): Promise<string>;
 }): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The slice of RoomService the help tool drives. */
+export interface RoomHelpToolBackend {
+    /** Ask another session for help, or write again on a thread (see RoomService.askHelp). */
+    askHelp(request: {
+        readonly sessionId: string;
+        readonly session?: string;
+        readonly member?: string;
+        readonly help?: string;
+        readonly text: string;
+    }, caller: Agent): Promise<string>;
+}
+/**
+ * Build the room_help tool definition bound to the room service.
+ * @param backend - the room service.
+ * @returns a registry-ready tool definition.
+ */
+export declare function roomHelpTool(backend: RoomHelpToolBackend): import("@deepseek-ai/dsh-tools").ToolDefinition;
 //# sourceMappingURL=tool-definition.d.ts.map