termdock 1.4.173 → 1.4.175

package/dist/server/agent/collaborationCli.js

@@ -0,0 +1,298 @@
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { COLLAB_LIMITS, CollaborationError } from './collaborationProtocol.js';
+export const COLLAB_HELP = `td collab — durable messages; no agent-specific hooks required
+  status | capabilities
+  send <session-id> <message> | reply <message-id> <message> | handoff <session-id> <message>
+    --group <id> --thread <id> --idempotency-key <key>
+    --file <path> | --stdin (instead of inline body; -- ends option parsing)
+    --wait-until queued|delivered|read --timeout 30s
+    --expect-reply ack|result|any
+    --response-kind ack|progress|result --metadata '<JSON object>'
+    --task-envelope '<JSON: task_id,status,progress?,evidence?,blocker?>'
+    --expires-at <ISO timestamp or epoch milliseconds>
+  message get <message-id> [--receipt-only]
+  message read <message-id> (explicit consumption; not application ACK)
+  message watch <message-id> [--wait-until delivered|read] [--timeout 30s]
+  inbox [--unread] [--since <ISO or epoch-ms>] [--after-id <id>]
+    [--cursor <token>] [--consumer <name>] [--limit 1..200]
+    [--from <id>] [--group <id>] [--thread <id>] [--kind <kind>]
+    [--response-kind ack|progress|result] [--follow] [--timeout 30s]
+  cursor commit <token> --consumer <name> (commit after processing the page)
+  add|remove <group-id> <session-id>
+  spawn <group-id> <agent-slug> [--name <name>] [--cwd <path>] [--task <text>]
+  --json (default) | --jsonl | --text
+Exit codes: 0 requested condition met; 1 invalid request/network error;
+2 wait timeout (message may still deliver); 3 failed/expired.
+Message limit: ${COLLAB_LIMITS.message_bytes} UTF-8 bytes; metadata: ${COLLAB_LIMITS.metadata_bytes} bytes.
+Idempotency retention: 7 days. read/ACK/result never imply each other.
+Inbox defaults to unread first, newest 50; cursor/consumer mode reads oldest unseen first.
+Reading never advances a consumer or marks messages read automatically.`;
+const BOOLEAN_OPTIONS = new Set(['json', 'jsonl', 'text', 'unread', 'follow', 'stdin', 'receipt-only', 'help']);
+const VALUE_OPTIONS = new Set(['group', 'thread', 'idempotency-key', 'file', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'kind', 'name', 'cwd', 'task']);
+export function parseCollaborationCommand(argv) {
+    const options = {};
+    const positional = [];
+    let literal = false;
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === '--' && !literal) {
+            literal = true;
+            continue;
+        }
+        if (!literal && value.startsWith('--')) {
+            const [flag, ...inline] = value.slice(2).split('=');
+            if (BOOLEAN_OPTIONS.has(flag)) {
+                if (inline.length)
+                    throw new Error(`--${flag} takes no value`);
+                options[flag] = true;
+            }
+            else if (VALUE_OPTIONS.has(flag)) {
+                const next = inline.length ? inline.join('=') : argv[++index];
+                if (!next || (!inline.length && next.startsWith('--')))
+                    throw new Error(`--${flag} requires a value`);
+                options[flag] = next;
+            }
+            else
+                throw new Error(`Unknown collaboration option: --${flag}`);
+        }
+        else
+            positional.push(value);
+    }
+    const action = (options.help ? 'help' : positional.shift() ?? 'status');
+    if (!['status', 'inbox', 'send', 'handoff', 'reply', 'add', 'remove', 'spawn', 'message', 'cursor', 'capabilities', 'help'].includes(action))
+        throw new Error('Unknown collaboration command; see td collab --help');
+    if (['json', 'jsonl', 'text'].filter((key) => options[key]).length > 1)
+        throw new Error('Choose one output format');
+    if (options['wait-until'] && !['queued', 'delivered', 'read'].includes(String(options['wait-until'])))
+        throw new Error('wait-until must be queued, delivered or read');
+    if (options['expect-reply'] && !['ack', 'result', 'any'].includes(String(options['expect-reply'])))
+        throw new Error('expect-reply must be ack, result or any');
+    if (options.timeout)
+        duration(String(options.timeout));
+    const command = { action, json: !options.text, options };
+    if (['send', 'reply', 'handoff'].includes(action)) {
+        command.target = positional.shift();
+        command.message = positional.join(' ');
+        if (!command.target || (!command.message && !options.file && !options.stdin))
+            throw new Error(`${action} requires a target and message`);
+        if ([Boolean(command.message), Boolean(options.file), Boolean(options.stdin)].filter(Boolean).length !== 1)
+            throw new Error('Choose inline body, --file, or --stdin');
+    }
+    else if (action === 'message') {
+        command.operation = positional.shift();
+        command.target = positional.shift();
+        if (!['get', 'watch', 'read'].includes(command.operation ?? '') || !command.target || positional.length)
+            throw new Error('Usage: td collab message get|watch|read <id>');
+    }
+    else if (action === 'cursor') {
+        command.operation = positional.shift();
+        command.target = positional.shift();
+        if (command.operation !== 'commit' || !command.target || !options.consumer || positional.length)
+            throw new Error('Usage: td collab cursor commit <token> --consumer <name>');
+    }
+    else if (action === 'add' || action === 'remove' || action === 'spawn') {
+        command.groupId = positional.shift();
+        if (action === 'spawn')
+            command.agentSlug = positional.shift();
+        else
+            command.sessionId = positional.shift();
+        if (!command.groupId || !(command.agentSlug || command.sessionId) || positional.length)
+            throw new Error(`${action} requires two identifiers`);
+        command.name = options.name;
+        command.cwd = options.cwd;
+        command.task = options.task;
+    }
+    else if (positional.length && action !== 'help')
+        throw new Error(`Unexpected arguments for ${action}`);
+    const allowed = new Set(['json', 'jsonl', 'text', 'help']);
+    const byAction = {
+        status: [], capabilities: [], help: [...BOOLEAN_OPTIONS, ...VALUE_OPTIONS],
+        send: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'kind'],
+        handoff: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at'],
+        reply: ['idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at'],
+        inbox: ['unread', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'group', 'thread', 'kind', 'response-kind', 'follow', 'timeout'],
+        message: ['receipt-only', 'follow', 'wait-until', 'timeout', 'expect-reply'], cursor: ['consumer'],
+        add: [], remove: [], spawn: ['name', 'cwd', 'task'],
+    };
+    for (const option of byAction[action])
+        allowed.add(option);
+    for (const option of Object.keys(options))
+        if (!allowed.has(option))
+            throw new Error(`--${option} is not supported by ${action}`);
+    if (action === 'message' && command.operation === 'read' && Object.keys(options).some((option) => !['json', 'jsonl', 'text', 'help'].includes(option)))
+        throw new Error('message read does not accept wait or filtering options');
+    return command;
+}
+export function duration(value) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m)?$/.exec(value);
+    const result = match ? Number(match[1]) * (match[2] === 'm' ? 60000 : match[2] === 's' ? 1000 : 1) : NaN;
+    if (!Number.isFinite(result) || result < 1 || result > 86_400_000)
+        throw new Error('timeout must be 1ms–24h, e.g. 30s (plain numbers are milliseconds)');
+    return result;
+}
+export function waitSatisfied(receipt, stage, reply) {
+    const reached = stage === 'queued' || (stage === 'delivered' && ['delivered', 'read'].includes(receipt.status)) || (stage === 'read' && receipt.status === 'read');
+    return reached && (!reply || (reply === 'ack' ? receipt.ack_at != null : reply === 'result' ? receipt.result_ids?.length > 0 : receipt.reply_ids?.length > 0));
+}
+export async function executeCollaborationCommand(command, context, io) {
+    const o = command.options;
+    const now = io.now ?? Date.now;
+    const sleep = io.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let deadline = now() + duration(String(o.timeout ?? '30s'));
+    const query = new URLSearchParams(context);
+    const request = async (method, route, body) => {
+        const response = await io.request(method, `/api/terminal/operations/orchestration${route}${method === 'GET' ? `${route.includes('?') ? '&' : '?'}${query}` : ''}`, method === 'POST' ? { ...context, ...body } : undefined, Math.max(1, Math.min(10000, deadline - now())));
+        let parsed;
+        try {
+            parsed = JSON.parse(response.body);
+        }
+        catch {
+            throw new CollaborationError('INVALID_RESPONSE', 'Service returned a non-JSON response');
+        }
+        if (response.statusCode < 200 || response.statusCode >= 300)
+            throw new CollaborationError(parsed.code ?? 'REQUEST_FAILED', parsed.error ?? 'Collaboration request failed', response.statusCode);
+        return parsed;
+    };
+    const output = (value) => {
+        if (o.text) {
+            if (Array.isArray(value.messages))
+                for (const message of value.messages)
+                    io.write(`[${message.responseKind ?? message.kind}] ${message.id} from ${message.fromSessionId ?? 'user'}\n${message.content}`);
+            else if (value.message)
+                io.write(`[${value.status}] ${value.message_id}\n${value.message.content}`);
+            else if (value.message_id)
+                io.write(`${value.status} ${value.message_id} thread=${value.thread_id}${value.code ? ` ${value.code}` : ''}${value.failure_reason ? ` ${value.failure_reason}` : ''}`);
+            else
+                io.write(JSON.stringify(value, null, 2));
+            if (value.next_cursor)
+                io.write(`next_cursor=${value.next_cursor} has_more=${value.has_more}`);
+        }
+        else if (o.jsonl && Array.isArray(value.messages) && command.action === 'inbox') {
+            for (const message of value.messages)
+                io.write(JSON.stringify({ type: 'message', ...message }));
+            io.write(JSON.stringify({ type: 'cursor', next_cursor: value.next_cursor, has_more: value.has_more, retention_gap: value.retention_gap ?? false, consumer: value.consumer }));
+        }
+        else
+            io.write(JSON.stringify(value, null, o.jsonl || o.follow || command.operation === 'watch' ? undefined : 2));
+    };
+    let receipt;
+    let idempotencyKey;
+    try {
+        if (command.action === 'help') {
+            io.write(COLLAB_HELP);
+            return 0;
+        }
+        if (command.action === 'capabilities' || command.action === 'status') {
+            output(await request('GET', command.action === 'status' ? '/peers' : '/capabilities'));
+            return 0;
+        }
+        if (command.action === 'inbox') {
+            let cursor = o.cursor;
+            do {
+                const params = new URLSearchParams();
+                for (const key of ['unread', 'since', 'after-id', 'consumer', 'limit', 'from', 'group', 'thread', 'kind', 'response-kind'])
+                    if (o[key])
+                        params.set(key.replaceAll('-', '_'), String(o[key]));
+                if (cursor) {
+                    params.set('cursor', cursor);
+                    params.delete('after_id');
+                }
+                const page = await request('GET', `/inbox?${params}`);
+                if (!o.follow || page.messages?.length || page.retention_gap)
+                    output(page);
+                cursor = page.next_cursor;
+                if (!o.follow)
+                    return 0;
+                if (!page.has_more)
+                    await sleep(Math.min(1000, Math.max(0, deadline - now())));
+            } while (now() < deadline);
+            return 0;
+        }
+        if (command.action === 'cursor') {
+            output(await request('POST', '/cursor/commit', { cursor: command.target, consumer: o.consumer }));
+            return 0;
+        }
+        if (command.action === 'message') {
+            const route = `/message/${encodeURIComponent(command.target)}`;
+            if (command.operation === 'read') {
+                output(await request('POST', `${route}/read`));
+                return 0;
+            }
+            receipt = await request('GET', `${route}${o['receipt-only'] || command.operation === 'watch' ? '?receipt_only=true' : ''}`);
+            if (command.operation === 'get' && !o.follow && !o['wait-until'] && !o['expect-reply']) {
+                output(receipt);
+                return 0;
+            }
+        }
+        else if (['send', 'reply', 'handoff'].includes(command.action)) {
+            let content = command.message ?? '';
+            if (o.file) {
+                if (fs.statSync(String(o.file)).size > COLLAB_LIMITS.message_bytes)
+                    throw new Error('Message file exceeds 1 MiB');
+                content = fs.readFileSync(String(o.file), 'utf8');
+            }
+            if (o.stdin) {
+                if (!io.stdin)
+                    throw new Error('stdin is unavailable');
+                content = await io.stdin();
+            }
+            if (Buffer.byteLength(content) > COLLAB_LIMITS.message_bytes)
+                throw new Error('Message exceeds 1 MiB');
+            const expiresAt = o['expires-at'] ? /^\d+$/.test(String(o['expires-at'])) ? Number(o['expires-at']) : Date.parse(String(o['expires-at'])) : undefined;
+            if (expiresAt !== undefined && !Number.isFinite(expiresAt))
+                throw new Error('Invalid expires-at timestamp');
+            idempotencyKey = String(o['idempotency-key'] ?? randomUUID());
+            const extras = { group_id: o.group, thread_id: o.thread, idempotency_key: idempotencyKey, response_kind: o['response-kind'],
+                metadata: o.metadata ? JSON.parse(String(o.metadata)) : undefined, task: o['task-envelope'] ? JSON.parse(String(o['task-envelope'])) : undefined, expires_at: expiresAt };
+            deadline = now() + duration(String(o.timeout ?? '30s'));
+            receipt = await request('POST', command.action === 'reply' ? '/reply' : '/send', command.action === 'reply'
+                ? { ...extras, messageId: command.target, content } : { ...extras, targetSessionId: command.target, message: content, kind: command.action === 'handoff' ? 'handoff' : o.kind ?? 'message' });
+            // CLI receipts stay small even when the message is a large evidence package.
+            delete receipt.messages;
+            receipt.idempotency_key = idempotencyKey;
+        }
+        else {
+            const body = command.action === 'spawn' ? { groupId: command.groupId, agentSlug: command.agentSlug, name: command.name, cwd: command.cwd, task: command.task }
+                : { groupId: command.groupId, targetSessionId: command.sessionId, action: command.action };
+            output(await request('POST', command.action === 'spawn' ? '/spawn' : '/members', body));
+            return 0;
+        }
+        const stage = String(o['wait-until'] ?? (command.action === 'message' ? 'read' : 'queued'));
+        let previous = '';
+        for (;;) {
+            if (['failed', 'expired'].includes(receipt.status)) {
+                output(receipt);
+                return 3;
+            }
+            if (waitSatisfied(receipt, stage, o['expect-reply'])) {
+                output(receipt);
+                return 0;
+            }
+            if (o.follow || command.operation === 'watch') {
+                const serialized = JSON.stringify(receipt);
+                if (serialized !== previous) {
+                    output(receipt);
+                    previous = serialized;
+                }
+            }
+            if (now() >= deadline) {
+                output({ ...receipt, ok: false, code: 'WAIT_TIMEOUT', wait_until: stage, expect_reply: o['expect-reply'] ?? null, delivery_continues: true });
+                return 2;
+            }
+            await sleep(Math.min(500, deadline - now()));
+            if (now() >= deadline)
+                continue;
+            receipt = { ...await request('GET', `/message/${encodeURIComponent(receipt.message_id)}?receipt_only=true`), ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}) };
+        }
+    }
+    catch (error) {
+        if (receipt && now() >= deadline) {
+            output({ ...receipt, ok: false, code: 'WAIT_TIMEOUT', delivery_continues: true, last_error: error instanceof Error ? error.message : String(error) });
+            return 2;
+        }
+        output({ ...(receipt ?? {}), ok: false, code: error instanceof CollaborationError ? error.code : 'COLLABORATION_ERROR',
+            error: error instanceof Error ? error.message : String(error), ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}), ...(receipt ? { delivery_continues: true } : {}) });
+        return 1;
+    }
+}

package/dist/server/agent/collaborationPrompt.js

@@ -24,8 +24,12 @@ export function formatCollaborationDelivery(input) {
             `来自：${source}`,
             `协作组：${group}`,
             '--- 消息内容 ---',
-            message.content,
+            Buffer.byteLength(message.content) > 8_192
+                ? `大消息已完整保存（${Buffer.byteLength(message.content)} 字节）。使用 td collab message get ${message.id} --json 获取正文；不要把这条提示当作任务正文。`
+                : message.content,
             '--- 消息结束 ---',
+            ...(message.responseKind ? [`回复类型：${message.responseKind}（ack=收到，progress=进展，result=结果；结果不保证成功）`] : []),
+            ...(message.task ? [`任务上报：${JSON.stringify(message.task)}`] : []),
         ].join('\n');
     });
     const peerIds = Array.from(new Set(input.groups.flatMap((group) => group.sessionIds)))
@@ -33,7 +37,7 @@ export function formatCollaborationDelivery(input) {
     const peers = peerIds.map((sessionId) => {
         const session = sessionsById.get(sessionId);
         return [
-            `- ${session?.name ?? '离线会话'} · ${session?.status ?? 'offline'}`,
+            `- ${session?.name ?? '离线会话'} · ${session?.status === 'service-unreachable' ? '服务不可达，消息无法送达；仅可排队等待服务重连' : session?.status ?? 'offline'}`,
             ...(session?.agentNativeSessionId ? [`  Agent 原生 Session ID：${session.agentNativeSessionId}`] : []),
             `  Termdock 会话 ID：${sessionId}`,
         ].join('\n');
@@ -49,12 +53,17 @@ export function formatCollaborationDelivery(input) {
         '- 如果没有这种内建能力，则使用下方 Termdock 收件箱命令；命令中的 <会话ID> 指 Termdock 会话 ID。',
         ...(hasUserMessage ? ['- 用户消息：直接在当前会话回答或执行（无来源 Agent，不能运行 `td collab reply`）。'] : []),
         ...(hasAgentMessage ? ['- 回复：`td collab reply <消息ID> "回复内容"`'] : []),
+        ...(peerIds.some((id) => id.startsWith('remote:')) ? ['- 跨服务成员必须使用 td collab 通信；服务不可达时消息尚未送达，不要把 pending 当作成功，也不要假定对方已收到任务。Mac 客户端须保持运行以转发消息。'] : []),
         '- 发消息：`td collab send <会话ID> "消息内容"`',
         '- 交接：`td collab handoff <会话ID> "交接摘要"`',
         '- 加成员：`td collab add <协作组ID> <会话ID>`',
         '- 移成员：`td collab remove <协作组ID> <会话ID>`',
         '- 新建 Agent：`td collab spawn <协作组ID> <agent-slug> --name "名称" --task "初始任务"`',
-        '- 查看：`td collab status` / `td collab inbox`',
+        '- 查看：`td collab status` / `td collab inbox`；完整选项：`td collab --help`。默认 JSON，pending 只表示已入队。',
+        '- 确认投递：`td collab message get <消息ID> --receipt-only`；send/reply 可加 `--wait-until delivered --timeout 30s`。超时不会取消消息，重试使用同一 `--idempotency-key`。',
+        '- 只取新回复：`td collab inbox --consumer <名称> --limit 20`；处理完成后用返回的 next_cursor 执行 `td collab cursor commit <游标> --consumer <名称>`。需要明确标记读取时用 `td collab message read <消息ID>`。',
+        '- 回复应明确类型：reply 加 `--response-kind ack|progress|result`；可附 `--task-envelope` JSON（task_id、status、progress、evidence、blocker）。不要把 ACK 或 turn done 汇报为任务完成。',
+        '- Agent 状态与工具活动只作可选提示；任意接入方都可通过收件箱主动读取、确认和回复，无需专用 hooks。',
     ];
     return [
         `[Termdock 协作收件箱 · ${input.messages.length} 条]`,

package/dist/server/agent/collaborationProtocol.js

@@ -0,0 +1,50 @@
+/** Transport facts and application reports deliberately remain separate. */
+export const COLLAB_LIMITS = {
+    message_bytes: 1_048_576,
+    metadata_bytes: 16_384,
+    wire_bytes: 1_572_864,
+    fragment_bytes: 32_768,
+    fragment_ttl_ms: 86_400_000,
+    idempotency_retention_ms: 7 * 86_400_000,
+    default_page_size: 50,
+    max_page_size: 200,
+};
+export class CollaborationError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus = 400) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+export function validateExtras(input) {
+    if (input.idempotencyKey !== undefined && (typeof input.idempotencyKey !== 'string' || !input.idempotencyKey.trim() || input.idempotencyKey.length > 256)) {
+        throw new CollaborationError('INVALID_IDEMPOTENCY_KEY', 'idempotency key must contain 1–256 characters');
+    }
+    if (input.responseKind !== undefined && !['ack', 'progress', 'result'].includes(input.responseKind))
+        throw new CollaborationError('INVALID_RESPONSE_KIND', 'response_kind must be ack, progress or result');
+    if (input.metadata !== undefined && (!input.metadata || typeof input.metadata !== 'object' || Array.isArray(input.metadata)))
+        throw new CollaborationError('INVALID_METADATA', 'metadata must be a JSON object');
+    const task = input.task;
+    if (task !== undefined && (!task || typeof task.task_id !== 'string' || !task.task_id.trim() || task.task_id.length > 256
+        || !['ack', 'working', 'blocked', 'complete', 'failed'].includes(task.status)
+        || (task.progress !== undefined && (!Number.isFinite(task.progress) || task.progress < 0 || task.progress > 100))
+        || (task.blocker !== undefined && typeof task.blocker !== 'string')))
+        throw new CollaborationError('INVALID_TASK', 'task requires task_id and status; progress is 0–100');
+    const inferred = task ? task.status === 'ack' ? 'ack' : ['complete', 'failed'].includes(task.status) ? 'result' : 'progress' : undefined;
+    if (inferred && input.responseKind && inferred !== input.responseKind)
+        throw new CollaborationError('TASK_KIND_CONFLICT', 'response_kind conflicts with task.status');
+    if (input.expiresAt != null && (!Number.isFinite(input.expiresAt) || input.expiresAt <= 0))
+        throw new CollaborationError('INVALID_EXPIRY', 'expires_at must be an epoch millisecond timestamp');
+    const extras = { idempotencyKey: input.idempotencyKey, responseKind: input.responseKind ?? inferred, metadata: input.metadata, task: input.task, expiresAt: input.expiresAt };
+    if (Buffer.byteLength(JSON.stringify(extras)) > COLLAB_LIMITS.metadata_bytes)
+        throw new CollaborationError('METADATA_TOO_LARGE', `metadata and task envelope exceed ${COLLAB_LIMITS.metadata_bytes} bytes`, 413);
+    return extras;
+}
+export function extrasFromBody(body) {
+    return validateExtras({ idempotencyKey: body.idempotency_key,
+        responseKind: body.response_kind, metadata: body.metadata,
+        task: body.task, expiresAt: body.expires_at });
+}
+export const STATUS_RANK = { pending: 0, failed: 1, expired: 1, delivered: 2, read: 3 };

package/dist/server/agent/collaborationRoutes.js

@@ -0,0 +1,86 @@
+import { Router } from 'express';
+import { COLLAB_LIMITS, CollaborationError, extrasFromBody } from './collaborationProtocol.js';
+export function collaborationRoutes({ store, resolveSession, deliver }) {
+    const router = Router();
+    const run = (handler) => (req, res) => {
+        try {
+            const sessionId = resolveSession((req.method === 'GET' ? req.query : req.body) ?? {});
+            if (!sessionId)
+                throw new CollaborationError('SESSION_NOT_FOUND', 'Run inside a Termdock managed session', 404);
+            handler(req, res, sessionId);
+        }
+        catch (error) {
+            res.status(error instanceof CollaborationError ? error.httpStatus : 400).json({ ok: false,
+                code: error instanceof CollaborationError ? error.code : 'COLLABORATION_ERROR', error: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    const ownMessage = (id, sessionId, recipientOnly = false) => {
+        const message = store.getMessage(id);
+        if (!message || (message.toSessionId !== sessionId && (recipientOnly || message.fromSessionId !== sessionId)))
+            throw new CollaborationError('MESSAGE_NOT_FOUND', 'Message does not belong to this session', 404);
+        return message;
+    };
+    const sent = (res, ids) => {
+        const messages = ids.map((id) => store.getMessage(id));
+        const receipts = ids.map((id) => store.receipt(id));
+        res.json({ ok: true, ...receipts[0], messages, receipts });
+    };
+    router.get('/capabilities', run((_req, res) => {
+        res.json({ protocol_version: 2, limits: COLLAB_LIMITS,
+            statuses: ['pending', 'delivered', 'read', 'failed', 'expired'], queued_status: 'pending',
+            semantics: { delivered: 'written to terminal; no application acknowledgement implied', read: 'explicit consumer acknowledgement',
+                ack: 'explicit response_kind=ack', result: 'explicit response_kind=result; inspect task.status and evidence',
+                done: 'adapter reports turn ended, never proof of task completion', heartbeat: 'null unless explicitly observed',
+                timeout: 'stops waiting, does not cancel delivery' } });
+    }));
+    router.post('/send', run((req, res, sessionId) => {
+        const target = typeof req.body.targetSessionId === 'string' ? req.body.targetSessionId.trim() : '';
+        const groups = store.groupsForSession(sessionId).filter((group) => group.sessionIds.includes(target) && (!req.body.group_id || group.id === req.body.group_id));
+        if (!groups.length)
+            throw new CollaborationError('GROUP_NOT_FOUND', 'Sender and recipient must share the specified group');
+        if (groups.length > 1 && !req.body.group_id)
+            throw new CollaborationError('AMBIGUOUS_GROUP', 'Multiple shared groups; specify --group');
+        const messages = store.send({ ...extrasFromBody(req.body), groupId: groups[0].id, fromSessionId: sessionId, toSessionIds: [target],
+            kind: (req.body.kind ?? 'message'), content: typeof req.body.message === 'string' ? req.body.message : '',
+            threadId: typeof req.body.thread_id === 'string' ? req.body.thread_id : undefined });
+        deliver(target);
+        sent(res, messages.map((message) => message.id));
+    }));
+    router.post('/reply', run((req, res, sessionId) => {
+        const original = ownMessage(String(req.body.messageId ?? ''), sessionId, true);
+        if (!original.fromSessionId)
+            throw new CollaborationError('NO_REPLY_TARGET', 'User messages have no agent reply target');
+        const messages = store.send({ ...extrasFromBody(req.body), groupId: original.groupId, fromSessionId: sessionId,
+            toSessionIds: [original.fromSessionId], kind: 'reply', content: typeof req.body.content === 'string' ? req.body.content : '',
+            replyTo: original.id, threadId: original.threadId });
+        // Reply is explicit consumption; only mark after successful validation/persistence.
+        store.markRead([original.id]);
+        deliver(original.fromSessionId);
+        sent(res, messages.map((message) => message.id));
+    }));
+    router.get('/message/:id', run((req, res, sessionId) => {
+        const message = ownMessage(String(req.params.id), sessionId);
+        res.json({ ok: true, ...store.receipt(message.id), ...(req.query.receipt_only === 'true' ? {} : { message }) });
+    }));
+    router.post('/message/:id/read', run((req, res, sessionId) => {
+        const message = ownMessage(String(req.params.id), sessionId, true);
+        store.markRead([message.id]);
+        res.json({ ok: true, ...store.receipt(message.id) });
+    }));
+    router.get('/inbox', run((req, res, sessionId) => {
+        const string = (key) => typeof req.query[key] === 'string' ? req.query[key] : undefined;
+        const sinceText = string('since');
+        const since = sinceText === undefined ? undefined : /^\d+$/.test(sinceText) ? Number(sinceText) : Date.parse(sinceText);
+        if (since !== undefined && !Number.isFinite(since))
+            throw new CollaborationError('INVALID_SINCE', 'since must be an ISO timestamp or epoch milliseconds');
+        const page = store.page(sessionId, { unread: string('unread') === 'true', since, afterId: string('after_id'), cursor: string('cursor'),
+            consumer: string('consumer'), limit: string('limit') ? Number(string('limit')) : undefined,
+            from: string('from'), group: string('group'), thread: string('thread'), kind: string('kind'), responseKind: string('response_kind'), order: string('order') });
+        res.json({ ok: true, ...page });
+    }));
+    router.post('/cursor/commit', run((req, res, sessionId) => {
+        store.commitCursor(sessionId, String(req.body.cursor ?? ''), String(req.body.consumer ?? ''));
+        res.json({ ok: true, consumer: req.body.consumer, cursor: req.body.cursor });
+    }));
+    return router;
+}