termdock 1.4.316 → 1.4.317

package/dist/server/agent/collaborationPrompt.js

@@ -23,7 +23,7 @@ export function collaborationRulesAge(updatedAt, now = Date.now()) {
  * names may carry them, so the render layer neutralizes them defensively;
  * user-entered names are rejected at creation instead.
  */
-export const COLLAB_NAME_FORBIDDEN = /[【】「」·\x00-\x1f\x7f]/;
+export { COLLAB_NAME_FORBIDDEN } from './collaborationProtocol.js';
 /** Render-safe name for shell header / per-message source lines: reserved
  * bracket and delimiter characters become spaces (they would otherwise split
  * the `「X」群` and `来自:X · kind` lines), control characters are

package/dist/server/agent/collaborationProtocol.js

@@ -1,4 +1,6 @@
 import crypto from 'node:crypto';
+/** Shared local group-name validation; presentation keeps its compatible export. */
+export const COLLAB_NAME_FORBIDDEN = /[【】「」·\x00-\x1f\x7f]/;
 /** Transport facts and application reports deliberately remain separate. */
 export const COLLAB_LIMITS = {
     message_bytes: 1_048_576,

package/dist/server/agent/collaborationStore.js

@@ -3,7 +3,7 @@ import { validateLaunchProfiles } from './collaborationLaunchProfiles.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { COLLAB_LIMITS, CollaborationError, STATUS_RANK, canonicalShortId, drawCollaborationId, newCollaborationId, resolveIdPrefix, validateExtras } from './collaborationProtocol.js';
+import { COLLAB_NAME_FORBIDDEN, COLLAB_LIMITS, CollaborationError, STATUS_RANK, canonicalShortId, drawCollaborationId, newCollaborationId, resolveIdPrefix, validateExtras } from './collaborationProtocol.js';
 function newerRevision(a, b) {
     return !b || a.updatedAt > b.updatedAt || (a.updatedAt === b.updatedAt && a.version > b.version);
 }
@@ -64,9 +64,10 @@ export class CollaborationStore {
             activity_observed_at: typeof observedAt === 'number' && Number.isFinite(observedAt) ? observedAt : null,
             last_peer_sync_at: Date.now(), activity_source: 'remote_terminal_output' });
     }
-    document = { version: 2, groups: [], messages: [], terminalHistoryComplete: true };
+    document = { version: 2, groups: [], messages: [], terminalHistoryComplete: true, localGroupRequestsComplete: true };
     persistedDocument = JSON.stringify(this.document);
     historyAvailable = true;
+    groupCreationAvailable = true;
     /** `drawId` is the random source behind newCollaborationId. It is a
      *  constructor seam so tests can force a collision and prove the guard
      *  below actually skips it; production always uses the CSPRNG default. */
@@ -94,6 +95,14 @@ export class CollaborationStore {
                     this.document.sequence = Math.max(this.document.sequence ?? 0, message.sequence);
                 }
             }
+            const requests = parsed.localGroupRequests;
+            this.groupCreationAvailable = [1, 2].includes(parsed.version ?? 0) && Array.isArray(parsed.groups)
+                && (parsed.localGroupRequestsComplete === undefined || parsed.localGroupRequestsComplete === true) && (requests === undefined || requests !== null && typeof requests === 'object' && !Array.isArray(requests)
+                && Object.entries(requests).every(([key, value]) => /^[a-f0-9]{64}$/.test(key) && value && /^[a-f0-9]{64}$/.test(value.hash)
+                    && value.group && typeof value.group.id === 'string' && typeof value.group.name === 'string'
+                    && Array.isArray(value.group.sessionIds) && value.group.sessionIds.length === 0 && value.group.federated === false
+                    && Number.isSafeInteger(value.group.createdAt) && Number.isSafeInteger(value.group.updatedAt)));
+            this.document.localGroupRequests = this.groupCreationAvailable ? requests ?? {} : {};
             this.document.sequence = Math.max(parsed.sequence ?? 0, this.document.sequence ?? 0);
             this.document.idempotency = parsed.idempotency ?? {};
             this.document.consumers = parsed.consumers ?? {};
@@ -104,8 +113,10 @@ export class CollaborationStore {
         }
         catch (error) {
             this.historyAvailable = error.code === 'ENOENT';
+            this.groupCreationAvailable = this.historyAvailable;
         }
         this.document.terminalHistoryComplete = this.historyAvailable;
+        this.document.localGroupRequestsComplete = this.groupCreationAvailable;
         this.persistedDocument = JSON.stringify(this.document);
     }
     list() {
@@ -170,6 +181,39 @@ export class CollaborationStore {
         this.persist();
         return group;
     }
+    /** The administrator request and empty local group share one durable commit.
+     * No terminal identity, arbitrary membership, or federation is involved. */
+    createEmptyLocalGroup(value, key) {
+        if (typeof value !== 'string' || !value.trim() || value.length > 256 || COLLAB_NAME_FORBIDDEN.test(value)) {
+            throw new CollaborationError('INVALID_GROUP', 'name must be non-empty text up to 256 characters without forbidden group-name characters', 400);
+        }
+        if (typeof key !== 'string' || !key.trim() || key.length > 256)
+            throw new CollaborationError('INVALID_IDEMPOTENCY_KEY', 'An explicit 1..256 character idempotency key is required', 400);
+        if (!this.groupCreationAvailable)
+            throw new CollaborationError('GROUP_CREATION_STATE_UNCONFIRMED', 'Creation journal is unavailable; reconcile the persisted state before creating another group', 409);
+        const name = value.trim(), requestKey = crypto.createHash('sha256').update(key).digest('hex');
+        const hash = crypto.createHash('sha256').update(JSON.stringify(['empty-local-group', name])).digest('hex');
+        const previous = this.document.localGroupRequests?.[requestKey];
+        if (previous) {
+            if (previous.hash !== hash)
+                throw new CollaborationError('IDEMPOTENCY_CONFLICT', 'This administrator key was used for different group parameters', 409);
+            const current = this.getGroup(previous.group.id);
+            if (!current || current.deleted || current.federated)
+                throw new CollaborationError('GROUP_CREATE_TARGET_UNAVAILABLE', 'Original local group was deleted or changed; this key cannot create a replacement', 409);
+            return structuredClone(previous.group);
+        }
+        if (Object.keys(this.document.localGroupRequests ?? {}).length >= 2000)
+            throw new CollaborationError('GROUP_CREATE_LIMIT', 'Administrator group creation journal has reached its 2000-record limit', 409);
+        const now = Date.now(), group = { id: newCollaborationId(this.takenIds(), this.drawId), name,
+            sessionIds: [], federated: false, createdAt: now, updatedAt: now };
+        this.document = { ...this.document, groups: [...this.document.groups, group], localGroupRequests: {
+                ...this.document.localGroupRequests, [requestKey]: { hash, group: structuredClone(group) }
+            } };
+        // persist restores the last committed document on failure. A post-rename
+        // fsync failure retains the committed request so retries cannot duplicate.
+        this.persist(true);
+        return structuredClone(group);
+    }
     setMemberLaunchProfile(groupId, sessionId, profile) {
         const group = this.getGroup(groupId);
         if (!group || group.deleted || !group.sessionIds.includes(sessionId))
@@ -326,7 +370,7 @@ export class CollaborationStore {
     clear() {
         if (this.document.groups.length === 0 && this.document.messages.length === 0)
             return;
-        this.document = { version: 2, groups: this.document.groups
+        this.document = { version: 2, localGroupRequests: this.document.localGroupRequests, localGroupRequestsComplete: this.groupCreationAvailable, groups: this.document.groups
                 .map((group) => group.deleted ? group : ({ ...group, deleted: true, updatedAt: Math.max(Date.now(), group.updatedAt + 1) })), messages: [] };
         this.persist();
     }

package/dist/server/agent/integrationCli.js

@@ -8,6 +8,18 @@ import { COLLAB_HELP, executeCollaborationCommand, duration } from './collaborat
 import { getTermdockVersion } from '../utils/version.js';
 export const INTEGRATION_HELP = `td integration — local scoped integration administration
   groups | list
+  group create --name <name> --idempotency-key <key>
+    Administrator only; create an empty local group without a terminal source.
+    Minimum CLI/running service 1.4.317; admin_local_group_create=true.
+    Returns {group: original creation snapshot}; same key/parameters reuse it.
+    Groups may later gain members; the snapshot is not their current membership.
+    No IDs, members, federation, launch profiles or principal credentials accepted.
+    Deleted/changed targets are not recreated; preserve the key after uncertain results.
+    Errors: INVALID_GROUP, INVALID_IDEMPOTENCY_KEY, IDEMPOTENCY_CONFLICT,
+    GROUP_CREATE_TARGET_UNAVAILABLE, GROUP_CREATION_STATE_UNCONFIRMED,
+    GROUP_CREATE_LIMIT (2000 retained creation records), ADMIN_LOCAL_GROUP_CREATE_UNSUPPORTED.
+    Next authorize a new fixed-group principal using integration create; no empty
+    administrator terminal is required. Existing principal/session ownership is unchanged.
   clear-startup-input <TD-session-id> --generation <N>
     Administrator removes this session's saved screen conditions and disables
     inheritance on later restores; original identity/launch/history are preserved.
@@ -89,6 +101,24 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
             return 0;
         }
         const socketPath = integrationSocketPath(port);
+        if (action === 'group') {
+            const args = {};
+            const usage = 'Usage: td integration group create --name <name> --idempotency-key <key>';
+            if (argv[1] !== 'create')
+                throw new CollaborationError('INVALID_GROUP_CREATE_REQUEST', usage, 400);
+            for (let i = 2; i < argv.length; i += 2) {
+                if (!['--name', '--idempotency-key'].includes(argv[i]) || !argv[i + 1] || Object.hasOwn(args, argv[i]))
+                    throw new CollaborationError('INVALID_GROUP_CREATE_REQUEST', usage, 400);
+                args[argv[i]] = argv[i + 1];
+            }
+            if (!args['--name']?.trim() || !args['--idempotency-key']?.trim() || Object.keys(args).length !== 2)
+                throw new CollaborationError('INVALID_GROUP_CREATE_REQUEST', usage, 400);
+            const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
+            if (capabilities.admin_local_group_create !== true)
+                throw new CollaborationError('ADMIN_LOCAL_GROUP_CREATE_UNSUPPORTED', 'CLI and running service must support empty local group creation (minimum 1.4.317)', 409);
+            write(JSON.stringify(parsed(await request(socketPath, 'POST', '/admin/groups', { name: args['--name'], idempotency_key: args['--idempotency-key'] }, headers(undefined, adminToken)))));
+            return 0;
+        }
         if (action === 'clear-startup-input') {
             const id = argv[1];
             if (argv.length !== 4 || !id || !/^[a-zA-Z0-9._-]{1,80}$/.test(id) || argv[2] !== '--generation'

package/dist/server/agent/integrationServer.js

@@ -69,6 +69,14 @@ export class IntegrationRuntime {
                 integrationError('INTEGRATION_ADMIN_REQUIRED', 'Local administration credential is required', 401);
         };
         app.get('/admin/groups', run(req => { admin(req); return { groups: options.messages.list().filter(g => !g.federated).map(g => ({ id: g.id, name: g.name })) }; }));
+        app.post('/admin/groups', run(req => {
+            admin(req);
+            const body = req.body;
+            if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(key => !['name', 'idempotency_key'].includes(key))) {
+                integrationError('INVALID_GROUP_CREATE_REQUEST', 'Specify only name and idempotency_key; members, federation, IDs and launch configuration are not accepted');
+            }
+            return { group: options.messages.createEmptyLocalGroup(body.name, body.idempotency_key) };
+        }));
         app.get('/admin/capabilities', run(req => { admin(req); return this.capabilities(); }));
         app.get('/admin/sessions/:id/restore-diagnostics', run(req => { admin(req); return { ...this.sessions.restoreDiagnostics(req.params.id), ...this.sessions.launchDiagnostics(req.params.id) }; }));
         app.get('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return this.sessions.resumeConfiguration(req.params.id); }));
@@ -233,6 +241,7 @@ export class IntegrationRuntime {
             session_cold_retry: true, session_cold_retry_min_version: '1.4.314',
             session_rename: true, session_rename_min_version: '1.4.315',
             session_close: true, session_close_min_version: '1.4.315',
+            admin_local_group_create: true, admin_local_group_create_min_version: '1.4.317',
             integration_policy_update: true,
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',

package/docs/integrations.md

@@ -1026,3 +1026,70 @@ TD 生命周期锁不排他控制外部 tmux 命令/手工进程替换，最终
 永久审计存储。close 不增加 task、看板或 accepted。真实私有 TraeX 与 DevBox
 共享升级/业务适配由接入方后续验收；维护侧验证仅覆盖隔离测试的真实 tmux/Linux
 进程退出与源码回归。macOS 真实 close 路径尚未实机验收。
+
+## 1.4.317：管理员幂等创建空本机组
+
+最低 **CLI / 实际服务均为 1.4.317**，协议仍为 1。管理员回读
+`admin_local_group_create=true`、`admin_local_group_create_min_version=1.4.317`；
+旧服务缺少能力时 CLI 返回 `ADMIN_LOCAL_GROUP_CREATE_UNSUPPORTED`，不回退到终端
+成员来源、网页裸 HTTP 或私有文件写入。
+
+```sh
+td integration group create --name 'Case A' --idempotency-key case-a:group
+# 返回 {"group":{"id":"...","name":"Case A","sessionIds":[],
+#              "federated":false,"createdAt":...,"updatedAt":...}}
+td integration groups   # 回读现有本机组的id/name
+# 使用返回的group.id填入新的独立policy.groupId：
+td integration create --file case-a-policy.json --credential-file case-a-credential.json
+```
+
+本机 Unix socket 管理路由 `POST /admin/groups`，JSON 只接受
+`{name,idempotency_key}`。沿用本机管理员 credential 的鉴权与协议版本检查，由正式
+CLI 从服务状态读取管理员凭据；不要把它放在命令行、消息、日志，也不要发给 Agent。
+principal 凭据不能调用此入口（`INTEGRATION_ADMIN_REQUIRED`），没有新增 principal
+建组权限。请求不能携带成员/目标ID/federated/launchProfiles/principal 等字段，
+即使 `sessionIds=[]` 也属于多余参数，返回 `INVALID_GROUP_CREATE_REQUEST`。
+
+名称去除首尾空白，非空、最多 256 字符，沿用现有本机组的禁止字符规则（括号
+`【】「」`、间隔号 `·`、C0 控制字符及 DEL）。名称不作为唯一标识；不同 key 同名可以
+建立不同组。幂等 key 必须非空、最多 256 字符，按原字符串区分；存储中只保存其哈希。
+API 名称非法返回 `INVALID_GROUP`，key 非法返回 `INVALID_IDEMPOTENCY_KEY`。
+
+创建记录和空组写入同一个协作存储文件，以一次 durable 原子替换提交，包含文件与
+父目录 fsync。服务内同步执行，无终端/tmux/Agent 启动和正文投递；不包含 principal
+授权、业务调度或三模型创建。**组创建与后续 principal 授权是两步操作，不是一个事务**。
+后者继续遵循已有凭据落盘、唯一 principal ID、固定授权组和拒绝静默替换规则。
+
+同服务存储中，同 key 同参数（名称规范化后）返回原创建快照，包括原 ID、空成员和
+原时间；同 key 异参返回 `IDEMPOTENCY_CONFLICT`。之后给原组加入成员或改名，不会改变
+创建快照，不能把重试响应的空 `sessionIds` 当作当前成员清单；当前名称可用 groups
+回读，成员清单沿现有组管理读接口。HTTP 回执丢失或持久写入结果不明时，保留原 key
+和名称重试对账，不要换新 key “再建一个”。
+
+文件替换前失败不会提交半个组；替换后 fsync/回执异常可能已经创建，应同键对账。
+服务重启保留 key→原快照映射。原组被明确删除、变成跨服务目标或原 ID 已不存在时，
+同键返回 `GROUP_CREATE_TARGET_UNAVAILABLE`，不新建替代组；全局清理也保留该 key 的
+保留记录。创建 journal 损坏、无法可靠读取或其完整性未确认返回
+`GROUP_CREATION_STATE_UNCONFIRMED`，普通存储写入不会自动把这种情况改称“已确认”。
+此时管理员先对账/修复可信存储，不能通过换 key 绕过。
+
+每个服务存储最多保留 2,000 个此入口的创建记录（含已删除组的 key 保留记录），满时
+新 key 返回 `GROUP_CREATE_LIMIT`；已有 key 仍可回读。首版无 TTL/forget，不为腾空间
+静默删除幂等证据。这不增加会话、普通消息、事件 journal 的原保留额度；调用者负责
+组/凭据/逻辑记录预算。保证范围是唯一运行服务写入同一持久存储；不提供多个独立
+服务共享文件的分布式事务，不能降级到旧写入器后再假设幂等证据仍完整。
+
+推荐外部宿主按自身业务创建独立本机组，再用现有 integration create 授权独立
+principal，可复用相同的 launchProfiles 配置模板。已有组允许零活动成员，随后
+principal create/restore 不要求保留空管理终端。此能力不创建业务 Case、定时器、
+consumer、task 或看板任务；Case/组/principal/session/message 映射由宿主持久保存。
+
+已有 principal 的 groupId 仍不可修改（`INTEGRATION_GROUP_IMMUTABLE`）；普通成员迁组
+也不会迁移 IntegrationSession 的归属、旧消息/reply、事件或 ACK 游标。此入口不提供
+旧 Case/原会话迁移。新组独立使用新授权，已有链路保持原归属完成/关闭。
+
+事件订阅协议未改变：新 consumer 从该组保留窗口最早可见位置开始，并非“从现在”
+开始；读取不自动 ACK。当前没有公开 ready/subscribed 帧，进程启动不能当订阅完成。
+即使普通 send 早于实际订阅建立，保留期内的事实也可重放；宿主按 event_id 持久
+去重/连续 ACK，并按原 message ID/reply_to 用历史对账明确回复。heartbeat 仅是连接
+观测，不表示宿主 inbox 已落盘或业务已完成。

package/package.json

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

package/runtime-manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.316",
+  "version": "1.4.317",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-oaGYi/P5ob8sd6VnNBOwshKozjhdV+hYiCmLAsn5x00=",
-  "serverBundleHash": "sha256-DAZwKtCVOjhre1SF4x800AfouUy22Cyfat68O+E8Hlo=",
+  "serverBundleHash": "sha256-1pRiIEg4Lpi8gtQSmaiVWgjK0PZrrA+QobxZC5+PEWc=",
   "clientBundleHash": "sha256-iwZyAmz8pDZptAaDUwHHnAqZlIvu6R9xpWhvQhPz3xY=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"