termdock 1.4.307 → 1.4.308

package/dist/server/agent/collaborationProtocol.js

@@ -143,4 +143,4 @@ export function extrasFromBody(body) {
         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 };
+export const STATUS_RANK = { pending: 0, failed: 1, expired: 1, delivered: 2, read: 3, stored: 4 };

package/dist/server/agent/collaborationRoutes.js

@@ -159,8 +159,9 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
                 background_task_records: true, task_purpose_configuration: true, explicit_execution_state: true,
                 task_reply: 'Replies to task-linked user messages are stored in the task; status=stored is not a terminal delivery receipt' },
             routing: { background_recovery: true, explicit_rebind: Boolean(rebind), fixed_tmux_pane: true },
-            statuses: ['pending', 'delivered', 'failed', 'expired'], queued_status: 'pending',
+            statuses: ['pending', 'delivered', 'failed', 'expired', 'stored'], queued_status: 'pending',
             semantics: { delivered: 'written to terminal; no application acknowledgement implied',
+                stored: 'durable reply to a nonterminal integration principal; never a terminal write',
                 ack: 'explicit response_kind=ack', result: 'explicit response_kind=result; inspect task.status and evidence',
                 snapshot: 'terminal observation, never proof of reading or task completion',
                 timeout: 'stops waiting, does not cancel delivery',
@@ -208,6 +209,11 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
     }));
     router.post('/reply', run(async (req, res, sessionId) => {
         const original = ownMessage(String(req.body.messageId ?? ''), sessionId, true);
+        if (original.integrationOrigin) {
+            const reply = store.storeIntegrationReply(original.id, sessionId, req.body.content, extrasFromBody(req.body));
+            res.json({ ok: true, ...store.receipt(reply.id), integration_recorded: true });
+            return;
+        }
         if (!original.fromSessionId) {
             const link = original.metadata?.termdockTask;
             if (link?.taskId && req.app.locals.collaborationTasks) {

package/dist/server/agent/collaborationStore.js

@@ -318,6 +318,8 @@ export class CollaborationStore {
             throw new Error('消息类型无效');
         const extras = validateExtras(input);
         const content = input.content;
+        if (typeof content !== 'string')
+            throw new CollaborationError('INVALID_MESSAGE', 'Message content must be text');
         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())
@@ -326,8 +328,14 @@ export class CollaborationStore {
         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 key = input.idempotencyKey ? JSON.stringify([input.groupId, input.integrationOrigin ? `principal:${input.integrationOrigin.integrationId}` : input.fromSessionId, input.idempotencyKey]) : null;
+        const payload = [recipients.slice().sort(), input.kind, content, input.threadId ?? null, input.replyTo ?? null, extras.responseKind, extras.metadata, extras.task, extras.expiresAt];
+        if (input.integrationOrigin) {
+            if (input.fromSessionId !== null || group.federated || !/^[a-zA-Z0-9._-]{1,80}$/.test(input.integrationOrigin.integrationId))
+                throw new CollaborationError('INVALID_INTEGRATION_MESSAGE', 'Integration messages require an authenticated local nonterminal source');
+            payload.push(input.integrationOrigin);
+        }
+        const hash = crypto.createHash('sha256').update(stableJson(payload)).digest('hex');
         const previous = key ? this.document.idempotency?.[key] : null;
         if (previous && previous.expiresAt > now) {
             if (previous.hash !== hash)
@@ -340,6 +348,7 @@ export class CollaborationStore {
         const taken = this.takenIds();
         const threadId = input.threadId?.trim() || newCollaborationId(taken, this.drawId);
         const messages = recipients.map((toSessionId) => ({
+            ...(input.integrationOrigin ? { integrationOrigin: structuredClone(input.integrationOrigin) } : {}),
             idempotencyKey: input.idempotencyKey, responseKind: extras.responseKind, metadata: extras.metadata, task: extras.task, expiresAt: extras.expiresAt,
             sequence: this.nextSequence(),
             id: newCollaborationId(taken, this.drawId), groupId: group.id, fromSessionId: input.fromSessionId,
@@ -353,10 +362,51 @@ export class CollaborationStore {
         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();
+        this.persist(!!input.integrationOrigin);
         queueMicrotask(() => this.onMessageQueued?.());
         return messages;
     }
+    /** An original recipient can persist a reply to a nonterminal integration.
+     * This is a stored fact, not a fake terminal write or a new task. */
+    storeIntegrationReply(originalId, sessionId, content, input) {
+        const original = this.getMessage(originalId), group = original && this.getGroup(original.groupId);
+        if (!original?.integrationOrigin || original.fromSessionId !== null || original.toSessionId !== sessionId
+            || !group || group.deleted || group.federated || !group.sessionIds.includes(sessionId))
+            throw new CollaborationError('NOT_MESSAGE_RECIPIENT', 'Only the original local recipient can reply to this integration message', 403);
+        const extras = validateExtras(input);
+        if (extras.task || extras.metadata?.termdockTask)
+            throw new CollaborationError('INVALID_INTEGRATION_REPLY', 'Ordinary integration replies cannot carry task envelopes');
+        if (!extras.idempotencyKey)
+            throw new CollaborationError('INVALID_IDEMPOTENCY_KEY', 'Integration replies require an idempotency key');
+        if (typeof content !== 'string' || !content.trim())
+            throw new CollaborationError('INVALID_MESSAGE', 'Reply content must not be empty');
+        if (Buffer.byteLength(content) > COLLAB_LIMITS.message_bytes)
+            throw new CollaborationError('MESSAGE_TOO_LARGE', 'Reply exceeds 1 MiB', 413);
+        if (extras.expiresAt !== undefined && extras.expiresAt !== null)
+            throw new CollaborationError('STORED_REPLY_CANNOT_EXPIRE', 'A persisted reply is not a pending delivery and cannot expire');
+        const principalId = original.integrationOrigin.integrationId;
+        const key = JSON.stringify([original.groupId, `integration-reply:${principalId}:${sessionId}`, extras.idempotencyKey]);
+        const hash = crypto.createHash('sha256').update(stableJson([original.id, content, extras.responseKind, extras.metadata, extras.task])).digest('hex');
+        const previous = this.document.idempotency?.[key];
+        if (previous && previous.expiresAt > Date.now()) {
+            if (previous.hash !== hash)
+                throw new CollaborationError('IDEMPOTENCY_CONFLICT', 'Reply key was already used with different content', 409);
+            const reply = this.getMessage(previous.ids[0]);
+            if (!reply)
+                throw new CollaborationError('IDEMPOTENCY_RECORD_GONE', 'Original reply is no longer retained', 409);
+            return reply;
+        }
+        const now = Date.now();
+        const reply = { ...extras, id: newCollaborationId(this.takenIds(), this.drawId), sequence: this.nextSequence(),
+            groupId: original.groupId, fromSessionId: sessionId, toSessionId: `principal:${principalId}`, toPrincipalId: principalId,
+            kind: 'reply', content, threadId: original.threadId, replyTo: original.id, status: 'stored', createdAt: now, storedAt: now, deliveredAt: null, readAt: null };
+        if (Buffer.byteLength(JSON.stringify(reply)) > COLLAB_LIMITS.wire_bytes)
+            throw new CollaborationError('MESSAGE_WIRE_TOO_LARGE', 'Encoded reply exceeds the wire limit', 413);
+        this.document.messages.push(reply);
+        (this.document.idempotency ??= {})[key] = { hash, ids: [reply.id], expiresAt: now + COLLAB_LIMITS.idempotency_retention_ms };
+        this.persist(true);
+        return reply;
+    }
     listMessages(groupId, limit = 200) {
         return this.document.messages.filter((message) => message.groupId === groupId).slice(-Math.max(1, Math.min(limit, 500)));
     }
@@ -414,7 +464,7 @@ export class CollaborationStore {
         const now = Date.now();
         const changed = [];
         this.document.messages = this.document.messages.map((message) => {
-            if (!ids.has(message.id) || message.status === 'expired' || message.status === 'failed' || message.status === 'read')
+            if (!ids.has(message.id) || message.status === 'stored' || message.status === 'expired' || message.status === 'failed' || message.status === 'read')
                 return message;
             const updated = status === 'read'
                 ? { ...message, status, deliveredAt: message.deliveredAt ?? now, readAt: now, readSource, deliverySource: message.deliverySource ?? (message.deliveredAt === null ? 'consumer_read' : 'legacy_or_unspecified') }
@@ -499,7 +549,7 @@ export class CollaborationStore {
             if (!message || typeof message !== 'object')
                 continue;
             const group = this.getGroup(message.groupId);
-            if (!group?.federated || group.deleted || !group.sessionIds.includes(message.toSessionId)
+            if (!group?.federated || group.deleted || message.status === 'stored' || message.integrationOrigin || message.toPrincipalId || !group.sessionIds.includes(message.toSessionId)
                 || (message.fromSessionId !== null && !group.sessionIds.includes(message.fromSessionId))
                 || typeof message.id !== 'string' || typeof message.threadId !== 'string' || !Number.isFinite(message.createdAt)
                 || typeof message.content !== 'string'
@@ -581,15 +631,18 @@ export class CollaborationStore {
         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 replies = this.document.messages.filter(reply => reply.replyTo === id
+            && (message.toPrincipalId ? reply.integrationOrigin?.integrationId === message.toPrincipalId : reply.fromSessionId === message.toSessionId)
+            && (message.integrationOrigin ? reply.toPrincipalId === message.integrationOrigin.integrationId : reply.toSessionId === message.fromSessionId));
         const diagnostic = this.diagnostic(id);
         const facts = terminalMessage(message, raw);
-        return { message_id: id, thread_id: message.threadId, status: facts.status, queued_at: message.createdAt,
+        return { message_id: id, thread_id: message.threadId, status: facts.status, queued_at: message.status === 'stored' ? null : message.createdAt, stored_at: message.storedAt ?? null,
+            from_principal_id: message.integrationOrigin?.integrationId ?? null, to_principal_id: message.toPrincipalId ?? null,
             delivered_at: facts.deliveredAt, expires_at: message.expiresAt ?? null,
-            failure_reason: message.failureReason ?? null, delivery_semantics: facts.deliverySource ?? (facts.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'),
+            failure_reason: message.failureReason ?? null, delivery_semantics: message.status === 'stored' ? 'durable_storage' : facts.deliverySource ?? (facts.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'),
             snapshot: message.snapshot ? (raw ? message.snapshot : plainCollaborationSnapshot(message.snapshot)) : null,
             delivery: { status: facts.status,
-                stage: facts.deliveredAt !== null ? 'terminal_written' : diagnostic?.remote_received_at ? 'remote_received' : 'queued',
+                stage: message.status === 'stored' ? 'stored' : facts.deliveredAt !== null ? 'terminal_written' : diagnostic?.remote_received_at ? 'remote_received' : 'queued',
                 remote_received_at: diagnostic?.remote_received_at ?? null, delivered_at: facts.deliveredAt, error: message.failureReason ?? diagnostic?.last_error ?? null },
             reply: { status: replies.length ? 'received' : 'pending', ack_at: replies.find(reply => reply.responseKind === 'ack')?.createdAt ?? null, reply_ids: replies.map(reply => reply.id) },
             idempotency_key: message.idempotencyKey ?? null,
@@ -725,7 +778,7 @@ export class CollaborationStore {
         this.persist();
         return { message_id: fragment.message_id, received, total: state.total, complete: received === state.total };
     }
-    persist() {
+    persist(durable = false) {
         const now = Date.now();
         for (const [key, record] of Object.entries(this.document.idempotency ?? {}))
             if (record.expiresAt <= now)
@@ -744,9 +797,26 @@ export class CollaborationStore {
         try {
             fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
             const serialized = JSON.stringify(this.document);
-            fs.writeFileSync(temporaryPath, serialized, { mode: 0o600 });
+            const descriptor = fs.openSync(temporaryPath, 'w', 0o600);
+            try {
+                fs.writeFileSync(descriptor, serialized);
+                if (durable)
+                    fs.fsyncSync(descriptor);
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
             fs.renameSync(temporaryPath, this.filePath);
             this.persistedDocument = serialized;
+            if (durable) {
+                const directory = fs.openSync(path.dirname(this.filePath), 'r');
+                try {
+                    fs.fsyncSync(directory);
+                }
+                finally {
+                    fs.closeSync(directory);
+                }
+            }
             for (const listener of this.changeListeners) {
                 try {
                     listener();

package/dist/server/agent/collaborationTaskService.js

@@ -268,6 +268,8 @@ export class CollaborationTaskService {
     }
     receipt(messageId) {
         const receipt = this.messages.receipt(messageId);
+        if (receipt.status === 'stored')
+            throw new CollaborationError('INVALID_TASK_DELIVERY', 'A nonterminal reply cannot be a task delivery');
         return { messageId, status: receipt.status, deliveredAt: receipt.delivered_at, error: receipt.delivery.error };
     }
     start() { this.timer = setInterval(() => void this.flush(), 1500); this.timer.unref(); void this.flush(); }

package/dist/server/agent/integrationCli.js

@@ -4,7 +4,7 @@ import http from 'node:http';
 import { INTEGRATION_PROTOCOL } from './integrationStore.js';
 import { integrationSocketPath } from './integrationServer.js';
 import { CollaborationError } from './collaborationProtocol.js';
-import { executeCollaborationCommand, duration } from './collaborationCli.js';
+import { COLLAB_HELP, executeCollaborationCommand, duration } from './collaborationCli.js';
 import { getTermdockVersion } from '../utils/version.js';
 export const INTEGRATION_HELP = `td integration — local scoped integration administration
   groups | list
@@ -14,6 +14,9 @@ export const INTEGRATION_HELP = `td integration — local scoped integration adm
   revoke <principal-id>
 Credentials are saved as a private file and never printed. Workers set
 TERMDOCK_INTEGRATION_CREDENTIAL_FILE, then use td collab --principal <id> …
+Ordinary messages: permissions message.send, message.read, events.read;
+td collab --principal <id> --help lists send/reply/history and event examples.
+No task or user acceptance is required for a message-driven integration.
 Only the local administrator can provision/revoke grants. See docs/integrations.md.`;
 export function readIntegrationCredential(file, principalId) {
     const info = fs.lstatSync(file);
@@ -55,7 +58,7 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
     let reserved;
     try {
         const action = argv[0] ?? 'help', options = {};
-        if (action === 'help' || action === '--help') {
+        if (action === 'help' || argv.includes('--help')) {
             write(INTEGRATION_HELP);
             return 0;
         }
@@ -131,6 +134,10 @@ export async function revokeIntegration(id, port, adminToken, write) {
 }
 export async function runIntegrationCollab(command, port, io) {
     try {
+        if (command.action === 'help') {
+            io.write(COLLAB_HELP);
+            return 0;
+        }
         const principalId = String(command.options.principal), file = process.env.TERMDOCK_INTEGRATION_CREDENTIAL_FILE;
         if (!file)
             throw new CollaborationError('INTEGRATION_CREDENTIAL_REQUIRED', 'Set TERMDOCK_INTEGRATION_CREDENTIAL_FILE to a private credential file', 401);
@@ -160,8 +167,12 @@ export async function runIntegrationCollab(command, port, io) {
             io.write(JSON.stringify(parsed(await request(socketPath, command.operation === 'get' ? 'GET' : 'POST', route, body, headers(credential)))));
             return 0;
         }
-        if (!['task', 'message', 'help'].includes(command.action) || command.action === 'message' && command.operation !== 'get')
-            throw new CollaborationError('INTEGRATION_OPERATION_DENIED', 'Command is not exposed to integration identities', 403);
+        const messageCapability = command.action === 'send' ? 'integration_message_send' : command.action === 'reply' ? 'integration_message_reply'
+            : command.action === 'message' && command.operation === 'list' ? 'integration_message_history' : null;
+        if (messageCapability && capability[messageCapability] !== true)
+            throw new CollaborationError('INTEGRATION_MESSAGING_UNSUPPORTED', 'CLI and running service must support integration messaging (minimum 1.4.308); upgrade both and read capabilities', 409);
+        if (!['task', 'message', 'send', 'reply'].includes(command.action) || command.action === 'message' && !['get', 'list'].includes(command.operation))
+            throw new CollaborationError('INTEGRATION_OPERATION_DENIED', 'Command is not exposed to integration identities; see td collab --principal <id> --help', 403);
         return executeCollaborationCommand(command, {}, { ...io, request: async (method, endpoint, body, timeout) => {
                 const origin = { source: command.options.source, externalActor: command.options['external-actor'] ? JSON.parse(String(command.options['external-actor'])) : undefined,
                     externalMessageId: command.options['external-message-id'], metadata: command.options.metadata ? JSON.parse(String(command.options.metadata)) : undefined };

package/dist/server/agent/integrationServer.js

@@ -4,12 +4,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { timingSafeEqual } from 'node:crypto';
-import { CollaborationError } from './collaborationProtocol.js';
+import { CollaborationError, resolveIdPrefix } from './collaborationProtocol.js';
 import { terminalMessage } from './collaborationStore.js';
 import { IntegrationStore, INTEGRATION_PROTOCOL, INTEGRATION_OPERATIONS, integrationError } from './integrationStore.js';
 import { IntegrationSessions, publicIntegrationSession } from './integrationSessions.js';
 import { getTermdockVersion } from '../utils/version.js';
 export function integrationSocketPath(port) { return path.join(homedir(), '.termdock', `integration-${port}.sock`); }
+function scopedId(input, ids, type) {
+    if (typeof input !== 'string')
+        integrationError(`INVALID_${type}_ID`, 'A message or member id is required');
+    const result = resolveIdPrefix([...new Set(ids)], input);
+    if (result.status !== 'ok')
+        integrationError(`${type}_${result.status === 'ambiguous' ? 'ID_AMBIGUOUS' : 'NOT_FOUND'}`, `No unique ${type.toLowerCase()} in this integration group`, result.status === 'ambiguous' ? 409 : 404);
+    return result.id;
+}
 /** A local authenticated API and push stream. It is never mounted on the
  * public HTTP application and does not reuse an integration's admin token. */
 export class IntegrationRuntime {
@@ -35,7 +43,7 @@ export class IntegrationRuntime {
         } };
         this.stops.push(options.messages.subscribe(changed), options.taskStore.subscribe(changed), this.sessions.subscribe(changed));
         const app = express();
-        app.use(express.json({ limit: '1mb' }));
+        app.use(express.json({ limit: '2mb' }));
         app.use((req, res, next) => {
             if (req.headers['x-termdock-integration-protocol'] !== String(INTEGRATION_PROTOCOL)) {
                 res.status(409).json({ ...this.error(new CollaborationError('INCOMPATIBLE_INTEGRATION_PROTOCOL', 'Unsupported integration protocol', 409)), protocol: INTEGRATION_PROTOCOL });
@@ -103,11 +111,62 @@ export class IntegrationRuntime {
             const event = options.taskStore.integrationRequestEvent(p.id, input.idempotencyKey, task.id);
             return { task, event_id: event?.id ?? null, attempt_id: event?.attemptId ?? null, delivery_id: event?.deliveryId ?? null };
         }));
+        app.post('/send', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'message.send', req.body?.group_id);
+            const group = this.group(p.groupId), raw = req.body ?? {};
+            if (raw.kind && raw.kind !== 'message')
+                integrationError('INTEGRATION_OPERATION_DENIED', 'Integration send uses ordinary messages only', 403);
+            const targets = Array.isArray(raw.toSessionIds) ? raw.toSessionIds : [raw.targetSessionId];
+            if (!targets.length || targets.some((id) => typeof id !== 'string'))
+                integrationError('INVALID_MESSAGE_TARGET', 'Specify a local group member');
+            const recipients = targets.map((id) => scopedId(id, group.sessionIds, 'SESSION'));
+            let thread;
+            if (raw.thread_id)
+                thread = scopedId(raw.thread_id, options.messages.snapshotMessages().filter(m => m.groupId === p.groupId).map(m => m.threadId), 'THREAD');
+            const messages = options.messages.send({ ...this.messageExtras(raw), groupId: p.groupId, fromSessionId: null,
+                integrationOrigin: this.origin(p, raw.origin), toSessionIds: recipients, kind: 'message', content: raw.message, threadId: thread });
+            this.sync();
+            return { ok: true, message_ids: messages.map(m => m.id), receipts: messages.map(m => options.messages.receipt(m.id)), ...options.messages.receipt(messages[0].id) };
+        }));
+        app.post('/reply', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'message.send', req.body?.group_id);
+            const raw = req.body ?? {}, original = this.message(p, raw.messageId);
+            const target = original.toPrincipalId === p.id ? original.fromSessionId
+                : original.integrationOrigin?.integrationId === p.id ? original.toSessionId : null;
+            if (!target || !this.group(p.groupId).sessionIds.includes(target))
+                integrationError('NO_REPLY_TARGET', 'Reply requires your own message and its original live group member', 409);
+            const messages = options.messages.send({ ...this.messageExtras(raw), groupId: p.groupId, fromSessionId: null,
+                integrationOrigin: this.origin(p, raw.origin), toSessionIds: [target], kind: 'reply', content: raw.content, threadId: original.threadId, replyTo: original.id });
+            this.sync();
+            return { ok: true, ...options.messages.receipt(messages[0].id) };
+        }));
+        app.get('/message', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'message.read', req.query.group);
+            const messages = options.messages.snapshotMessages().filter(m => m.groupId === p.groupId).sort((a, b) => a.sequence - b.sequence);
+            const after = req.query['after-id'] ? this.message(p, String(req.query['after-id'])) : null;
+            const limit = req.query.limit === undefined ? 50 : Number(req.query.limit);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+                integrationError('INVALID_MESSAGE_LIMIT', 'limit must be 1..200');
+            const thread = req.query.thread ? scopedId(String(req.query.thread), messages.map(m => m.threadId), 'THREAD') : null;
+            const filtered = messages.filter(m => (!after || m.sequence > after.sequence) && (!thread || m.threadId === thread));
+            const page = [];
+            let bytes = 0;
+            for (const message of filtered.slice(0, limit)) {
+                const size = Buffer.byteLength(JSON.stringify(message));
+                if (page.length && bytes + size > 2 * 1024 * 1024)
+                    break;
+                page.push(message);
+                bytes += size;
+            }
+            return { messages: page.map(m => terminalMessage(m)), next_after_id: page.at(-1)?.id ?? after?.id ?? null, has_more: filtered.length > page.length, retention: 'retained_messages_only' };
+        }));
         app.get('/message/:id', run(req => {
-            const p = principal(req), message = options.messages.getMessage(req.params.id);
-            if (!message)
-                integrationError('MESSAGE_NOT_FOUND', 'Message does not exist', 404);
-            this.authorize(p, 'task.read', message.groupId);
+            const p = principal(req);
+            this.authorize(p, p.permissions.includes('message.read') ? 'message.read' : 'task.read');
+            const message = this.message(p, req.params.id);
             const receipt = options.messages.receipt(message.id);
             const { snapshot: _, ...diagnostic } = receipt;
             return { ok: true, ...diagnostic, ...(req.query.receipt_only === 'true' ? {} : { message: terminalMessage(message) }) };
@@ -149,6 +208,7 @@ export class IntegrationRuntime {
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',
             background_task_records: true, task_purpose_configuration: true, explicit_execution_state: true,
+            integration_message_send: true, integration_message_reply: true, integration_message_history: true,
             permissions: INTEGRATION_OPERATIONS };
     }
     error(error) {
@@ -170,6 +230,18 @@ export class IntegrationRuntime {
             integrationError('TASK_NOT_FOUND', 'Task does not exist within this integration grant', 404);
         this.authorize(p, operation, task.groupId);
     }
+    message(p, id) {
+        const scoped = this.options.messages.snapshotMessages().filter(m => m.groupId === p.groupId);
+        const resolved = scopedId(id, scoped.map(m => m.id), 'MESSAGE');
+        return this.options.messages.getMessage(resolved);
+    }
+    messageExtras(raw) {
+        if (typeof raw.idempotency_key !== 'string' || !raw.idempotency_key.trim())
+            integrationError('IDEMPOTENCY_KEY_REQUIRED', 'Integration message mutations require an explicit idempotency key');
+        if (raw.task || raw.task_envelope || raw.metadata?.termdockTask)
+            integrationError('INTEGRATION_OPERATION_DENIED', 'Ordinary messages cannot forge task envelopes', 403);
+        return { idempotencyKey: raw.idempotency_key, responseKind: raw.response_kind, metadata: raw.metadata, expiresAt: raw.expires_at };
+    }
     origin(p, input) {
         const value = input && typeof input === 'object' ? input : {};
         if (Buffer.byteLength(JSON.stringify(value)) > 16384)
@@ -215,11 +287,16 @@ export class IntegrationRuntime {
                 if (groups.has(message.groupId)) {
                     const link = message.metadata?.termdockTask;
                     const context = { group_id: message.groupId, task_id: link?.taskId ?? null, attempt_id: link?.attemptId ?? null,
-                        reply_to_event_id: link?.replyToEventId ?? null, message_id: message.id, source: message.fromSessionId ? 'member' : 'system' };
+                        reply_to_event_id: link?.replyToEventId ?? null, message_id: message.id, source: message.integrationOrigin ? 'integration' : message.fromSessionId ? 'member' : 'system',
+                        actor: message.integrationOrigin ? { integration_id: message.integrationOrigin.integrationId } : message.fromSessionId ? { session_id: message.fromSessionId } : null,
+                        external_actor: message.integrationOrigin?.externalActor ?? null };
                     updates.push({ sourceKey: `message:${message.id}`, sourceVersion: '1', event: { ...context,
                             kind: message.kind === 'reply' ? 'message.reply' : 'message.queued', created_at: message.createdAt,
                             payload: { message_id: message.id, thread_id: message.threadId, reply_to: message.replyTo ?? null,
-                                from_session_id: message.fromSessionId, to_session_id: message.toSessionId, content: message.content, metadata: message.metadata ?? null } } });
+                                from_session_id: message.fromSessionId, to_session_id: message.toPrincipalId ? null : message.toSessionId,
+                                to_principal_id: message.toPrincipalId ?? null, integration_origin: message.integrationOrigin ?? null,
+                                response_kind: message.responseKind ?? null, stored_at: message.storedAt ?? null,
+                                content: message.content, metadata: message.metadata ?? null } } });
                     const { snapshot: _, ...receipt } = this.options.messages.receipt(message.id);
                     updates.push({ sourceKey: `message-status:${message.id}`, sourceVersion: JSON.stringify(receipt), event: {
                             ...context, kind: 'message.delivery', created_at: message.deliveredAt ?? message.createdAt, payload: { receipt }

package/dist/server/agent/integrationStore.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { CollaborationError } from './collaborationProtocol.js';
 export const INTEGRATION_PROTOCOL = 1;
-export const INTEGRATION_OPERATIONS = ['task.read', 'task.create', 'task.configure', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore'];
+export const INTEGRATION_OPERATIONS = ['message.send', 'message.read', 'task.read', 'task.create', 'task.configure', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore'];
 export function integrationError(code, message, status = 400) { throw new CollaborationError(code, message, status); }
 export function atomicJson(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });

package/dist/server/cli.js

@@ -3489,7 +3489,7 @@ async function main() {
     }
     if (options.integration) {
         const argv = options.integration;
-        if (!argv.length || ['help', '--help'].includes(argv[0])) {
+        if (!argv.length || argv.includes('--help') || argv[0] === 'help') {
             console.log(INTEGRATION_HELP);
             return;
         }

package/docs/integrations.md

@@ -8,7 +8,8 @@
 **实际运行服务至少 1.4.304**。管理员恢复诊断要求 **CLI / 实际服务均至少 1.4.305**；
 直接 exec 为 pane PID 的原生 argv 核验及可选 Linux 持锁身份要求 **实际服务至少 1.4.306**；
 后台执行记录与用途迁移要求 **CLI / 实际服务均至少 1.4.307**；
-建议 CLI 与服务同步安装 1.4.307（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
+普通消息身份发送、持久回复及消息历史要求 **CLI / 实际服务均至少 1.4.308**；
+建议 CLI 与服务同步安装 1.4.308（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
 现有 `--session`、消息投递、任务报告与自动协作入口继续兼容；旧的
 `task create --integration` 仍表示代码集成子任务，新身份使用 `--principal`。
 
@@ -17,6 +18,90 @@ TD 提供受限身份、持久事件推送、关联咨询回复，以及会话
 `complete` 是执行成员的明确交付，`accepted` 是用户明确验收；投递成功、终端快照、
 事件 ACK 都不表示已读、任务完成或业务校验通过。
 
+## 普通消息接入（1.4.308，推荐用于机器人与报表）
+
+触发 Agent、追问和回帖可使用普通消息：**无需创建 task，不产生任务看板或逐期用户验收**。
+消息负责可靠投递与关联回复；业务周期、结果版本、机器校验、外部发布状态由接入方记录。
+只有需要 TD 任务分派、交付物、评审或人工验收时才使用后文 task；1.4.307 的 automation
+purpose 是可选任务能力，不是机器人接入的前置要求。已有 task/attempt/session 和外部根帖
+保持原记录，不自动迁移、重建、重投或重跑。
+
+管理员为现有身份补权限后用 `td integration update --file /private/policy.json`：
+
+```json
+"permissions": ["message.send", "message.read", "events.read", "session.create", "session.read", "session.restore"]
+```
+
+更新保留同一身份、组和凭据；保留实际需要的既有 task 权限以及原 launchProfiles。
+`message.send` 授权 send/reply，`message.read` 授权组内 message get/list；它们不授予任务操作
+或用户验收。events.read 可订阅授权组内事件。只允许该身份授权的一个本机组，拒绝跨服务目标、
+组外成员、未授权操作与 task envelope。组中其他 principal 的消息可以按组授权读取，但不能
+借其原消息 reply 或冒充其身份；只能向本组成员 send 新消息。
+
+先回读实际运行服务，再检查三个能力均为 true：
+
+```sh
+export TERMDOCK_INTEGRATION_CREDENTIAL_FILE=/private/bridge-credential.json
+td collab --principal report-bridge capabilities
+# cli_version / server_version >= 1.4.308, integration_protocol = 1
+# integration_message_send / integration_message_reply / integration_message_history = true
+
+td collab --principal report-bridge send <TD成员ID> --file /private/prompt.txt --idempotency-key run:2026-10-10
+# 保存输出 message_id、thread_id；status=pending 表示已持久入队
+# 可附 --source feishu --external-actor '{"id":"external-user"}' --external-message-id <external-id>
+
+td collab --principal report-bridge events subscribe --consumer bridge-inbox --jsonl
+# 按 event_id 去重；先将事件落盘，再 ACK 已连续持久接收的位置
+td collab --principal report-bridge events ack <cursor> --consumer bridge-inbox
+```
+
+CLI 在发送前检查运行服务 capability；旧服务返回 `INTEGRATION_MESSAGING_UNSUPPORTED`，
+不会降级成用户或终端成员发送。凭据只通过私有文件注入；`--principal <id> --help` 不需要
+凭据或运行服务。建议 CLI 与实际服务保持同一版本，版本号本身不能替代能力检测。
+
+接收 Agent 在**原终端**使用明确回复（投递提示每次都附原消息 ID 与此用法）：
+
+```sh
+td collab --session <自己的TD成员ID> reply <原消息ID> "收到" --response-kind ack --idempotency-key run:ack
+td collab --session <自己的TD成员ID> reply <原消息ID> --file /private/result.txt --response-kind result --idempotency-key run:result
+# 进展也可 --response-kind progress；不推断 Agent 内部进度或整个会话忙闲
+```
+
+回复保存到同一消息历史，`status=stored`、`stored_at`、`delivery.stage=stored`、
+`delivery_semantics=durable_storage`、`delivered_at=null`、`attempt_count=0`；
+不进终端投递队列，不伪造“写入终端”。原 message get/list 记录的 toSessionId 使用内部保留
+地址 principal:<id> 以兼容历史结构，实际接收方由 toPrincipalId 标识；不要把这个地址当作成员 ID。Agent CLI 立即返回这个保存事实，不等待不存在的接收终端。
+原发送的 receipt.result_ids/reply_ids/ack_at 来自明确的关联回复，原消息投递状态独立保留。
+原生会话、结果正文及外部校验仍由实际 Agent/业务方负责；result 不表示用户验收或外部发布成功。
+
+`message.reply` 的 payload 包含 `message_id`、`thread_id`、`reply_to`（原消息 ID）、
+`from_session_id`、`to_session_id`（后台回复为 null）、`to_principal_id`、
+`integration_origin`、`response_kind`、`stored_at`、`content`、`metadata`。
+普通消息没有 task_id/attempt_id；不要套用 task 的 to-event/respond。外部话题和结果版本
+用 message_id/thread_id 与 reply_to 关联。外部追问可以回复自己的原发送或收到的 Agent 回复：
+
+```sh
+td collab --principal report-bridge reply <原发送ID或Agent回复ID> "解释一下" --idempotency-key followup:external-id
+td collab --principal report-bridge message get <消息ID> --text
+td collab --principal report-bridge message list --thread <话题ID> --limit 50
+td collab --principal report-bridge message list --thread <话题ID> --after-id <上一页next_after_id> --limit 50
+```
+
+追问固定回原成员及原 thread，原成员不在授权组时返回 NO_REPLY_TARGET，不悄悄新建会话。
+需要恢复时显式 session restore，仍保留原 native UUID、argv/cwd/包装器与 startupInput 条件。
+命令变更必须给稳定 idempotency-key；同身份/组/key 且相同正文与参数返回同一消息 ID，
+不同 payload 返回 IDEMPOTENCY_CONFLICT。原 Agent 回复另按 principal/成员/key 隔离。
+
+消息/回复在成功返回前完成文件 fsync、原子替换和目录 fsync，事件从这些源记录持久生成。
+订阅自动断线重连，从同 consumer 已 ACK 的连续位置重放；收到事件不自动 ACK，也不表示业务
+已经处理。业务 inbox/outbox 按自身持久处理状态重试。事件保留缺口返回 EVENT_RETENTION_GAP
+并停止；需结合仍保留的消息与业务数据库对账后建立新 consumer，不能声称任意历史均可重放。
+message list 按本组 sequence 升序分页，返回 next_after_id/has_more，页还受 2 MiB 字节预算限制；
+只覆盖仍保留的消息（常规历史最多保留 2000 条，pending 和未过期幂等记录另外保护，幂等保留 7 天）。
+after-id 不在本组保留记录中返回 MESSAGE_NOT_FOUND；前缀不唯一返回 MESSAGE_ID_AMBIGUOUS。
+鉴权撤销与权限更新沿用下文错误和重连契约。普通消息 delivered 仍只表示写入终端，不能从快照
+缺少正文推断未消费，更不能因此自动重投已 delivered 消息。
+
 ## 管理员配置身份
 
 接口只监听本机 Unix socket `~/.termdock/integration-<port>.sock`（0600），
@@ -49,7 +134,7 @@ td integration list
 }
 ```
 
-`launchProfiles` 可为空（只操作已有任务）。创建会话时只能选择预配 profile 和
+`launchProfiles` 可为空（只操作已有消息或任务）。创建会话时只能选择预配 profile 和
 目录，不能传任意命令/参数。`cwd` 必须已存在，真实路径须位于 `cwdRoots` 内；
 符号链接不能逃出目录边界。参数按独立 token 引号转义，控制字符禁止。
 `{cwd}`、`{sessionId}`、`{launchArgs}` 必须是独立参数；恢复模板必须各包含一次
@@ -302,8 +387,8 @@ task 事件 `event_id` 与任务内事件 ID 一致，`respond.reply_to_event_id
 | `task.close/reopen/coordinate/pause/resume/retry/child-update/automation-blocked/review-passed/review-blocked` | `{event}`：保留服务事件的 source 与原文 |
 | `task.result` | `{artifact}`：结果 id、attemptId、actor、content、summary、evidence、createdAt |
 | `task.delivery` | `{delivery}`：任务投递 id、attemptId、messageId、status、deliveredAt、error |
-| `message.queued/message.reply` | `{message_id,thread_id,reply_to,from_session_id,to_session_id,content,metadata}` |
-| `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
+| `message.queued/message.reply` | `{message_id,thread_id,reply_to,from_session_id,to_session_id,to_principal_id,integration_origin,response_kind,stored_at,content,metadata}` |
+| `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入/后台回复保存阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
 | `session.starting/binding_pending/ready/restoring/failed` | `{session}`：下节公开会话记录，失败包含 error_code |
 
 TD 在源记录提交后触发 journal 及订阅，journal 中的同一事件 ID 在重连重放时保持不变。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.307",
+  "version": "1.4.308",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.307",
+  "version": "1.4.308",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-SmxpQ63ErP59HLeERjJ0euDs74G6un227eMPe9/sAEI=",
-  "clientBundleHash": "sha256-dfDbp6qzSoUEczQc0mFdVx2jNb+7Oabm+ZvcTpBThnw=",
+  "serverBundleHash": "sha256-KCZQLf7sIa26nzVvLZBZhHNcitDKANSYJdK523lF3qg=",
+  "clientBundleHash": "sha256-Yh0fz4oTrM6A2pNHLYx+Y67/R7Wfa84cFlIPMrwAsfE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }

package/dist/client/assets/CollaborationTaskContent-DQpH2HIj.js

@@ -1,2 +0,0 @@
-import{bv as r}from"./app-CXvK8WZg.js";import{b as m}from"./dnd-BCFAPC0L.js";import{b as n}from"./RightSidebar-CnnU7Ffp.js";import"./react-XDCjal2T.js";import"./terminal-C7X98Amf.js";import"./App-cagV-flM.js";import"./gestureArbiter-Cy5v_ZUL.js";import"./triangle-alert-BFCgLlxS.js";import"./referenceLongPress-xNXQRqYn.js";import"./DiffReview-Cn_PmN-9.js";import"./sparkles-BBYDWqCu.js";import"./DiffViewer-DRnuph7U.js";import"./ChangeWalkthroughPanel-DOj40Srm.js";function v({content:o}){const e=m.useMemo(()=>n(o.split(`
-`),null,null),[o]);return r.jsx("div",{className:"min-w-0 space-y-3 break-words text-sm leading-6 text-foreground [&_h1]:text-lg [&_h2]:text-base [&_h3]:text-sm [&_pre]:max-w-full [&_table]:text-xs",children:e.map((t,i)=>r.jsx("div",{className:"min-w-0",children:typeof t.content=="function"?t.content(null):t.content},i))})}export{v as default};