termdock 1.4.231 → 1.4.232

package/dist/server/agent/collaborationPeerTransport.js

@@ -0,0 +1,441 @@
+import { encryptedRequestSubject } from '../federation/requestContext.js';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import WebSocket from 'ws';
+import { AsyncQueue, toBase64, fromBase64, PacketChannel } from '../federation/packets.js';
+import { secureConnection } from '../federation/secureProtocol.js';
+import { socketDuplex } from '../federation/socketDuplex.js';
+import { readPinnedCertificateAuthority } from '../federation/trustedCa.js';
+import { COLLAB_LIMITS, STATUS_RANK } from './collaborationProtocol.js';
+import { terminalMessage } from './collaborationStore.js';
+/** The outer API gate already authenticated local CLI tokens. Browser callers
+ * additionally need durable administration authority; open-access sessions may
+ * not turn temporary access into persistent peer authorization. */
+export function assertPeerRegistrationAuthority(req) {
+    const subjectId = encryptedRequestSubject(req);
+    if (!subjectId)
+        return;
+    const runtime = req.app.locals.passwordRuntime;
+    if (!runtime?.store.authorize({ subjectId, serviceId: runtime.serviceId, action: 'authorization.manage' }).allowed)
+        throw new Error('AUTHORIZATION_DENIED');
+}
+export function remoteSession(origin, id) { return `remote:${encodeURIComponent(origin)}:${encodeURIComponent(id)}`; }
+function localSession(origin, id) {
+    const prefix = `remote:${encodeURIComponent(origin)}:`;
+    return id.startsWith(prefix) ? decodeURIComponent(id.slice(prefix.length)) : id;
+}
+export function validateCollaborationNode(input) {
+    const url = new URL(input.origin);
+    if (url.protocol !== 'https:' || url.origin !== input.origin || url.username || url.password
+        || !/^12D3KooW[a-zA-Z0-9]{30,60}$/.test(input.serviceId)
+        || (input.caFingerprint256 !== undefined && !/^(?:[\da-f]{2}:){31}[\da-f]{2}$/i.test(input.caFingerprint256)))
+        throw new Error('INVALID_COLLABORATION_NODE');
+}
+function mapContext(context, map) {
+    return { instructions: context.instructions ? { ...context.instructions, updatedBy: map(context.instructions.updatedBy) } : undefined,
+        roles: context.roles ? Object.fromEntries(Object.entries(context.roles).map(([id, role]) => [map(id), role])) : undefined,
+        roleVersions: context.roleVersions ? Object.fromEntries(Object.entries(context.roleVersions).map(([id, revision]) => [map(id), revision])) : undefined };
+}
+/** Small RPC client over the same authenticated Noise transport as the page.
+ * No cookies, browser device keys, or direct HTTP business requests. */
+export class CollaborationRpc {
+    channel;
+    pending = new Map();
+    closed = false;
+    constructor(channel) {
+        this.channel = channel;
+        void this.read();
+        void channel.done.catch(error => this.close(error));
+    }
+    async read() {
+        try {
+            for await (const packet of this.channel.read()) {
+                const request = this.pending.get(packet.id);
+                if (!request)
+                    continue;
+                clearTimeout(request.timer);
+                this.pending.delete(packet.id);
+                if (packet.type === 'error')
+                    request.reject(new Error(String(packet.error)));
+                else
+                    request.resolve(packet);
+            }
+        }
+        catch (error) {
+            this.close(error instanceof Error ? error : new Error('PEER_DISCONNECTED'));
+        }
+        finally {
+            this.close();
+        }
+    }
+    request(packet) {
+        if (this.closed)
+            return Promise.reject(new Error('PEER_DISCONNECTED'));
+        if (this.pending.size >= 8)
+            return Promise.reject(new Error('PEER_BUSY'));
+        return new Promise((resolve, reject) => {
+            const id = randomUUID();
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new Error('PEER_TIMEOUT')); this.close(); }, 10_000);
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                this.channel.send({ ...packet, id });
+            }
+            catch (error) {
+                this.close(error instanceof Error ? error : new Error('PEER_DISCONNECTED'));
+            }
+        });
+    }
+    close(error = new Error('PEER_DISCONNECTED')) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.channel.close();
+        for (const item of this.pending.values()) {
+            clearTimeout(item.timer);
+            item.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+export async function connectCollaborationRpc(identity, peer, endpoint) {
+    validateCollaborationNode(peer);
+    const ca = peer.caFingerprint256 ? await readPinnedCertificateAuthority(peer.origin, peer.caFingerprint256) : undefined;
+    const url = endpoint ?? `${peer.origin.replace(/^https:/, 'wss:')}/api/federation/secure`;
+    const socket = new WebSocket(url, { ca, rejectUnauthorized: true, followRedirects: false, handshakeTimeout: 3000, maxPayload: 1024 * 1024 });
+    const relay = endpoint ? relayDuplex(socket, peer.serviceId) : undefined;
+    const duplex = relay?.duplex ?? socketDuplex(socket);
+    try {
+        await new Promise((resolve, reject) => {
+            socket.once('open', resolve);
+            socket.once('error', reject);
+            socket.once('close', () => reject(new Error('PEER_DISCONNECTED')));
+        });
+        if (relay)
+            await relay.ready;
+        const secured = await secureConnection({ identity, duplex, initiator: true, targetPinnedPeerId: peer.serviceId, signal: AbortSignal.timeout(5000) });
+        return new CollaborationRpc(new PacketChannel(secured.duplex));
+    }
+    catch (error) {
+        socket.terminate();
+        throw error;
+    }
+}
+function relayDuplex(socket, target) {
+    const queue = new AsyncQueue(64), streamId = randomUUID();
+    let readyResolve, readyReject;
+    const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+    void ready.catch(() => { });
+    const timer = setTimeout(() => fail(new Error('ROUTE_TIMEOUT')), 5000);
+    const fail = (error) => { clearTimeout(timer); readyReject(error); queue.end(error); socket.close(); };
+    const send = (frame) => {
+        if (socket.readyState !== 1 || socket.bufferedAmount > 1024 * 1024)
+            throw new Error('ROUTE_CONGESTED');
+        socket.send(JSON.stringify(frame));
+    };
+    socket.on('error', fail);
+    socket.on('close', () => fail(new Error('ROUTE_CLOSED')));
+    socket.on('message', (raw, binary) => {
+        try {
+            if (binary || raw.toString().length > 256 * 1024)
+                throw new Error('INVALID_RELAY_FRAME');
+            const frame = JSON.parse(raw.toString());
+            if (frame.type === 'ready') {
+                send({ type: 'open', streamId, serviceId: target });
+                return;
+            }
+            if (frame.streamId !== streamId)
+                return;
+            if (frame.type === 'opened') {
+                clearTimeout(timer);
+                readyResolve();
+                return;
+            }
+            if (frame.type !== 'data' || frame.encoding !== 'base64' || typeof frame.payload !== 'string')
+                throw new Error('ROUTE_CLOSED');
+            queue.push(fromBase64(frame.payload));
+        }
+        catch (error) {
+            fail(error instanceof Error ? error : new Error('INVALID_RELAY_FRAME'));
+        }
+    });
+    return { ready, duplex: { source: queue, close: () => socket.close(), async sink(source) {
+                await ready;
+                for await (const bytes of source)
+                    for (let offset = 0; offset < bytes.length; offset += 65536) {
+                        while (socket.bufferedAmount > 256 * 1024) {
+                            if (socket.readyState !== 1)
+                                throw new Error('ROUTE_CLOSED');
+                            await new Promise(resolve => setTimeout(resolve, 10));
+                        }
+                        send({ type: 'data', streamId, encoding: 'base64', payload: toBase64(bytes.subarray(offset, offset + 65536)) });
+                    }
+            } } };
+}
+/** Group-scoped, durable server-to-server delivery. A binding is installed only
+ * by an already authorized group administrator, never by the remote peer itself. */
+export class CollaborationPeerTransport {
+    options;
+    bindings = [];
+    clients = new Map();
+    running = new Set();
+    accepted = new Set();
+    shellConfirmed = new Set();
+    nextAttempt = new Map();
+    timer;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+        try {
+            const data = JSON.parse(readFileSync(options.file, 'utf8'));
+            if (data.version === 1 && Array.isArray(data.bindings))
+                this.bindings = data.bindings.filter((b) => {
+                    try {
+                        validateCollaborationNode(b.peer);
+                        return typeof b.groupId === 'string' && new URL(b.localOrigin).origin === b.localOrigin;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+        }
+        catch { /* First run has no server authorizations. */ }
+    }
+    notify() {
+        for (const b of this.bindings) {
+            const key = `${b.groupId}:${b.peer.serviceId}`;
+            if (!this.options.store.federationSnapshot().messages.some(m => m.groupId === b.groupId && m.status === 'pending'
+                && this.options.store.diagnostic(m.id)?.last_error))
+                this.nextAttempt.delete(key);
+        }
+        // A queued message may arrive while an empty scan is finishing.
+        setImmediate(() => this.wake());
+    }
+    start() { this.options.store.onMessageQueued = () => this.notify(); this.timer = setInterval(() => this.wake(), 500); this.timer.unref(); this.wake(); }
+    close() { this.stopped = true; this.options.store.onMessageQueued = undefined; clearInterval(this.timer); for (const client of this.clients.values())
+        void client.then(c => c.close()).catch(() => { }); this.clients.clear(); }
+    live(b) {
+        const group = this.options.store.getGroup(b.groupId);
+        return !!group && !group.deleted && group.federated && group.sessionIds.some(id => id.startsWith(`remote:${encodeURIComponent(b.peer.origin)}:`));
+    }
+    configure(groupId, localOrigin, nodes) {
+        if (!Array.isArray(nodes) || nodes.length > 64)
+            throw new Error('INVALID_COLLABORATION_NODES');
+        const group = this.options.store.getGroup(groupId);
+        if (!group || group.deleted || !group.federated)
+            throw new Error('GROUP_NOT_FOUND');
+        const local = nodes.find(n => n.serviceId === this.options.serviceId);
+        if (!local || local.origin !== localOrigin)
+            throw new Error('LOCAL_NODE_MISMATCH');
+        for (const node of nodes)
+            validateCollaborationNode(node);
+        const peers = nodes.filter(n => n.serviceId !== this.options.serviceId && group.sessionIds.some(id => id.startsWith(`remote:${encodeURIComponent(n.origin)}:`)));
+        const next = [...this.bindings.filter(b => b.groupId !== groupId), ...peers.map(peer => ({ groupId, localOrigin, peer }))];
+        if (JSON.stringify(next) !== JSON.stringify(this.bindings)) {
+            mkdirSync(dirname(this.options.file), { recursive: true, mode: 0o700 });
+            const temp = `${this.options.file}.${process.pid}.tmp`;
+            writeFileSync(temp, JSON.stringify({ version: 1, bindings: next }), { mode: 0o600 });
+            renameSync(temp, this.options.file);
+            this.bindings = next;
+            this.nextAttempt.clear();
+            for (const client of this.clients.values())
+                void client.then(c => c.close()).catch(() => { });
+            this.clients.clear();
+        }
+        this.notify();
+    }
+    canRoute(subjectId, targetId) {
+        return this.bindings.some(b => b.peer.serviceId === subjectId && this.live(b)
+            && this.bindings.some(target => target.groupId === b.groupId && target.peer.serviceId === targetId && this.live(target)));
+    }
+    binding(subjectId, groupId) {
+        const binding = this.bindings.find(b => b.peer.serviceId === subjectId && b.groupId === groupId && this.live(b));
+        if (!binding)
+            throw new Error('COLLABORATION_NOT_AUTHORIZED');
+        return binding;
+    }
+    /** Remote peers can submit only their own members' messages and query receipts
+     * for those messages. They cannot create groups, rewrite bodies or administer sessions. */
+    receive(subjectId, packet) {
+        const b = this.binding(subjectId, String(packet.groupId));
+        const store = this.options.store;
+        if (packet.context)
+            store.mergeContext(b.groupId, mapContext(packet.context, id => localSession(b.localOrigin, id)));
+        if (packet.message) {
+            const message = packet.message;
+            if (message.groupId !== b.groupId || typeof message.fromSessionId !== 'string' || message.fromSessionId.startsWith('remote:')
+                || typeof message.toSessionId !== 'string' || !message.toSessionId.startsWith(`remote:${encodeURIComponent(b.localOrigin)}:`)
+                || Buffer.byteLength(JSON.stringify(message)) > COLLAB_LIMITS.wire_bytes)
+                throw new Error('INVALID_PEER_MESSAGE');
+            const incoming = { ...message, fromSessionId: remoteSession(b.peer.origin, message.fromSessionId),
+                toSessionId: localSession(b.localOrigin, message.toSessionId), status: 'pending', deliveredAt: null, readAt: null,
+                snapshot: null, deliverySource: undefined, readSource: undefined, shellConfirmed: message.shellConfirmed === true };
+            const existing = store.getMessage(message.id);
+            if (existing && (existing.groupId !== incoming.groupId || existing.fromSessionId !== incoming.fromSessionId
+                || existing.toSessionId !== incoming.toSessionId || existing.content !== incoming.content))
+                throw new Error('MESSAGE_ID_CONFLICT');
+            if (!existing)
+                store.mergeFederatedMessages([incoming]);
+            else if (incoming.shellConfirmed && !existing.shellConfirmed)
+                store.mergeFederatedMessages([{ ...existing, shellConfirmed: true }]);
+            if (!store.getMessage(message.id))
+                throw new Error('PEER_REJECTED_MESSAGE');
+            this.options.deliver(incoming.toSessionId);
+        }
+        if (!Array.isArray(packet.ids) || packet.ids.length > 20 || packet.ids.some(id => typeof id !== 'string'))
+            throw new Error('INVALID_RECEIPT_IDS');
+        const receipts = packet.ids.flatMap(id => {
+            const message = store.getMessage(id);
+            if (!message || message.groupId !== b.groupId || !message.fromSessionId?.startsWith(`remote:${encodeURIComponent(b.peer.origin)}:`)
+                || message.toSessionId.startsWith('remote:'))
+                return [];
+            const facts = terminalMessage(message);
+            const known = Array.isArray(packet.known) ? packet.known.find((item) => item?.id === message.id) : undefined;
+            if (known && known.status === facts.status && known.deliveredAt === facts.deliveredAt && known.shellConfirmed === message.shellConfirmed && (known.hasSnapshot || !message.snapshot))
+                return [];
+            const receipt = store.receipt(message.id);
+            return [{ id: message.id, status: facts.status, deliveredAt: facts.deliveredAt,
+                    snapshot: (receipt.snapshot ?? '').slice(0, 16000) || null, deliverySource: facts.deliverySource,
+                    failureReason: message.failureReason, shellConfirmed: message.shellConfirmed, last_error: store.diagnostic(message.id)?.last_error ?? null }];
+        });
+        const group = store.getGroup(b.groupId);
+        const activity = this.options.activity?.().filter(item => group.sessionIds.includes(item.sessionId) && !item.sessionId.startsWith('remote:')) ?? [];
+        return { activity, context: mapContext(store.context(b.groupId), id => id.startsWith('remote:') ? id : remoteSession(b.localOrigin, id)), receipts, receivedIds: packet.ids.filter(id => {
+                const message = store.getMessage(id);
+                return message?.groupId === b.groupId && message.fromSessionId?.startsWith(`remote:${encodeURIComponent(b.peer.origin)}:`) && !message.toSessionId.startsWith('remote:');
+            }) };
+    }
+    wake() {
+        if (this.stopped)
+            return;
+        for (const b of this.bindings) {
+            const key = `${b.groupId}:${b.peer.serviceId}`;
+            if (!this.live(b) || this.running.has(key) || (this.nextAttempt.get(key) ?? 0) > Date.now())
+                continue;
+            this.running.add(key);
+            void this.sync(b).catch(() => { this.nextAttempt.set(key, Date.now() + 1000); }).finally(() => this.running.delete(key));
+        }
+        // No registration must be visible, rather than an unexplained zero-attempt queue.
+        for (const group of this.options.store.list())
+            for (const m of this.options.store.federationSnapshot().messages.filter(message => message.groupId === group.id)) {
+                if (m.status !== 'pending' || m.fromSessionId?.startsWith('remote:') || !m.toSessionId.startsWith('remote:'))
+                    continue;
+                if (this.bindings.some(b => b.groupId === group.id && this.live(b) && m.toSessionId.startsWith(`remote:${encodeURIComponent(b.peer.origin)}:`)))
+                    continue;
+                const prior = this.options.store.diagnostic(m.id);
+                if (prior?.last_error === 'PEER_REGISTRATION_REQUIRED' && Date.now() - prior.checked_at < 10_000)
+                    continue;
+                this.options.store.recordTransport(m.id, { relay_online: null, peer_reachable: null, attempt_count: prior?.attempt_count ?? 0,
+                    next_retry_at: null, last_error: 'PEER_REGISTRATION_REQUIRED', checked_at: Date.now() });
+            }
+    }
+    async client(b) {
+        const key = b.peer.serviceId;
+        let pending = this.clients.get(key);
+        if (pending) {
+            const client = await pending;
+            if (!client.closed)
+                return client;
+            this.clients.delete(key);
+        }
+        pending = (async () => {
+            try {
+                return await this.options.connect(b.peer);
+            }
+            catch (directError) {
+                for (const entry of this.bindings.filter(e => e.groupId === b.groupId && e.peer.serviceId !== b.peer.serviceId && this.live(e))) {
+                    try {
+                        return await this.options.connect(b.peer, entry.peer);
+                    }
+                    catch { /* Try the next explicitly registered entry. */ }
+                }
+                throw directError;
+            }
+        })();
+        this.clients.set(key, pending);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            if (this.clients.get(key) === pending)
+                this.clients.delete(key);
+            throw error;
+        }
+    }
+    async sync(b) {
+        const store = this.options.store, key = `${b.groupId}:${b.peer.serviceId}`;
+        const messages = store.federationSnapshot().messages.filter(m => m.groupId === b.groupId).filter(m => !m.fromSessionId?.startsWith('remote:') && m.fromSessionId !== null
+            && m.toSessionId.startsWith(`remote:${encodeURIComponent(b.peer.origin)}:`) && !['failed', 'expired'].includes(m.status)
+            && (m.status === 'pending' || !m.snapshot)).sort((a, b) => Number(b.status === 'pending') - Number(a.status === 'pending'));
+        const pending = messages.filter(m => m.status === 'pending');
+        const targetErrors = new Map();
+        try {
+            const client = await this.client(b);
+            for (let offset = 0; offset < Math.max(1, messages.length); offset += 20) {
+                const batch = messages.slice(offset, offset + 20);
+                const requests = batch.filter(m => m.status === 'pending' && (!this.accepted.has(m.id) || m.shellConfirmed && !this.shellConfirmed.has(m.id)));
+                const payloads = requests.length ? requests : [undefined];
+                for (const message of payloads) {
+                    const result = await client.request({ type: 'collaboration-exchange', groupId: b.groupId,
+                        context: mapContext(store.context(b.groupId), id => id.startsWith('remote:') ? id : remoteSession(b.localOrigin, id)),
+                        ids: batch.map(m => m.id), known: batch.map(m => ({ id: m.id, status: m.status, deliveredAt: m.deliveredAt, hasSnapshot: !!m.snapshot, shellConfirmed: m.shellConfirmed })), ...(message ? { message } : {}) });
+                    if (Array.isArray(result.activity))
+                        for (const item of result.activity.slice(0, 500)) {
+                            if (!item || typeof item.sessionId !== 'string' || item.sessionId.startsWith('remote:'))
+                                continue;
+                            const id = remoteSession(b.peer.origin, item.sessionId);
+                            if (store.getGroup(b.groupId)?.sessionIds.includes(id))
+                                store.recordPeerActivity(id, item.last_terminal_output_at, item.activity_observed_at);
+                        }
+                    if (result.context)
+                        store.mergeContext(b.groupId, mapContext(result.context, id => localSession(b.localOrigin, id)));
+                    if (Array.isArray(result.receivedIds))
+                        for (const item of batch) {
+                            if (result.receivedIds.includes(item.id))
+                                this.accepted.add(item.id);
+                            else
+                                this.accepted.delete(item.id);
+                        }
+                    if (this.accepted.size > 2000) {
+                        const retained = new Set(store.federationSnapshot().messages.map(m => m.id));
+                        for (const id of this.accepted)
+                            if (!retained.has(id)) {
+                                this.accepted.delete(id);
+                                this.shellConfirmed.delete(id);
+                            }
+                    }
+                    if (!Array.isArray(result.receipts))
+                        throw new Error('INVALID_PEER_RECEIPTS');
+                    for (const receipt of result.receipts) {
+                        const existing = batch.find(m => m.id === receipt.id);
+                        if (!existing)
+                            continue;
+                        if (receipt.shellConfirmed)
+                            this.shellConfirmed.add(existing.id);
+                        if (typeof receipt.last_error === 'string')
+                            targetErrors.set(existing.id, receipt.last_error);
+                        if (!receipt.status || !Object.hasOwn(STATUS_RANK, receipt.status)
+                            || (receipt.deliveredAt != null && !Number.isFinite(receipt.deliveredAt)))
+                            throw new Error('INVALID_PEER_RECEIPT');
+                        store.mergeFederatedMessages([{ ...existing, status: receipt.status === 'read' ? 'delivered' : receipt.status, deliveredAt: receipt.deliveredAt ?? null,
+                                readAt: null, snapshot: typeof receipt.snapshot === 'string' ? receipt.snapshot.slice(0, 16000) : null,
+                                deliverySource: receipt.deliverySource, readSource: undefined, failureReason: receipt.failureReason }]);
+                    }
+                }
+            }
+            for (const m of pending)
+                store.recordTransport(m.id, { relay_online: true, peer_reachable: true,
+                    attempt_count: (store.diagnostic(m.id)?.attempt_count ?? 0) + 1, next_retry_at: m.status === 'pending' ? Date.now() + 500 : null, last_error: targetErrors.get(m.id) ?? null, checked_at: Date.now(),
+                    ...(this.accepted.has(m.id) ? { remote_received_at: store.diagnostic(m.id)?.remote_received_at ?? Date.now() } : {}) });
+            this.nextAttempt.set(key, Date.now() + (messages.some(m => m.status === 'pending') ? 250 : 1000));
+        }
+        catch (error) {
+            const attempts = Math.max(0, ...pending.map(m => store.diagnostic(m.id)?.attempt_count ?? 0)) + 1;
+            const next = Date.now() + Math.min(10_000, 500 * 2 ** Math.min(attempts - 1, 5));
+            this.nextAttempt.set(key, next);
+            for (const m of pending)
+                store.recordTransport(m.id, { relay_online: true, peer_reachable: false, attempt_count: attempts, remote_received_at: store.diagnostic(m.id)?.remote_received_at,
+                    next_retry_at: next, last_error: error instanceof Error ? error.message.slice(0, 300) : 'PEER_UNREACHABLE', checked_at: Date.now() });
+        }
+    }
+}

package/dist/server/agent/collaborationPrompt.js

@@ -3,7 +3,7 @@ import { sanitizeCollaborationRole } from './collaborationStore.js';
 const SHELL_RULE = '─'.repeat(30);
 /** Body larger than this (in UTF-8 bytes) is replaced by a retrieval pointer
  * instead of being injected into the terminal verbatim. */
-const MAX_INLINE_BODY_BYTES = 8_192;
+const MAX_INLINE_BODY_BYTES = 4_096;
 /**
  * Characters that would corrupt the delivery shell header `「X」群(N 个成员)`
  * and the per-message `来自:X · kind` line: the quote brackets and the middle
@@ -73,6 +73,12 @@ function formatCollaborationMessage(message, source, fannedNames, fence, token)
     const lines = [`来自:${source} · ${message.kind}${fannedNames.length ? ' · 群发' : ''}`];
     if (fannedNames.length)
         lines.push(`同时发给了:${fannedNames.join('、')}`);
+    const rules = message.instructions;
+    if (rules?.text) {
+        lines.push(`群协作约定（版本 ${rules.version}，不改变用户授权）：`);
+        lines.push(Buffer.byteLength(rules.text) <= 1024 ? rules.text
+            : `执行 td collab message get ${token} --text 查看本消息附带的完整群规与正文。`);
+    }
     lines.push('', fence, message.content, fence);
     if (message.task)
         lines.push('', `任务上报:${JSON.stringify(message.task)}`);
@@ -92,7 +98,7 @@ export function formatCollaborationDelivery(input) {
         const token = tokens.get(message.id) ?? message.id;
         const bytes = Buffer.byteLength(message.content);
         const body = bytes > MAX_INLINE_BODY_BYTES
-            ? `大消息已完整保存（${bytes} 字节）。使用 td collab message get ${token} --json 获取正文；不要把这条提示当作消息正文。`
+            ? `大消息已完整保存（${bytes} 字节）。先执行 td collab message get ${token} --text 查看完整正文；不要把这条提示当作消息正文。`
             : message.content;
         const fence = '`'.repeat(Math.max(3, ...Array.from(body.matchAll(/`+/g), (match) => match[0].length + 1)));
         const fannedNames = (message.fanOutIds ?? [])
@@ -122,13 +128,13 @@ export function formatCollaborationDelivery(input) {
     const routingHelp = input.showRoutingHelp === false ? [] : (peers.length ? ['联系其他成员：', ...peers] : []);
     const dynamicNotices = [
         ...(peerIds.some((id) => id.startsWith('remote:'))
-            ? ['跨服务通信使用 td collab；转发客户端须保持运行，网页或 PWA 暂停后需返回前台继续转发。'] : []),
+            ? ['跨服务通信使用 td collab；已登记节点由服务后台直接投递，使用 message get 查看送达回执与重试原因。'] : []),
         ...unreachable.map((id) => {
             const session = sessionsById.get(id);
             return `注意：${session ? sanitizeCollaborationName(session.name) : id} 服务不可达，消息无法送达；仅可排队等待重连。`;
         }),
     ];
-    const captureHelp = '想看伙伴正在做什么、是否卡住：先用 `td collab capture <会话ID> --text` 只读当前屏幕，不打断对方；ID 用 `td collab status --text` 查。仅同组本机 tmux；远端用 send 询问。快照不等于任务完成，按需查看，避免循环轮询。';
+    const captureHelp = '想看伙伴正在做什么、是否卡住：先用 `td collab capture <会话ID> --text` 只读当前屏幕；可加 --lines 200 查看历史，不打断对方；ID 用 `td collab status --text` 查。仅同组本机 tmux；远端用 send 询问。快照不等于任务完成，按需查看，避免循环轮询。';
     const notes = [...routingHelp, ...dynamicNotices, '更多操作：`td collab --help`。',
         ...(input.showRoutingHelp === false ? [] : [captureHelp])];
     // Notes (education + dynamic notices) live inside the shell, after the last

package/dist/server/agent/collaborationRoutes.js

@@ -1,3 +1,5 @@
+import { terminalMessage } from './collaborationStore.js';
+import { assertPeerRegistrationAuthority } from './collaborationPeerTransport.js';
 import { Router } from 'express';
 import { COLLAB_LIMITS, CollaborationError, MIN_ID_PREFIX_LENGTH, ambiguousIdMessage, extrasFromBody } from './collaborationProtocol.js';
 /** Member names arrive agent-authored over a CLI; control characters would
@@ -21,6 +23,27 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
                 code: error instanceof CollaborationError ? error.code : 'COLLABORATION_ERROR', error: error instanceof Error ? error.message : String(error) });
         }
     };
+    router.get('/transport', run((req, res) => {
+        if (!req.app.locals.collaborationNode)
+            throw new Error('COLLABORATION_UNAVAILABLE');
+        res.json({ ok: true, node: req.app.locals.collaborationNode });
+    }));
+    router.post('/transport', run((req, res, sessionId) => {
+        assertPeerRegistrationAuthority(req);
+        const resolved = store.resolveGroupId(String(req.body.groupId ?? ''));
+        if (resolved.status !== 'ok')
+            throw new Error('GROUP_NOT_FOUND_OR_AMBIGUOUS');
+        if (!store.groupsForSession(sessionId).some(group => group.id === resolved.id))
+            throw new Error('GROUP_NOT_FOUND');
+        const node = req.app.locals.collaborationNode;
+        if (!node || !req.app.locals.collaborationTransport || !Array.isArray(req.body.nodes))
+            throw new Error('COLLABORATION_UNAVAILABLE');
+        const local = req.body.nodes.find((item) => item?.serviceId === node.serviceId);
+        if (!local)
+            throw new Error('LOCAL_NODE_MISMATCH');
+        req.app.locals.collaborationTransport.configure(resolved.id, local.origin, req.body.nodes);
+        res.json({ ok: true, group_id: resolved.id, transport: 'server' });
+    }));
     router.post('/route/rebind', run(async (req, res, sessionId) => {
         if (!rebind)
             throw new CollaborationError('ROUTE_REBIND_UNAVAILABLE', 'Route rebinding is not available');
@@ -87,10 +110,10 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
     router.get('/capabilities', run((_req, res) => {
         res.json({ protocol_version: 2, limits: COLLAB_LIMITS,
             routing: { background_recovery: true, explicit_rebind: Boolean(rebind), fixed_tmux_pane: true },
-            statuses: ['pending', 'delivered', 'read', 'failed', 'expired'], queued_status: 'pending',
-            semantics: { delivered: 'written to terminal; no application acknowledgement implied', read: 'explicit consumer acknowledgement',
+            statuses: ['pending', 'delivered', 'failed', 'expired'], queued_status: 'pending',
+            semantics: { delivered: 'written to terminal; no application acknowledgement implied',
                 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',
+                snapshot: 'terminal observation, never proof of reading or task completion',
                 timeout: 'stops waiting, does not cancel delivery',
                 retry: 'same message id may be submitted again after a crash or uncertain transport result; consumers deduplicate by message id' } });
     }));
@@ -141,14 +164,13 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
         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]);
         await awaitDelivery(messages[0].id, (await deliver(original.fromSessionId)) ?? null);
         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 }) });
+        const raw = req.query.raw === 'true';
+        res.json({ ok: true, ...store.receipt(message.id, raw), ...(req.query.receipt_only === 'true' ? {} : { message: terminalMessage(message, raw) }) });
     }));
     router.post('/message/:id/confirm-shell', run(async (req, res, sessionId) => {
         const message = ownMessage(String(req.params.id), sessionId);
@@ -159,10 +181,10 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
         await awaitDelivery(message.id, outcome);
         sent(res, [message.id]);
     }));
-    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) });
+    // Old clients receive an explicit error instead of a fabricated read receipt.
+    router.post('/message/:id/read', run((req, _res, sessionId) => {
+        ownMessage(String(req.params.id), sessionId, true);
+        throw new CollaborationError('READ_RECEIPTS_UNSUPPORTED', 'Terminal delivery cannot observe reading; use message get for the snapshot or reply for an explicit response', 410);
     }));
     router.get('/inbox', run((req, res, sessionId) => {
         const string = (key) => typeof req.query[key] === 'string' ? req.query[key] : undefined;
@@ -185,14 +207,29 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
             if (resolved.status === 'ok')
                 threadFilter = resolved.id;
         }
-        const page = store.page(sessionId, { unread: string('unread') === 'true', since, afterId: string('after_id'), cursor: string('cursor'),
+        let fromFilter = string('from');
+        if (fromFilter) {
+            const allowedIds = [...new Set(store.groupsForSession(sessionId).flatMap(group => group.sessionIds))];
+            if (!allowedIds.includes(fromFilter)) {
+                const matches = fromFilter.length < 4 ? [] : allowedIds.filter(id => id.startsWith(fromFilter)
+                    || (id.startsWith('remote:') && decodeURIComponent(id.slice(id.lastIndexOf(':') + 1)).startsWith(fromFilter)));
+                if (matches.length > 1)
+                    throw new CollaborationError('SESSION_ID_AMBIGUOUS', '发送者短 ID 匹配多个成员，请使用完整 ID');
+                if (matches.length === 1)
+                    fromFilter = matches[0];
+            }
+        }
+        if (string('unread') === 'true')
+            throw new CollaborationError('READ_RECEIPTS_UNSUPPORTED', 'Use a consumer cursor to track retrieved messages');
+        const page = store.page(sessionId, { since, afterId: string('after_id'), cursor: string('cursor'),
             consumer: string('consumer'), limit: string('limit') ? Number(string('limit')) : undefined,
-            from: string('from'), group: groupFilter, thread: threadFilter, kind: string('kind'), responseKind: string('response_kind'), order: string('order') });
+            from: fromFilter, group: groupFilter, thread: threadFilter, kind: string('kind'), responseKind: string('response_kind'), order: string('order') });
+        const messages = page.messages.map(message => terminalMessage(message, string('raw') === 'true'));
         // Fan-out edges carry sibling recipients; the names map lets the CLI text
         // renderer show 同时发给了:… as people instead of bare session ids. The
         // fallback to the raw id stays server-side agnostic (federated/offline).
         const nameIds = [...new Set(page.messages.flatMap((message) => [message.fromSessionId, ...(message.fanOutIds ?? [])].filter((id) => typeof id === 'string' && id.length > 0)))];
-        res.json({ ok: true, ...page, ...(nameIds.length ? { names: resolveNames?.(nameIds) ?? {} } : {}) });
+        res.json({ ok: true, ...page, messages, ...(nameIds.length ? { names: resolveNames?.(nameIds) ?? {} } : {}) });
     }));
     router.post('/cursor/commit', run((req, res, sessionId) => {
         store.commitCursor(sessionId, String(req.body.cursor ?? ''), String(req.body.consumer ?? ''));
@@ -212,6 +249,16 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
     // Member names ride along so role lists read as people, not bare ids; the
     // caller falls back to the session id when a name is unknown (federated or
     // offline members have no local record).
+    const memberOf = (ids, input) => {
+        if (ids.includes(input))
+            return input;
+        if (input.length < 4)
+            return null;
+        const matches = ids.filter(id => id.startsWith(input) || (id.startsWith('remote:') && decodeURIComponent(id.slice(id.lastIndexOf(':') + 1)).startsWith(input)));
+        if (matches.length > 1)
+            throw new CollaborationError('SESSION_ID_AMBIGUOUS', '成员短 ID 匹配多个会话，请使用完整 ID');
+        return matches[0] ?? null;
+    };
     const groupView = (group) => {
         const names = resolveNames?.(group.sessionIds) ?? {};
         return {
@@ -220,6 +267,18 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
             roles: group.roles ?? {},
         };
     };
+    router.get('/rules', run((req, res, sessionId) => {
+        const group = groupOf(String(req.query.group ?? ''), sessionId);
+        res.json({ ok: true, group_id: group.id, instructions: group.instructions ?? null });
+    }));
+    router.post('/rules', run((req, res, sessionId) => {
+        const group = groupOf(String(req.body.group_id ?? ''), sessionId);
+        const expected = req.body.expected_version;
+        if (expected !== undefined && typeof expected !== 'string')
+            throw new Error('INVALID_VERSION');
+        const instructions = store.setRules(group.id, req.body.text, sessionId, expected);
+        res.json({ ok: true, group_id: group.id, instructions });
+    }));
     router.get('/role', run((req, res, sessionId) => {
         const groupId = String(req.query.group ?? '');
         if (groupId) {
@@ -236,13 +295,14 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
     router.post('/role', run((req, res, sessionId) => {
         const group = groupOf(String(req.body.group_id ?? ''), sessionId);
         const role = req.body.role;
-        if (typeof req.body.session_id !== 'string' || !group.sessionIds.includes(req.body.session_id)) {
+        const member = typeof req.body.session_id === 'string' ? memberOf(group.sessionIds, req.body.session_id) : null;
+        if (!member) {
             throw new CollaborationError('NOT_A_MEMBER', 'Role target must be a member of this group', 400);
         }
         if (role === undefined || (role !== null && typeof role !== 'string')) {
             throw new CollaborationError('INVALID_ROLE', 'role must be text or null', 400);
         }
-        const updated = store.setRole({ groupId: group.id, sessionId: req.body.session_id, role: role });
+        const updated = store.setRole({ groupId: group.id, sessionId: member, role: role });
         res.json({ ok: true, group: { ...updated, roles: updated.roles ?? {} } });
     }));
     router.post('/name', run(async (req, res, sessionId) => {