termdock 1.4.306 → 1.4.308

package/dist/server/agent/collaborationCli.js

@@ -5,10 +5,12 @@ import { randomUUID } from 'node:crypto';
 import { COLLAB_LIMITS, CollaborationError, canonicalShortId } from './collaborationProtocol.js';
 export const COLLAB_HELP = `td collab — durable messages; no agent-specific hooks required
 ── 任务闭环 ──
-  task list [--group <组id>] | task get <任务id>
+  task list [--group <组id>] [--purpose interactive|automation|all] | task get <任务id>
+  task configure <任务id> --purpose interactive|automation --revision <当前版本>
   task create --group <组id> --title <标题> --content <正文> [--assignee <成员id>]
     [--constraints <约束>] [--acceptance <验收标准>] [--coordinator <成员id>]
     [--parent <任务id>] [--depends-on <任务id,任务id>] [--integration]
+    [--purpose interactive|automation]（默认 interactive；automation 是独立后台记录，无需用户验收）
   task assign <任务id> --assignee <成员id> --revision <当前版本>
   task report <任务id> --attempt <尝试id> --status ack|working|blocked|complete|failed --content <正文>
   task ask <任务id> --attempt <尝试id> --content <问题> [--options '["选项一","选项二"]']
@@ -50,12 +52,27 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
 ── 后台集成（独立凭据；本机 Unix socket） ──
   td integration help（管理授权与启动配置）
   td collab --principal <id> capabilities
+  send <成员id> "执行正文" --idempotency-key <key>（权限 message.send；普通消息，不创建看板任务）
+  reply <原消息id> "追问正文" --idempotency-key <key>（回到原成员、原话题）
+  message get <id> | message list [--thread <id>] [--after-id <id>] [--limit 1..200]
+    （权限 message.read；list 返回保留记录，next_after_id/has_more 用于分页）
+  以上命令均需前缀 td collab --principal <id>；send/reply 支持 --file/--stdin。
+  来源可附 --source <name> --external-actor '<JSON object>' --external-message-id <id>。
+  Agent 在终端收到消息后：td collab --session <自己的TD成员id> reply <原消息id> "答复" --response-kind result --idempotency-key <key>
+    ack=明确回复收到；progress=原文进展；result=原文结果。后台回复 status=stored，仅表示持久保存。
+    回复通过 message.reply 事件主动推送；payload.reply_to 关联原消息，response_kind 标记回复类型。
   events subscribe --consumer <name> --jsonl（主动推送，默认持续运行）
   events ack <cursor> --consumer <name>（仅声明已持久接收）
+    events 需权限 events.read；按 event_id 去重，落盘后 ACK 连续前缀；订阅读到不等于 ACK。
+    断线自动重连，同 consumer 从已 ACK 处重放；保留缺口 EVENT_RETENTION_GAP 停止，需对账后换 consumer。
+    消息历史只覆盖仍保留记录；不存在的 after-id 返回 MESSAGE_NOT_FOUND，不能据此声称历史完整。
   session create --group <id> --launch-profile <id> --cwd <absolute-path> --idempotency-key <key>
   session get <id> | session restore <id> --idempotency-key <key>
   task respond <task-id> --attempt <attempt-id> --to-event <comment-event-id> --content <答复>
   凭据通过 TERMDOCK_INTEGRATION_CREDENTIAL_FILE 注入，不通过命令行传 token。
+  消息接入最低 CLI/实际服务均为 1.4.308；capabilities 回读双方版本与 integration_message_send/reply/history。
+  principal 只操作获授权本机组；不能冒充用户/成员或用户验收。普通消息不需要 task/accepted。
+  任务命令适用于需要任务闭环的流程；message.send/read 与 task 权限独立。
   已验收任务可追加纯咨询；respond 保留当前结果与验收，revise 是修改要求。
 ── 常用 ──
   status (who is in my groups, their names, roles, observed activity.
@@ -143,11 +160,11 @@ Message limit: ${COLLAB_LIMITS.message_bytes} UTF-8 bytes; metadata: ${COLLAB_LI
 Idempotency retention: 7 days. Terminal delivery, ACK and result never imply each other.
 Delivery semantics: delivered = written to the terminal — never proof of
 reading or task completion; a timeout stops waiting, it does not cancel delivery.
-The service cannot see whether the recipient's agent consumed a message. To
-judge for yourself, use --wait-until delivered and read the recipient-screen
-snapshot in the receipt: if your message is not visible on that screen, send it
-again (a fresh send is a new message and will be written again); if it is
-visible but unanswered, the recipient may simply not have started yet.`;
+The service cannot see whether the recipient's agent consumed a message.
+Use explicit replies as evidence. A screen snapshot is only an observation;
+do not automatically resend a delivered message because it is absent from a snapshot.
+stored = durable reply to a nonterminal principal; terminal delivery waits do not apply.
+Idempotent retries reuse the same key and payload; a fresh key creates a new message.`;
 /** One roster row: prefer the member's human name, keep the full session id
  * reachable for role set/unset targeting, mark unset members explicitly. */
 function roleLine(member, role) {
@@ -155,7 +172,7 @@ function roleLine(member, role) {
     return role ? `- ${label}：${role}` : `- ${label}（未设置）`;
 }
 const BOOLEAN_OPTIONS = new Set(['json', 'jsonl', 'text', 'follow', 'stdin', 'receipt-only', 'confirm', 'raw', 'help', 'no-rules', 'managed', 'shared-directory', 'integration']);
-const VALUE_OPTIONS = new Set(['principal', 'source', 'external-actor', 'external-message-id', 'launch-profile', 'to-event', 'decision', 'work-type', 'summary', 'verdict', 'reviewers', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'session', 'group', 'thread', 'idempotency-key', 'file', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'kind', 'name', 'cwd', 'task', 'pane', 'lines', 'if-version', 'origin']);
+const VALUE_OPTIONS = new Set(['purpose', 'principal', 'source', 'external-actor', 'external-message-id', 'launch-profile', 'to-event', 'decision', 'work-type', 'summary', 'verdict', 'reviewers', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'session', 'group', 'thread', 'idempotency-key', 'file', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'kind', 'name', 'cwd', 'task', 'pane', 'lines', 'if-version', 'origin']);
 export function parseCollaborationCommand(argv) {
     const options = {};
     const positional = [];
@@ -234,7 +251,7 @@ export function parseCollaborationCommand(argv) {
     else if (action === 'task') {
         command.operation = positional.shift();
         command.target = positional.shift();
-        if (positional.length || !['list', 'get', 'create', 'assign', 'report', 'respond', 'answer', 'ask', 'plan', 'review', 'request-review', 'comment', 'revise', 'close', 'reopen', 'coordinate', 'pause', 'resume', 'retry'].includes(command.operation ?? ''))
+        if (positional.length || !['list', 'get', 'create', 'configure', 'assign', 'report', 'respond', 'answer', 'ask', 'plan', 'review', 'request-review', 'comment', 'revise', 'close', 'reopen', 'coordinate', 'pause', 'resume', 'retry'].includes(command.operation ?? ''))
             throw new Error('Usage: td collab task list|get|create|assign|report|ask|plan|review|request-review|comment|revise|close|reopen');
         if (['list', 'create'].includes(command.operation) ? Boolean(command.target) : !command.target)
             throw new Error('task command requires a full task id except list/create');
@@ -248,6 +265,8 @@ export function parseCollaborationCommand(argv) {
             throw new Error(`${action} requires a target and message`);
         if ([Boolean(command.message), Boolean(options.file), Boolean(options.stdin)].filter(Boolean).length !== 1)
             throw new Error('Choose inline body, --file, or --stdin');
+        if (options.principal && !options['idempotency-key'])
+            throw new Error('Integration message mutation requires an explicit --idempotency-key');
     }
     else if (action === 'rules') {
         command.operation = positional.shift();
@@ -284,8 +303,15 @@ export function parseCollaborationCommand(argv) {
     else if (action === 'message') {
         command.operation = positional.shift();
         command.target = positional.shift();
-        if (!['get', 'watch', 'confirm-shell'].includes(command.operation ?? '') || !command.target || positional.length)
-            throw new Error('Usage: td collab message get|watch|confirm-shell <id>');
+        if (!['get', 'watch', 'confirm-shell', 'list'].includes(command.operation ?? '') || (command.operation === 'list' ? !options.principal || Boolean(command.target) : !command.target) || positional.length)
+            throw new Error('Usage: td collab message get|watch|confirm-shell <id>; --principal <id> message list');
+        if (command.operation === 'list') {
+            for (const flag of Object.keys(options))
+                if (!['principal', 'json', 'jsonl', 'text', 'group', 'thread', 'after-id', 'limit'].includes(flag))
+                    throw new Error(`--${flag} is not supported by message list`);
+        }
+        else if (['group', 'thread', 'after-id', 'limit'].some(flag => options[flag] !== undefined))
+            throw new Error('History filters apply to --principal message list only');
     }
     else if (action === 'cursor') {
         command.operation = positional.shift();
@@ -356,17 +382,20 @@ export function parseCollaborationCommand(argv) {
     const allowed = new Set(['json', 'jsonl', 'text', 'help', 'session', 'principal']);
     const byAction = {
         events: ['consumer', 'group', 'timeout'], session: ['group', 'launch-profile', 'cwd', 'idempotency-key'],
-        task: ['to-event', 'decision', 'source', 'external-actor', 'external-message-id', 'metadata', 'work-type', 'summary', 'integration', 'managed', 'shared-directory', 'reviewers', 'verdict', 'group', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'idempotency-key', 'file', 'stdin'],
+        task: ['purpose', 'to-event', 'decision', 'source', 'external-actor', 'external-message-id', 'metadata', 'work-type', 'summary', 'integration', 'managed', 'shared-directory', 'reviewers', 'verdict', 'group', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'idempotency-key', 'file', 'stdin'],
         rules: ['file', 'stdin', 'if-version'], transport: ['file', 'origin'], group: ['file'], status: [], capabilities: [], rebind: ['pane'], help: [...BOOLEAN_OPTIONS, ...VALUE_OPTIONS],
         send: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'expires-at', 'kind'],
         handoff: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'expires-at'],
         reply: ['idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at'],
         inbox: ['raw', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'group', 'thread', 'kind', 'response-kind', 'follow', 'timeout'],
-        message: ['raw', 'receipt-only', 'no-rules', 'follow', 'wait-until', 'timeout', 'expect-reply'], cursor: ['consumer'],
+        message: ['raw', 'receipt-only', 'no-rules', 'follow', 'wait-until', 'timeout', 'expect-reply', 'group', 'thread', 'after-id', 'limit'], cursor: ['consumer'],
         add: [], remove: [], spawn: ['launch-profile', 'name', 'cwd', 'task'], role: [], rename: [], cleanup: ['confirm'], drive: ['lines', 'raw'],
     };
     for (const option of byAction[action])
         allowed.add(option);
+    if (options.principal && ['send', 'reply'].includes(action))
+        for (const option of ['source', 'external-actor', 'external-message-id'])
+            allowed.add(option);
     for (const option of Object.keys(options))
         if (!allowed.has(option))
             throw new Error(`--${option} is not supported by ${action}`);
@@ -392,7 +421,7 @@ export function waitSatisfied(receipt, stage, reply) {
  *  machine reasons onto what the sender should do next, so a settled-but-
  *  unconsumed message is not mistaken for a lost one (or a good one). */
 const DELIVERY_DIAGNOSTICS = {
-    AGENT_CONSUME_UNCONFIRMED: '消息已写入对方终端，但未确认被对方消费；它可能尚未开始处理，可用 capture 查看当前屏幕或重发',
+    AGENT_CONSUME_UNCONFIRMED: '消息已写入对方终端，但未确认被对方消费；等待明确回复，不从终端快照推断消费或自动重发',
     SHELL_CONFIRMATION_REQUIRED: '目标当前是 shell，消息可能被当命令执行；确认请运行 message confirm-shell <id>',
     DELIVERY_IN_PROGRESS: '投递进行中（写入前的中间标记，正常会在数秒内推进为 delivered 或带原因的重试）',
     TERMINAL_WRITE_FAILED: '写入对方终端失败，会按重试间隔继续尝试',
@@ -428,17 +457,22 @@ export async function executeCollaborationCommand(command, context, io) {
     const output = (value) => {
         if (o.text) {
             let diagnosed = false;
-            if (Array.isArray(value.messages))
+            if (Array.isArray(value.messages)) {
                 for (const message of value.messages) {
                     const fanIds = Array.isArray(message.fanOutIds) ? message.fanOutIds : [];
                     const names = value.names ?? {};
-                    io.write(`[${message.responseKind ?? message.kind}] ${canonicalShortId(message.id)} from ${message.fromSessionId ?? 'user'}${fanIds.length ? ' · 群发' : ''}`);
+                    io.write(`[${message.responseKind ?? message.kind}] ${canonicalShortId(message.id)} from ${message.fromSessionId ?? (message.integrationOrigin ? `principal:${message.integrationOrigin.integrationId}` : 'user')}${fanIds.length ? ' · 群发' : ''}`);
                     // A fan-out dispatch names its sibling recipients so a broadcast is
                     // never read as a one-to-one assignment; unknown ids stay raw.
                     if (fanIds.length)
                         io.write(`同时发给了:${fanIds.map((id) => names[id] ?? id).join('、')}`);
                     io.write(message.content);
+                    if (message.status === 'stored')
+                        io.write('答复已持久保存；接收方是后台程序，不是终端。');
                 }
+                if (value.next_after_id !== undefined)
+                    io.write(`next_after_id=${value.next_after_id ?? ''} has_more=${value.has_more === true}（仅保留记录）`);
+            }
             else if (value.message) {
                 // One line instead of the full rules text — the CLI is stateless so it
                 // cannot diff versions across calls; --no-rules silences it entirely.
@@ -643,12 +677,24 @@ export async function executeCollaborationCommand(command, context, io) {
             return 0;
         }
         if (command.action === 'message') {
+            if (command.operation === 'list') {
+                const params = new URLSearchParams();
+                for (const key of ['group', 'thread', 'after-id', 'limit'])
+                    if (o[key])
+                        params.set(key, String(o[key]));
+                output(await request('GET', `/message?${params}`));
+                return 0;
+            }
             const route = `/message/${encodeURIComponent(command.target)}`;
             if (command.operation === 'confirm-shell') {
                 output(await request('POST', `${route}/${command.operation}`));
                 return 0;
             }
             receipt = await request('GET', `${route}?receipt_only=${Boolean(o['receipt-only'] || command.operation === 'watch')}&raw=${Boolean(o.raw)}`);
+            if (receipt.status === 'stored') {
+                output(receipt);
+                return 0;
+            }
             if (command.operation === 'get' && !o.follow && !o['wait-until'] && !o['expect-reply']) {
                 output(receipt);
                 return 0;
@@ -690,7 +736,7 @@ export async function executeCollaborationCommand(command, context, io) {
             // CLI receipts stay small even when the message is a large evidence package.
             delete receipt.messages;
             receipt.idempotency_key = idempotencyKey;
-            if (receipt.task_recorded) {
+            if (receipt.task_recorded || receipt.integration_recorded) {
                 output(receipt);
                 return 0;
             }

package/dist/server/agent/collaborationPrompt.js

@@ -89,7 +89,7 @@ export function formatCollaborationDelivery(input) {
         const sourceSession = message.fromSessionId ? sessionsById.get(message.fromSessionId) : null;
         const source = message.fromSessionId
             ? sanitizeCollaborationName(sourceSession?.name ?? message.fromSessionId)
-            : '用户';
+            : message.integrationOrigin ? `后台接入 ${sanitizeCollaborationName(message.integrationOrigin.integrationId, 80)}` : '用户';
         const token = tokens.get(message.id) ?? message.id;
         const bytes = Buffer.byteLength(message.content);
         // A remote recipient's CLI cannot detect its identity (the session is not
@@ -103,6 +103,8 @@ export function formatCollaborationDelivery(input) {
         const fannedNames = (message.fanOutIds ?? [])
             .map((sessionId) => sanitizeCollaborationName(sessionsById.get(sessionId)?.name ?? sessionId));
         blocks.push(formatCollaborationMessage({ ...message, content: body }, source, fannedNames, fence, token));
+        if (message.integrationOrigin)
+            blocks.push(`此消息来自后台程序，使用原消息 id 回复：td collab --session ${input.targetSessionId} reply ${token} "答复正文" --response-kind result --idempotency-key <稳定唯一key> --text\n需要时用 --response-kind ack|progress 明确回复收到或进展；result 提交结果。回复持久保存为 stored 并主动推送给后台，不创建看板任务，不代表用户验收。`);
     }
     // The shell header names the group only when every block belongs to one;
     // a mixed batch drops the header entirely (no single-group claim to make).

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

@@ -156,10 +156,12 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
                 managed_goals: true, automatic_review: true, dependency_dispatch: true, isolated_worktrees: true, encrypted_commit_transfer: true,
                 durable_questions: true, user_acceptance: true, versioned_artifacts: true, independent_reviews: true,
                 correlated_responses: true, accepted_comments: true,
+                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',
@@ -207,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/collaborationTaskCli.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import { randomUUID } from 'node:crypto';
+import { CollaborationError } from './collaborationProtocol.js';
+import { taskPurpose, taskPurposeFilter } from './collaborationTaskPurpose.js';
 export async function executeTaskCommand(command, request, io) {
     const o = command.options, operation = command.operation;
     const bodyOptions = ['content', 'file', 'stdin', 'idempotency-key'];
@@ -7,7 +9,7 @@ export async function executeTaskCommand(command, request, io) {
     if (originOptions.some(key => o[key]) && !o.principal)
         throw new Error('External source metadata requires --principal');
     const allowed = {
-        list: ['group'], get: [], create: [...bodyOptions, 'group', 'title', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'managed', 'reviewers', 'shared-directory', 'integration', 'work-type'],
+        list: ['group', 'purpose'], get: [], configure: [...bodyOptions, 'purpose', 'revision'], create: [...bodyOptions, 'purpose', 'group', 'title', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'managed', 'reviewers', 'shared-directory', 'integration', 'work-type'],
         answer: [...bodyOptions, 'decision'], respond: [...bodyOptions, 'attempt', 'to-event', 'evidence'],
         assign: [...bodyOptions, 'assignee', 'revision'], report: [...bodyOptions, 'attempt', 'status', 'evidence', 'summary'], ask: [...bodyOptions, 'attempt', 'options'],
         plan: [...bodyOptions, 'attempt', 'evidence'], review: [...bodyOptions, 'artifact', 'evidence', 'verdict'], comment: bodyOptions,
@@ -18,21 +20,37 @@ export async function executeTaskCommand(command, request, io) {
     for (const flag of Object.keys(o))
         if (![...allowed[operation], ...(o.principal ? originOptions : []), 'principal', 'session', 'json', 'jsonl', 'text', 'help'].includes(flag))
             throw new Error(`--${flag} is not supported by task ${operation}`);
-    if (operation === 'list')
-        return request('GET', `/tasks${o.group ? `?group=${encodeURIComponent(String(o.group))}` : ''}`);
+    if (o.purpose !== undefined)
+        (operation === 'list' ? taskPurposeFilter : taskPurpose)(o.purpose);
+    if (operation === 'configure' && o.purpose === undefined)
+        throw new Error('configure requires --purpose interactive|automation');
+    if (o.purpose !== undefined || operation === 'configure') {
+        const capabilities = await request('GET', '/capabilities');
+        const features = o.principal ? capabilities : capabilities.task_workflow;
+        if (features?.background_task_records !== true || features.task_purpose_configuration !== true || features.explicit_execution_state !== true)
+            throw new CollaborationError('BACKGROUND_TASK_RECORDS_UNSUPPORTED', 'Running service does not support background task records', 409);
+    }
+    if (operation === 'list') {
+        const query = new URLSearchParams();
+        if (o.group)
+            query.set('group', String(o.group));
+        if (o.purpose)
+            query.set('purpose', String(o.purpose));
+        return request('GET', `/tasks${query.size ? `?${query}` : ''}`);
+    }
     if (operation === 'get')
         return request('GET', `/tasks/${encodeURIComponent(command.target)}`);
     const contentSources = [o.content, o.file, o.stdin].filter(Boolean).length;
     if (contentSources > 1)
         throw new Error('Choose --content, --file or --stdin');
     const content = o.file ? fs.readFileSync(String(o.file), 'utf8') : o.stdin ? await io.stdin?.() : o.content;
-    if (!['assign', 'close', 'reopen', 'request-review', 'pause', 'resume', 'retry'].includes(operation) && (typeof content !== 'string' || !content.trim()))
+    if (!['configure', 'assign', 'close', 'reopen', 'request-review', 'pause', 'resume', 'retry'].includes(operation) && (typeof content !== 'string' || !content.trim()))
         throw new Error('This task operation requires --content, --file or --stdin');
     const idempotencyKey = String(o['idempotency-key'] ?? randomUUID());
     const expectedRevision = o.revision === undefined ? undefined : Number(o.revision);
     if (expectedRevision !== undefined && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1))
         throw new Error('--revision must be a positive integer');
-    if (['assign', 'revise', 'close', 'reopen', 'request-review', 'coordinate', 'pause', 'resume', 'retry'].includes(operation) && expectedRevision === undefined)
+    if (['configure', 'assign', 'revise', 'close', 'reopen', 'request-review', 'coordinate', 'pause', 'resume', 'retry'].includes(operation) && expectedRevision === undefined)
         throw new Error('Read task get first, then supply --revision to avoid overwriting another decision');
     if (['assign', 'request-review'].includes(operation) && !o.assignee)
         throw new Error('This task operation requires --assignee');
@@ -46,7 +64,7 @@ export async function executeTaskCommand(command, request, io) {
         if (!o.title || !o.group)
             throw new Error('task create requires --title and --group');
         return request('POST', '/tasks', { input: { idempotencyKey, groupId: o.group, title: o.title, spec: content,
-                constraints: o.constraints, acceptance: o.acceptance, assigneeSessionId: o.assignee, coordinatorSessionId: o.coordinator,
+                purpose: o.purpose, constraints: o.constraints, acceptance: o.acceptance, assigneeSessionId: o.assignee, coordinatorSessionId: o.coordinator,
                 parentTaskId: o.parent, dependsOn: o['depends-on'] ? String(o['depends-on']).split(',').filter(Boolean) : undefined,
                 integration: o.integration === true, managed: o.managed === true, isolated: o['shared-directory'] !== true, workType: o['work-type'],
                 reviewerSessionIds: o.reviewers ? String(o.reviewers).split(',').filter(Boolean) : undefined } });
@@ -55,7 +73,7 @@ export async function executeTaskCommand(command, request, io) {
     if (options !== undefined && (!Array.isArray(options) || options.some(v => typeof v !== 'string')))
         throw new Error('--options must be a JSON array of strings');
     return request('POST', `/tasks/${encodeURIComponent(command.target)}`, { input: {
-            replyToEventId: o['to-event'], decisionId: o.decision, kind: operation === 'plan' ? 'submit-plan' : operation, idempotencyKey, expectedRevision, content,
+            purpose: o.purpose, replyToEventId: o['to-event'], decisionId: o.decision, kind: operation === 'plan' ? 'submit-plan' : operation, idempotencyKey, expectedRevision, content,
             assigneeSessionId: o.assignee, attemptId: o.attempt, status: o.status, artifactId: o.artifact, options, verdict: o.verdict,
             evidence: o.evidence ? JSON.parse(String(o.evidence)) : undefined, summary: o.summary,
         } });

package/dist/server/agent/collaborationTaskPurpose.js

@@ -0,0 +1,20 @@
+import { CollaborationError } from './collaborationProtocol.js';
+export function taskPurpose(value = 'interactive') {
+    if (value !== 'interactive' && value !== 'automation')
+        throw new CollaborationError('INVALID_TASK_PURPOSE', 'purpose must be interactive or automation');
+    return value;
+}
+export function taskPurposeFilter(value = 'all') {
+    return value === 'all' ? value : taskPurpose(value);
+}
+/** Only ordered, explicit reports count. Revisions invalidate the previous round;
+ * comments and responses leave it intact. Delivery never implies completion. */
+export function taskExecution(task) {
+    const report = task.events.filter(e => e.kind === 'report' && e.attemptId === task.activeAttemptId).at(-1);
+    const revision = task.events.filter(e => e.kind === 'revise' && e.attemptId === task.activeAttemptId).at(-1);
+    if (!task.activeAttemptId || !report?.reportStatus || revision && revision.sequence > report.sequence) {
+        return { status: task.activeAttemptId ? 'awaiting_report' : 'unassigned', attemptId: task.activeAttemptId, reportEventId: null, artifactId: null, reportedAt: null };
+    }
+    return { status: report.reportStatus, attemptId: task.activeAttemptId, reportEventId: report.id,
+        artifactId: report.reportStatus === 'complete' ? report.artifactId ?? null : null, reportedAt: report.createdAt };
+}

package/dist/server/agent/collaborationTaskRoutes.js

@@ -40,7 +40,7 @@ export function collaborationTaskRoutes(options) {
     router.get('/', run((req, { tasks, actor }) => {
         const requested = typeof req.query.group === 'string' ? groupId(req.query.group) : null;
         const groups = requested ? [requested] : actor ? options.store.groupsForSession(actor.sessionId).map(g => g.id) : options.store.list().map(g => g.id);
-        return { tasks: groups.flatMap(id => tasks.list(id, actor)) };
+        return { tasks: groups.flatMap(id => tasks.list(id, actor, req.query.purpose ?? (options.agent ? 'all' : 'interactive'))) };
     }));
     router.get('/:taskId', run(async (req, { tasks, actor }) => ({ task: await tasks.get(req.params.taskId, actor) })));
     const input = (req, peers) => {

package/dist/server/agent/collaborationTaskService.js

@@ -1,6 +1,7 @@
 import { CollaborationError } from './collaborationProtocol.js';
 import { captureTaskCommit } from './collaborationTaskWorkspace.js';
 import { taskBundleChunk } from './collaborationTaskBundles.js';
+import { taskExecution, taskPurpose, taskPurposeFilter } from './collaborationTaskPurpose.js';
 import { taskMemberKey } from './collaborationTaskTypes.js';
 /** One authority per task; replicas are records, never competing decision writers. */
 export class CollaborationTaskService {
@@ -56,12 +57,13 @@ export class CollaborationTaskService {
             const template = task.workflow?.reviewers.some(m => taskMemberKey(m) === taskMemberKey(member));
             return { member, sessionId, launchProfile: group.memberLaunchProfiles?.[sessionId], role: `${template ? '此目标的执行成员模板；' : ''}${group.roles?.[sessionId] ?? ''}` };
         });
-        return { ...task, children, roster, launchProfiles: summary ? undefined : group?.launchProfiles, defaultLaunchProfileId: summary ? undefined : group?.defaultLaunchProfileId, memberSessions, replica: task.ownerServiceId !== this.self, summaryOnly: summary, outbox: (summary ? [] : this.tasks.pending(task.id))
+        return { ...task, purpose: taskPurpose(task.purpose), ...(task.purpose === 'automation' ? { execution: task.execution ?? taskExecution(task) } : {}), children, roster, launchProfiles: summary ? undefined : group?.launchProfiles, defaultLaunchProfileId: summary ? undefined : group?.defaultLaunchProfileId, memberSessions, replica: task.ownerServiceId !== this.self, summaryOnly: summary, outbox: (summary ? [] : this.tasks.pending(task.id))
                 .map(({ id, attemptId, messageId, lastError }) => ({ id, attemptId, messageId, lastError })) };
     }
-    list(groupId, actor) {
+    list(groupId, actor, purpose = 'all') {
         this.group(groupId, actor);
-        return this.tasks.list([groupId], true).map(task => this.view(task, true));
+        const filter = taskPurposeFilter(purpose);
+        return this.tasks.list([groupId], true).filter(task => filter === 'all' || taskPurpose(task.purpose) === filter).map(task => this.view(task, true));
     }
     async get(taskId, actor) {
         const task = this.tasks.get(taskId);
@@ -71,8 +73,10 @@ export class CollaborationTaskService {
         return this.view(task);
     }
     async create(input, actor, origin) {
-        this.group(input.groupId, actor);
+        const group = this.group(input.groupId, actor);
         this.validateMembers(input.groupId, input);
+        if (input.purpose === 'automation' && group.federated)
+            throw new CollaborationError('BACKGROUND_TASK_LOCAL_ONLY', '首版后台自动化记录使用本机协作组', 409);
         const dependencies = [...(input.dependsOn ?? []), ...(input.parentTaskId ? [input.parentTaskId] : [])];
         const authority = dependencies.length ? this.tasks.get(dependencies[0])?.ownerServiceId : this.self;
         if (!authority)
@@ -97,8 +101,10 @@ export class CollaborationTaskService {
         const task = this.tasks.get(taskId);
         if (!task)
             throw new CollaborationError('TASK_NOT_FOUND', '任务不存在', 404);
-        this.group(task.groupId, actor);
+        const group = this.group(task.groupId, actor);
         this.validateMembers(task.groupId, input);
+        if (input.kind === 'configure' && input.purpose === 'automation' && group.federated)
+            throw new CollaborationError('BACKGROUND_TASK_LOCAL_ONLY', '首版后台自动化记录使用本机协作组', 409);
         if (origin && task.ownerServiceId !== this.self)
             throw new CollaborationError('INTEGRATION_LOCAL_ONLY', '首版集成任务须由本机服务保存', 409);
         if (task.ownerServiceId !== this.self) {
@@ -131,7 +137,8 @@ export class CollaborationTaskService {
                         commit: child.artifacts.find(a => a.id === child.acceptedArtifactId)?.evidence?.commit })) } };
         }
         const updated = this.tasks.apply(taskId, input, actor, origin);
-        void this.flush();
+        if (input.kind !== 'configure')
+            void this.flush();
         return this.view(updated);
     }
     heads(groupIds) { return this.tasks.heads(groupIds, this.self); }
@@ -261,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(); }