termdock 1.4.174 → 1.4.175

package/dist/server/agent/collaborationStore.js

@@ -1,11 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { COLLAB_LIMITS, CollaborationError, STATUS_RANK, validateExtras } from './collaborationProtocol.js';
 const MAX_MESSAGES = 2_000;
 const MESSAGE_KINDS = new Set(['message', 'ask', 'reply', 'task', 'handoff', 'done']);
 export class CollaborationStore {
     filePath;
     document = { version: 2, groups: [], messages: [] };
+    persistedDocument = JSON.stringify(this.document);
     constructor(filePath) {
         this.filePath = filePath;
         try {
@@ -14,10 +16,21 @@ export class CollaborationStore {
                 this.document.groups = parsed.groups.filter((group) => group && typeof group.id === 'string' && Array.isArray(group.sessionIds));
             }
             if (Array.isArray(parsed.messages)) {
-                this.document.messages = parsed.messages.filter((message) => message && typeof message.id === 'string' && typeof message.toSessionId === 'string' && MESSAGE_KINDS.has(message.kind)).slice(-MAX_MESSAGES);
+                this.document.messages = parsed.messages.filter((message) => message && typeof message.id === 'string' && typeof message.toSessionId === 'string' && MESSAGE_KINDS.has(message.kind));
+                for (const message of this.document.messages) {
+                    message.sequence ??= (this.document.sequence ?? 0) + 1;
+                    this.document.sequence = Math.max(this.document.sequence ?? 0, message.sequence);
+                }
             }
+            this.document.sequence = Math.max(parsed.sequence ?? 0, this.document.sequence ?? 0);
+            this.document.idempotency = parsed.idempotency ?? {};
+            this.document.consumers = parsed.consumers ?? {};
+            this.document.transport = parsed.transport ?? {};
+            this.document.fragments = parsed.fragments ?? {};
+            this.document.prunedThrough = parsed.prunedThrough ?? {};
         }
         catch { /* first run */ }
+        this.persistedDocument = JSON.stringify(this.document);
     }
     list() {
         return this.document.groups.filter((group) => !group.deleted).sort((a, b) => b.updatedAt - a.updatedAt);
@@ -92,21 +105,41 @@ export class CollaborationStore {
             throw new Error('协作组不存在');
         if (!MESSAGE_KINDS.has(input.kind))
             throw new Error('消息类型无效');
-        const content = input.content.trim();
-        if (!content)
+        const extras = validateExtras(input);
+        const content = input.content;
+        if (Buffer.byteLength(content) > COLLAB_LIMITS.message_bytes)
+            throw new CollaborationError('MESSAGE_TOO_LARGE', `Message exceeds ${COLLAB_LIMITS.message_bytes} UTF-8 bytes`, 413);
+        if (!content.trim())
             throw new Error('消息不能为空');
         const recipients = Array.from(new Set(input.toSessionIds)).filter((id) => group.sessionIds.includes(id) && id !== input.fromSessionId);
         if (recipients.length === 0)
             throw new Error('没有有效的接收会话');
         const now = Date.now();
+        const key = input.idempotencyKey ? JSON.stringify([input.groupId, input.fromSessionId, input.idempotencyKey]) : null;
+        const hash = crypto.createHash('sha256').update(stableJson([recipients.slice().sort(), input.kind, content, input.threadId ?? null, input.replyTo ?? null, extras.responseKind, extras.metadata, extras.task, extras.expiresAt])).digest('hex');
+        const previous = key ? this.document.idempotency?.[key] : null;
+        if (previous && previous.expiresAt > now) {
+            if (previous.hash !== hash)
+                throw new CollaborationError('IDEMPOTENCY_CONFLICT', 'This key was already used with a different payload', 409);
+            const originals = previous.ids.map((id) => this.getMessage(id));
+            if (originals.some((message) => !message))
+                throw new CollaborationError('IDEMPOTENCY_RECORD_GONE', 'Original message removed; this key cannot be reused yet', 409);
+            return originals;
+        }
         const threadId = input.threadId?.trim() || crypto.randomUUID();
         const messages = recipients.map((toSessionId) => ({
+            idempotencyKey: input.idempotencyKey, responseKind: extras.responseKind, metadata: extras.metadata, task: extras.task, expiresAt: extras.expiresAt,
+            sequence: this.nextSequence(),
             id: crypto.randomUUID(), groupId: group.id, fromSessionId: input.fromSessionId,
             toSessionId, kind: input.kind, content, threadId,
             replyTo: input.replyTo?.trim() || null, status: 'pending', createdAt: now,
             deliveredAt: null, readAt: null,
         }));
-        this.document.messages = [...this.document.messages, ...messages].slice(-MAX_MESSAGES);
+        if (messages.some((message) => Buffer.byteLength(JSON.stringify(message)) > COLLAB_LIMITS.wire_bytes))
+            throw new CollaborationError('MESSAGE_WIRE_TOO_LARGE', `Encoded message exceeds ${COLLAB_LIMITS.wire_bytes} JSON bytes`, 413);
+        this.document.messages.push(...messages);
+        if (key)
+            (this.document.idempotency ??= {})[key] = { hash, ids: messages.map((message) => message.id), expiresAt: now + COLLAB_LIMITS.idempotency_retention_ms };
         this.persist();
         return messages;
     }
@@ -114,12 +147,18 @@ export class CollaborationStore {
         return this.document.messages.filter((message) => message.groupId === groupId).slice(-Math.max(1, Math.min(limit, 500)));
     }
     getMessage(id) {
+        this.expire();
         return this.document.messages.find((message) => message.id === id) ?? null;
     }
     inbox(sessionId, options = {}) {
-        return this.document.messages
-            .filter((message) => message.toSessionId === sessionId && (!options.pendingOnly || message.status === 'pending'))
-            .slice(-Math.max(1, Math.min(options.limit ?? 50, 200)));
+        this.expire();
+        const matches = this.document.messages.filter((message) => message.toSessionId === sessionId && (!options.pendingOnly || message.status === 'pending'));
+        const limit = Math.max(1, Math.min(options.limit ?? 50, 200));
+        return options.pendingOnly ? matches.slice(0, limit) : matches.slice(-limit);
+    }
+    pendingCount(sessionId) {
+        this.expire();
+        return this.document.messages.filter((message) => message.toSessionId === sessionId && message.status === 'pending').length;
     }
     markDelivered(messageIds) {
         return this.updateStatus(messageIds, 'delivered');
@@ -129,14 +168,15 @@ export class CollaborationStore {
     }
     updateStatus(messageIds, status) {
         const ids = new Set(messageIds);
+        this.expire();
         const now = Date.now();
         const changed = [];
         this.document.messages = this.document.messages.map((message) => {
-            if (!ids.has(message.id))
+            if (!ids.has(message.id) || message.status === 'expired' || message.status === 'failed' || message.status === 'read')
                 return message;
             const updated = status === 'read'
-                ? { ...message, status, deliveredAt: message.deliveredAt ?? now, readAt: now }
-                : message.status === 'pending' ? { ...message, status, deliveredAt: now } : message;
+                ? { ...message, status, deliveredAt: message.deliveredAt ?? now, readAt: now, readSource: 'explicit', deliverySource: message.deliverySource ?? (message.deliveredAt === null ? 'consumer_read' : 'legacy_or_unspecified') }
+                : message.status === 'pending' ? { ...message, status, deliveredAt: now, deliverySource: 'pty_written' } : message;
             changed.push(updated);
             return updated;
         });
@@ -145,9 +185,11 @@ export class CollaborationStore {
         return changed;
     }
     federationSnapshot() {
+        this.expire();
         const groups = this.document.groups.filter((group) => group.federated);
         const ids = new Set(groups.filter((group) => !group.deleted).map((group) => group.id));
-        return { groups, messages: this.document.messages.filter((message) => ids.has(message.groupId)) };
+        const messages = this.document.messages.filter((message) => ids.has(message.groupId));
+        return { groups, messages, transportDiagnostics: Object.fromEntries(messages.flatMap((message) => this.document.transport?.[message.id] ? [[message.id, this.document.transport[message.id]]] : [])) };
     }
     mergeFederatedGroup(group) {
         if (!group.federated || typeof group.id !== 'string' || !group.id.startsWith('cross-') || typeof group.name !== 'string' || !group.name.trim()
@@ -169,7 +211,7 @@ export class CollaborationStore {
     }
     mergeFederatedMessages(messages) {
         let changed = false;
-        const rank = { pending: 0, delivered: 1, read: 2 };
+        const rank = STATUS_RANK;
         for (const message of messages) {
             if (!message || typeof message !== 'object')
                 continue;
@@ -178,31 +220,217 @@ export class CollaborationStore {
                 || (message.fromSessionId !== null && !group.sessionIds.includes(message.fromSessionId))
                 || typeof message.id !== 'string' || typeof message.threadId !== 'string' || !Number.isFinite(message.createdAt)
                 || typeof message.content !== 'string'
-                || message.content.length > 20_000 || !MESSAGE_KINDS.has(message.kind)
-                || !Object.hasOwn(rank, message.status))
+                || Buffer.byteLength(message.content) > COLLAB_LIMITS.message_bytes || !MESSAGE_KINDS.has(message.kind)
+                || !Object.hasOwn(rank, message.status) || Buffer.byteLength(JSON.stringify(message)) > COLLAB_LIMITS.wire_bytes)
                 continue;
+            try {
+                validateExtras(message);
+            }
+            catch {
+                continue;
+            }
             const index = this.document.messages.findIndex((item) => item.id === message.id);
             if (index < 0) {
-                this.document.messages.push(message);
+                this.document.messages.push({ ...message, sequence: this.nextSequence() });
                 changed = true;
             }
             else if (rank[message.status] > rank[this.document.messages[index].status]) {
                 const existing = this.document.messages[index];
                 // A receipt may advance status, but never rewrite an existing message.
                 this.document.messages[index] = { ...existing, status: message.status,
-                    deliveredAt: message.deliveredAt, readAt: message.readAt };
+                    deliveredAt: message.deliveredAt, readAt: message.readAt, failureReason: message.failureReason, readSource: message.readSource, deliverySource: message.deliverySource };
                 changed = true;
             }
         }
-        if (changed) {
-            this.document.messages = this.document.messages.slice(-MAX_MESSAGES);
+        if (changed)
+            this.persist();
+    }
+    nextSequence() { return this.document.sequence = (this.document.sequence ?? 0) + 1; }
+    expire() {
+        let changed = false;
+        for (const message of this.document.messages)
+            if (message.status === 'pending' && message.expiresAt && message.expiresAt <= Date.now()) {
+                message.status = 'expired';
+                message.failureReason = 'MESSAGE_EXPIRED';
+                changed = true;
+            }
+        if (changed)
+            this.persist();
+    }
+    fail(id, reason) {
+        const message = this.getMessage(id);
+        if (message?.status === 'pending') {
+            message.status = 'failed';
+            message.failureReason = reason;
+            this.persist();
+        }
+    }
+    diagnostic(id) { return this.document.transport?.[id] ?? null; }
+    recordTransport(id, diagnostic) {
+        if (!this.getMessage(id))
+            return;
+        (this.document.transport ??= {})[id] = diagnostic;
+        this.persist();
+    }
+    receipt(id) {
+        const message = this.getMessage(id);
+        if (!message)
+            throw new CollaborationError('MESSAGE_NOT_FOUND', 'Message not found or no longer retained', 404);
+        const replies = this.document.messages.filter((reply) => reply.replyTo === id && reply.fromSessionId === message.toSessionId && reply.toSessionId === message.fromSessionId);
+        const diagnostic = this.diagnostic(id);
+        return { message_id: id, thread_id: message.threadId, status: message.status, queued_at: message.createdAt,
+            delivered_at: message.deliveredAt, read_at: message.readAt, expires_at: message.expiresAt ?? null,
+            failure_reason: message.failureReason ?? null, delivery_semantics: message.deliverySource ?? (message.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'), read_semantics: message.readAt ? message.readSource ?? 'legacy_or_unspecified' : 'not_read',
+            idempotency_key: message.idempotencyKey ?? null,
+            ack_at: replies.find((reply) => reply.responseKind === 'ack')?.createdAt ?? null,
+            reply_ids: replies.map((reply) => reply.id), result_ids: replies.filter((reply) => reply.responseKind === 'result').map((reply) => reply.id),
+            response_kind: message.responseKind ?? null, task: message.task ?? null,
+            size_bytes: Buffer.byteLength(message.content),
+            relay_online: diagnostic && Date.now() - diagnostic.checked_at < 15_000 ? diagnostic.relay_online : null,
+            peer_reachable: diagnostic && Date.now() - diagnostic.checked_at < 15_000 ? diagnostic.peer_reachable : null,
+            attempt_count: diagnostic?.attempt_count ?? 0, next_retry_at: diagnostic?.next_retry_at ?? null,
+            last_error: diagnostic?.last_error ?? null, transport_checked_at: diagnostic?.checked_at ?? null,
+            fragments_sent: diagnostic?.fragments_sent ?? 0, fragments_total: diagnostic?.fragments_total ?? 0 };
+    }
+    sessionFacts(sessionId, online, turnState) {
+        const reports = this.document.messages.filter((message) => message.fromSessionId === sessionId);
+        const tasks = new Map();
+        for (const message of reports)
+            if (message.task)
+                tasks.set(message.task.task_id, { task_id: message.task.task_id, status: message.task.status, reported_at: message.createdAt, message_id: message.id });
+        return { session_state: online ? 'online' : 'offline', turn_state: turnState === 'done' ? 'ended' : turnState ?? 'unknown',
+            task_state: 'unknown', tasks: [...tasks.values()], last_heartbeat: null, last_tool_activity_at: null,
+            last_message_at: reports.length ? Math.max(...reports.map((message) => message.createdAt)) : null,
+            state_source: 'optional_adapter', task_source: 'explicit_message' };
+    }
+    page(sessionId, options = {}) {
+        this.expire();
+        if (options.responseKind && !['ack', 'progress', 'result'].includes(options.responseKind))
+            throw new CollaborationError('INVALID_RESPONSE_KIND', 'response_kind must be ack, progress or result');
+        if (options.kind && !MESSAGE_KINDS.has(options.kind))
+            throw new CollaborationError('INVALID_KIND', 'Unknown message kind');
+        const limit = options.limit ?? COLLAB_LIMITS.default_page_size;
+        if (!Number.isInteger(limit) || limit < 1 || limit > COLLAB_LIMITS.max_page_size)
+            throw new CollaborationError('INVALID_LIMIT', 'limit must be 1–200');
+        if (options.consumer !== undefined && (!options.consumer || options.consumer.length > 128))
+            throw new CollaborationError('INVALID_CONSUMER', 'consumer must contain 1–128 characters');
+        if (options.cursor && options.afterId)
+            throw new CollaborationError('INVALID_CURSOR', 'Choose cursor or after-id');
+        const scope = JSON.stringify([sessionId, options.group ?? null, options.thread ?? null, options.from ?? null, options.kind ?? null, options.responseKind ?? null, options.unread ?? false, options.since ?? null]);
+        const consumerKey = JSON.stringify([scope, options.consumer]);
+        let after = options.consumer ? this.document.consumers?.[consumerKey] ?? 0 : 0;
+        if (options.cursor) {
+            try {
+                const decoded = JSON.parse(Buffer.from(options.cursor, 'base64url').toString());
+                if (decoded.scope !== scope || !Number.isSafeInteger(decoded.sequence) || decoded.sequence < 0)
+                    throw new Error();
+                after = decoded.sequence;
+            }
+            catch {
+                throw new CollaborationError('INVALID_CURSOR', 'Cursor is invalid or belongs to different filters');
+            }
+        }
+        if (options.afterId) {
+            const anchor = this.getMessage(options.afterId);
+            if (!anchor || anchor.toSessionId !== sessionId)
+                throw new CollaborationError('CURSOR_GONE', 'after-id is unknown or no longer retained; resync explicitly', 410);
+            after = anchor.sequence ?? 0;
+        }
+        const incremental = Boolean(options.cursor || options.afterId || options.consumer || options.since !== undefined);
+        const candidates = this.document.messages.filter((message) => message.toSessionId === sessionId && (message.sequence ?? 0) > after
+            && (!options.unread || message.status !== 'read') && (options.since === undefined || message.createdAt > options.since)
+            && (!options.from || message.fromSessionId === options.from) && (!options.group || message.groupId === options.group)
+            && (!options.thread || message.threadId === options.thread) && (!options.kind || message.kind === options.kind)
+            && (!options.responseKind || message.responseKind === options.responseKind))
+            .sort((a, b) => (a.sequence ?? 0) - (b.sequence ?? 0));
+        const messages = incremental || options.order === 'oldest' ? candidates.slice(0, limit) : candidates.slice().sort((a, b) => Number(a.status === 'read') - Number(b.status === 'read') || (b.sequence ?? 0) - (a.sequence ?? 0)).slice(0, limit);
+        const sequence = messages.length ? Math.max(...messages.map((message) => message.sequence ?? 0)) : after;
+        const next_cursor = Buffer.from(JSON.stringify({ scope, sequence })).toString('base64url');
+        return { messages, next_cursor, retention_gap: incremental && after < (this.document.prunedThrough?.[sessionId] ?? 0), has_more: incremental ? candidates.length > messages.length : false, consumer: options.consumer ?? null };
+    }
+    commitCursor(sessionId, cursor, consumer) {
+        if (!consumer || consumer.length > 128)
+            throw new CollaborationError('INVALID_CONSUMER', 'consumer must contain 1–128 characters');
+        try {
+            const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString());
+            if (JSON.parse(decoded.scope)[0] !== sessionId || !Number.isSafeInteger(decoded.sequence) || decoded.sequence < 0 || decoded.sequence > (this.document.sequence ?? 0))
+                throw new Error();
+            const key = JSON.stringify([decoded.scope, consumer]);
+            (this.document.consumers ??= {})[key] = Math.max(this.document.consumers?.[key] ?? 0, decoded.sequence);
             this.persist();
         }
+        catch {
+            throw new CollaborationError('INVALID_CURSOR', 'Invalid consumption cursor');
+        }
+    }
+    acceptFragment(fragment) {
+        const group = this.getGroup(fragment.group_id);
+        if (!group?.federated || group.deleted || typeof fragment.message_id !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(fragment.message_id) || ['__proto__', 'constructor', 'prototype'].includes(fragment.message_id) || !Number.isInteger(fragment.total) || fragment.total < 1 || fragment.total > 64
+            || !Number.isInteger(fragment.index) || fragment.index < 0 || fragment.index >= fragment.total || !/^[a-f0-9]{64}$/.test(fragment.sha256)
+            || typeof fragment.data !== 'string' || !/^[A-Za-z0-9+/]*={0,2}$/.test(fragment.data) || Buffer.from(fragment.data, 'base64').length > COLLAB_LIMITS.fragment_bytes)
+            throw new CollaborationError('INVALID_FRAGMENT', 'Invalid message fragment');
+        const existing = this.getMessage(fragment.message_id);
+        if (existing) {
+            if (existing.groupId !== fragment.group_id)
+                throw new CollaborationError('FRAGMENT_CONFLICT', 'Message belongs to another group', 409);
+            return { message_id: existing.id, received: fragment.total, total: fragment.total, complete: true };
+        }
+        const fragments = this.document.fragments ??= {};
+        for (const [id, state] of Object.entries(fragments))
+            if (state.createdAt + COLLAB_LIMITS.fragment_ttl_ms < Date.now())
+                delete fragments[id];
+        if (!fragments[fragment.message_id] && Object.keys(fragments).length >= 32)
+            throw new CollaborationError('FRAGMENT_CAPACITY', 'Too many incomplete messages', 429);
+        const state = fragments[fragment.message_id] ??= { groupId: fragment.group_id, total: fragment.total, sha256: fragment.sha256, chunks: {}, createdAt: Date.now() };
+        if (state.groupId !== fragment.group_id || state.total !== fragment.total || state.sha256 !== fragment.sha256 || (state.chunks[fragment.index] && state.chunks[fragment.index] !== fragment.data))
+            throw new CollaborationError('FRAGMENT_CONFLICT', 'Conflicting fragment', 409);
+        state.chunks[fragment.index] = fragment.data;
+        const received = Object.keys(state.chunks).length;
+        if (received === state.total) {
+            const bytes = Buffer.concat(Array.from({ length: state.total }, (_, index) => Buffer.from(state.chunks[index], 'base64')));
+            if (crypto.createHash('sha256').update(bytes).digest('hex') !== state.sha256)
+                throw new CollaborationError('FRAGMENT_CHECKSUM', 'Message checksum mismatch');
+            const message = JSON.parse(bytes.toString());
+            if (message.id !== fragment.message_id || message.groupId !== fragment.group_id)
+                throw new CollaborationError('FRAGMENT_IDENTITY', 'Message identity mismatch');
+            this.mergeFederatedMessages([message]);
+            if (!this.getMessage(message.id))
+                throw new CollaborationError('INVALID_MESSAGE', 'Reassembled message rejected');
+            delete fragments[fragment.message_id];
+        }
+        this.persist();
+        return { message_id: fragment.message_id, received, total: state.total, complete: received === state.total };
     }
     persist() {
-        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        const now = Date.now();
+        for (const [key, record] of Object.entries(this.document.idempotency ?? {}))
+            if (record.expiresAt <= now)
+                delete this.document.idempotency[key];
+        const protectedIds = new Set(Object.values(this.document.idempotency ?? {}).flatMap((record) => record.ids));
+        const history = this.document.messages.filter((message) => message.status !== 'pending' && !protectedIds.has(message.id)).slice(-MAX_MESSAGES);
+        const retained = new Set(history.map((message) => message.id));
+        this.document.messages = this.document.messages.filter((message) => {
+            if (message.status === 'pending' || protectedIds.has(message.id) || retained.has(message.id))
+                return true;
+            (this.document.prunedThrough ??= {})[message.toSessionId] = Math.max(this.document.prunedThrough?.[message.toSessionId] ?? 0, message.sequence ?? 0);
+            delete this.document.transport?.[message.id];
+            return false;
+        });
         const temporaryPath = `${this.filePath}.${process.pid}.tmp`;
-        fs.writeFileSync(temporaryPath, JSON.stringify(this.document, null, 2), { mode: 0o600 });
-        fs.renameSync(temporaryPath, this.filePath);
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            const serialized = JSON.stringify(this.document);
+            fs.writeFileSync(temporaryPath, serialized, { mode: 0o600 });
+            fs.renameSync(temporaryPath, this.filePath);
+            this.persistedDocument = serialized;
+        }
+        catch (error) {
+            this.document = JSON.parse(this.persistedDocument);
+            throw error;
+        }
     }
 }
+function stableJson(value) {
+    return JSON.stringify(value, (_key, entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+        ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b))) : entry);
+}

package/dist/server/cli.js

@@ -10,6 +10,12 @@ import { resolve } from 'path';
 // dotenv 不会覆盖已存在的环境变量，因此系统环境变量和命令行参数优先级最高
 loadDotenv({ path: resolve(os.homedir(), '.termdock', '.env'), quiet: true });
 loadDotenv({ path: resolve(process.cwd(), '.env'), quiet: true });
+// Federation commands run before normal server/terminal CLI initialization.
+if (process.argv.slice(2).some(arg => arg === '--federation-pairing' || arg === '--federation-relay')) {
+    const { runFederationCli } = await import('./federation/cli.js');
+    process.exit(await runFederationCli(process.argv.slice(2)));
+}
+import { parseCollaborationCommand, executeCollaborationCommand, COLLAB_HELP } from './agent/collaborationCli.js';
 import fs from 'fs';
 import http from 'http';
 import https from 'https';
@@ -183,7 +189,7 @@ Short commands:
                      Emit one lifecycle/status event from an Agent hook.
   pi                 Same as agent-plugin
   collab status      Show this Session's collaboration groups and peers
-  collab inbox       Read and acknowledge collaboration messages
+  collab inbox       Read messages without acknowledging (see collab --help)
   collab send <session-id> <message>
                      Send a durable message to a related Session
   collab handoff <session-id> <summary>
@@ -678,53 +684,11 @@ function parseArgs(argv) {
             }
         }
         else if (command === 'collab') {
-            const action = (next || 'status');
-            const json = argv.includes('--json');
-            if (action === 'status' || action === 'inbox') {
-                collab = { action, json };
-            }
-            else if (action === 'send' || action === 'handoff' || action === 'reply') {
-                const target = argv[2];
-                const message = argv.slice(3).filter((part) => part !== '--json').join(' ').trim();
-                if (!target || !message) {
-                    console.error(`${ICON.err} ${c.red(`Usage: td collab ${action} <${action === 'reply' ? 'message-id' : 'session-id'}> <message>`)}`);
-                    process.exit(1);
-                }
-                collab = { action, target, message, json };
-            }
-            else if (action === 'add' || action === 'remove') {
-                const groupId = argv[2];
-                const sessionId = argv[3];
-                if (!groupId || !sessionId || groupId.startsWith('-') || sessionId.startsWith('-')) {
-                    console.error(`${ICON.err} ${c.red(`Usage: td collab ${action} <group-id> <session-id>`)}`);
-                    process.exit(1);
-                }
-                collab = { action, groupId, sessionId, json };
-            }
-            else if (action === 'spawn') {
-                const groupId = argv[2];
-                const agentSlug = argv[3];
-                const optionValue = (flag) => {
-                    const index = argv.indexOf(flag);
-                    const value = index >= 0 ? argv[index + 1] : undefined;
-                    return value && !value.startsWith('--') ? value : undefined;
-                };
-                if (!groupId || !agentSlug || groupId.startsWith('-') || agentSlug.startsWith('-')) {
-                    console.error(`${ICON.err} ${c.red('Usage: td collab spawn <group-id> <agent-slug> [--name <name>] [--cwd <path>] [--task <text>]')}`);
-                    process.exit(1);
-                }
-                collab = {
-                    action,
-                    groupId,
-                    agentSlug,
-                    name: optionValue('--name'),
-                    cwd: optionValue('--cwd'),
-                    task: optionValue('--task'),
-                    json,
-                };
+            try {
+                collab = parseCollaborationCommand(argv.slice(1));
             }
-            else {
-                console.error(`${ICON.err} ${c.red('Usage: td collab <status|inbox|send|handoff|reply|add|remove|spawn>')}`);
+            catch (error) {
+                console.error(JSON.stringify({ ok: false, code: 'INVALID_ARGUMENT', error: error instanceof Error ? error.message : String(error) }));
                 process.exit(1);
             }
             argv = [];
@@ -1219,7 +1183,7 @@ async function readStdinText() {
         process.stdin.on('error', reject);
     });
 }
-async function postLocalJson(baseUrl, token, endpoint, payload) {
+async function postLocalJson(baseUrl, token, endpoint, payload, timeoutMs = 30_000) {
     const url = new URL(endpoint, baseUrl);
     const body = JSON.stringify(payload);
     const isHttps = url.protocol === 'https:';
@@ -1244,12 +1208,14 @@ async function postLocalJson(baseUrl, token, endpoint, payload) {
             res.on('data', (chunk) => { responseBody += chunk; });
             res.on('end', () => resolve({ statusCode: res.statusCode ?? 0, body: responseBody }));
         });
+        const timer = setTimeout(() => req.destroy(new Error('Local collaboration request timed out')), timeoutMs);
+        req.on('close', () => clearTimeout(timer));
         req.on('error', reject);
         req.write(body);
         req.end();
     });
 }
-async function getLocalJson(baseUrl, token, endpoint) {
+async function getLocalJson(baseUrl, token, endpoint, timeoutMs = 30_000) {
     const url = new URL(endpoint, baseUrl);
     const isHttps = url.protocol === 'https:';
     const requestImpl = isHttps ? https.request : http.request;
@@ -1271,14 +1237,20 @@ async function getLocalJson(baseUrl, token, endpoint) {
             res.on('data', (chunk) => { responseBody += chunk; });
             res.on('end', () => resolve({ statusCode: res.statusCode ?? 0, body: responseBody }));
         });
+        const timer = setTimeout(() => req.destroy(new Error('Local collaboration request timed out')), timeoutMs);
+        req.on('close', () => clearTimeout(timer));
         req.on('error', reject);
         req.end();
     });
 }
 async function runCollab(command) {
+    if (command.action === 'help') {
+        console.log(COLLAB_HELP);
+        return;
+    }
     const runningState = getRunningState();
     if (!runningState?.localApiToken) {
-        console.error(`${ICON.err} ${c.red('Termdock is not running or its local API token is unavailable.')}`);
+        console.error(JSON.stringify({ ok: false, code: 'SERVICE_UNAVAILABLE', error: 'Termdock is not running or its local API token is unavailable.' }));
         process.exit(1);
     }
     const backendSessionId = process.env.TERMDOCK_BACKEND_SESSION_ID?.trim() || null;
@@ -1299,128 +1271,16 @@ async function runCollab(command) {
         }
     }
     if (!backendSessionId && !tmuxSessionName) {
-        console.error(`${ICON.err} ${c.red('td collab must run inside a Termdock-managed Session.')}`);
+        console.error(JSON.stringify({ ok: false, code: 'SESSION_NOT_FOUND', error: 'td collab must run inside a Termdock-managed Session.' }));
         process.exit(1);
     }
     const context = backendSessionId ? { backendSessionId } : { tmuxSessionName };
-    const contextQuery = new URLSearchParams(Object.entries(context).filter((entry) => typeof entry[1] === 'string')).toString();
     const baseUrl = runningState.localUrl
         ?? `${runningState.scheme ?? 'http'}://${runningState.host === '0.0.0.0' ? 'localhost' : runningState.host}:${runningState.port}`;
-    let response;
-    if (command.action === 'status') {
-        response = await getLocalJson(baseUrl, runningState.localApiToken, `/api/terminal/operations/orchestration/peers?${contextQuery}`);
-    }
-    else if (command.action === 'inbox') {
-        response = await getLocalJson(baseUrl, runningState.localApiToken, `/api/terminal/operations/orchestration/inbox?${contextQuery}&markRead=true`);
-    }
-    else if (command.action === 'reply') {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/reply', {
-            ...context,
-            messageId: command.target,
-            content: command.message,
-        });
-    }
-    else if (command.action === 'add' || command.action === 'remove') {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/members', {
-            ...context,
-            groupId: command.groupId,
-            targetSessionId: command.sessionId,
-            action: command.action,
-        });
-    }
-    else if (command.action === 'spawn') {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/spawn', {
-            ...context,
-            groupId: command.groupId,
-            agentSlug: command.agentSlug,
-            name: command.name,
-            cwd: command.cwd,
-            task: command.task,
-        });
-    }
-    else {
-        response = await postLocalJson(baseUrl, runningState.localApiToken, '/api/terminal/operations/orchestration/send', {
-            ...context,
-            targetSessionId: command.target,
-            message: command.message,
-            kind: command.action === 'handoff' ? 'handoff' : 'message',
-        });
-    }
-    let body = {};
-    try {
-        body = JSON.parse(response.body || '{}');
-    }
-    catch { /* handled below */ }
-    if (response.statusCode < 200 || response.statusCode >= 300) {
-        console.error(`${ICON.err} ${c.red(typeof body.error === 'string' ? body.error : 'Collaboration request failed')}`);
-        process.exit(1);
-    }
-    if (command.json) {
-        console.log(JSON.stringify(body, null, 2));
-        return;
-    }
-    if (command.action === 'status') {
-        const groups = Array.isArray(body.groups) ? body.groups : [];
-        const peers = Array.isArray(body.peers) ? body.peers : [];
-        const sessions = Array.isArray(body.sessions) ? body.sessions : [];
-        const agents = Array.isArray(body.agents) ? body.agents : [];
-        console.log(`${ICON.ok} ${c.green(`Collaboration: ${groups.length} group(s), ${peers.length} peer(s)`)}`);
-        for (const group of groups) {
-            console.log(`  ${c.green(group.name ?? 'Group')} ${c.dim(`[${group.id ?? ''}]`)}`);
-            if (group.sessionIds?.length)
-                console.log(`    ${c.dim(`${group.sessionIds.length} member(s)`)}`);
-        }
-        if (peers.length > 0)
-            console.log(`\n${c.dim('Current group peers:')}`);
-        for (const peer of peers) {
-            console.log(`  ${c.cyan(peer.name ?? peer.sessionId ?? 'Session')} ${c.dim(`[${peer.sessionId ?? ''}]`)}`);
-            console.log(`    ${peer.status ?? 'offline'} · ${peer.capability ?? ''}`);
-            if (peer.currentTask)
-                console.log(`    ${c.dim(peer.currentTask)}`);
-        }
-        for (const group of groups) {
-            const memberIds = new Set(group.sessionIds ?? []);
-            const candidates = sessions.filter((session) => session.sessionId && !memberIds.has(session.sessionId));
-            if (candidates.length > 0) {
-                console.log(`\n${c.dim(`Sessions available to add to ${group.name ?? 'group'} [${group.id ?? ''}]:`)}`);
-                for (const session of candidates) {
-                    console.log(`  ${session.name ?? 'Session'} ${c.dim(`[${session.sessionId ?? ''}]`)} · ${session.status ?? 'offline'}`);
-                    if (session.cwd)
-                        console.log(`    ${c.dim(session.cwd)}`);
-                }
-            }
-        }
-        if (agents.length > 0) {
-            console.log(`\n${c.dim('Agent types available to spawn:')}`);
-            for (const agent of agents)
-                console.log(`  ${agent.displayName ?? agent.slug ?? 'Agent'} ${c.dim(`[${agent.slug ?? ''}]`)}`);
-        }
-        return;
-    }
-    if (command.action === 'inbox') {
-        const messages = Array.isArray(body.messages) ? body.messages : [];
-        if (messages.length === 0) {
-            console.log(`${ICON.ok} ${c.dim('Collaboration inbox is empty.')}`);
-            return;
-        }
-        for (const message of messages) {
-            console.log(`${c.cyan(message.kind ?? 'message')} ${c.dim(`#${message.id ?? ''}`)} from ${message.fromSessionId ?? 'user'}`);
-            console.log(`  ${message.content ?? ''}`);
-        }
-        return;
-    }
-    const delivery = body.delivery;
-    if (delivery?.reason) {
-        console.log(`${delivery.serviceUnavailable ? '服务不可达' : '等待投递'}: ${delivery.reason}`);
-        return;
-    }
-    const success = command.action === 'reply' ? 'Reply sent.'
-        : command.action === 'handoff' ? 'Handoff sent.'
-            : command.action === 'add' ? 'Session added to collaboration group.'
-                : command.action === 'remove' ? 'Session removed from collaboration group.'
-                    : command.action === 'spawn' ? 'Agent Session created and added to collaboration group.'
-                        : 'Message sent.';
-    console.log(`${ICON.ok} ${c.green(success)}`);
+    process.exitCode = await executeCollaborationCommand(command, Object.fromEntries(Object.entries(context).filter((entry) => typeof entry[1] === 'string')), { request: (method, endpoint, body, timeout) => method === 'GET'
+            ? getLocalJson(baseUrl, runningState.localApiToken, endpoint, timeout)
+            : postLocalJson(baseUrl, runningState.localApiToken, endpoint, body, timeout),
+        write: (line) => console.log(line), stdin: readStdinText });
 }
 async function runInjectChangeAudit(source) {
     const raw = source === true
@@ -3463,7 +3323,7 @@ async function main() {
     }
     if (options.collab) {
         await runCollab(options.collab);
-        process.exit(0);
+        return; // Preserve the receipt exit code and allow piped JSON output to drain.
     }
     if (options.pluginInit) {
         if (options.pluginInitJson)