dsh-workspace-mover 2.0.3 → 2.1.0

package/docs/ARCHITECTURE.md

@@ -53,6 +53,20 @@ Single logical channel `/workspace-mover` via `ctx.connection.rpc.handle('/works
 
 Errors carry stable codes (`busy`, `conflict`, `not-found`, `rollback-failed`, …). Host logs write failures under `MOVE FAILED`.
 
+## Agent tools (DSH ≥ 0.1.5 with `dsh-tools`)
+
+When the host provides the `tools` service, `apply()` registers three plain (zero-dependency) tool definitions; each tool's execute re-enters the internal RPC dispatch, so agent calls share the panel's locks, error codes, and transaction semantics:
+
+| Tool | Gate | Purpose |
+| --- | --- | --- |
+| `mover_list_sessions` | none (read-only) | Compose scan + workspace list (sessions capped at 40, counts, ghosts, recoveryCount) for id resolution |
+| `mover_move_session` | user approval | Move one session (`sessionId`, `targetWorkspaceId`, optional `sessionTitle`) |
+| `mover_repair_sessions` | user approval | One `mover.repairAll` pass (accounting-only) |
+
+- Mutating tools call `ctx.approval.request({ agent, toolName, reason, signal })` before acting; `allowed-once` proceeds, anything else (`denied` / `cancelled` / `unavailable`) or a throwing seam fails closed. Hosts without the approval seam (no UI) rely on conversational confirmation and proceed.
+- `exec.signal` propagates into the RPC layer; cancellation lets the in-flight step finish rolling back to a consistent state.
+- Hosts without `dsh-tools` skip registration silently; `mover.status` reports the `agentTools` flag.
+
 ## Session archives (v3)
 
 - Naming: `session.v3.jsonl.zstd` or `session.v3.jsonl` (highest generation wins).
@@ -65,8 +79,8 @@ Order of operations for a cross-workspace move:
 
 1. **Running check** — reject only mid-turn sessions (`agents.get(id)?.status === 'running'`); idle resident sessions may move.
 2. **Read authority header** from disk; verify target ≠ source.
-3. **Preflight** — dual-accounting detect, target writability probe, disk-space hint.
-4. **Byte backup** to `$DSH_HOME/workspace-mover/backups/` (rolling 20 per session) **before any side effect**.
+3. **Byte backup** to `$DSH_HOME/workspace-mover/backups/` (rolling 20 per session) **before any side effect** — a backup failure aborts with `backup-failed` and nothing has been touched.
+4. **Preflight** — dual-accounting detect, target writability probe, disk-space hint.
 5. **Rewrite first frame** (header cwd) only.
 6. **Move directory** (Windows: exponential-backoff retry on EPERM; fallback copy+delete).
 7. **In-memory closeout** — invalidate three registry indexes; for resident sessions clear stale persistence-coordinator write state; retarget live header `cwd` before official `attachSession`.

package/lib/index.js

@@ -40,7 +40,9 @@ import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 
 const name = 'workspace-mover';
-const inject = ['workspaceRegistry', 'sessionPersistence'];
+// tools/approval 由 dsh-tools / dsh-user-approval 提供（dsh-base 默认挂载）；
+// 缺失时 Inject.resolve 填 null，agent 工具与审批门相应降级。
+const inject = ['workspaceRegistry', 'sessionPersistence', 'tools', 'approval'];
 
 const CHANNEL = '/workspace-mover';
 const ZSTD_MAGIC = 4247762216;
@@ -145,22 +147,22 @@ function listGenerationArtifacts(dir) {
 	return out.sort((a, b) => b.version - a.version || a.name.localeCompare(b.name));
 }
 
-function findHighestArtifact(dir, compression = 'zstd') {
-	const entries = listGenerationArtifacts(dir);
-	const encodings = new Set(entries.map((entry) => entry.compression));
-	if (encodings.size > 1) {
-		const err = new Error(`mixed session compression encodings under: ${dir}`);
-		err.code = 'unsupported';
-		throw err;
-	}
-	if (entries.length > 0 && !encodings.has(compression)) {
-		const actual = [...encodings][0];
-		const err = new Error(`session compression ${actual} does not match configured ${compression} under: ${dir}`);
-		err.code = 'unsupported';
-		throw err;
-	}
-	return entries[0] ?? null;
-}
+function findHighestArtifact(dir, compression = 'zstd') {
+	const entries = listGenerationArtifacts(dir);
+	const encodings = new Set(entries.map((entry) => entry.compression));
+	if (encodings.size > 1) {
+		const err = new Error(`mixed session compression encodings under: ${dir}`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	if (entries.length > 0 && !encodings.has(compression)) {
+		const actual = [...encodings][0];
+		const err = new Error(`session compression ${actual} does not match configured ${compression} under: ${dir}`);
+		err.code = 'unsupported';
+		throw err;
+	}
+	return entries[0] ?? null;
+}
 
 function preferredArtifactName(compression = 'zstd') {
 	return generationLogFilename(CURRENT_GENERATION, compression);
@@ -2245,8 +2247,141 @@ async function repairAllSessions(ctx) {
 	};
 }
 
+//#region agent tools（v2.1）：把救援/迁移能力暴露给模型
+// 注册的是裸 ToolDefinition 对象（零依赖）：dsh-tools 的 register 只要求
+// { name, description, parameters(JSON Schema), output:{schema, render}, execute }；
+// defineTool 只是参数校验语法糖，execute 内自行做轻校验即可。
+// 变更类工具统一走 ctx.approval.request（dsh-user-approval，dsh-base 默认挂载）
+// 弹用户确认——与面板 confirm 同级的人审；接缝缺失时降级为模型对话纪律。
+
+/** 通过审批接缝请求用户确认；未获准（denied/cancelled/unavailable）一律抛错拒绝。 */
+async function approveOrThrow(ctx, exec, toolName, reason) {
+	const approval = ctx?.approval;
+	if (!exec?.agent || typeof approval?.request !== 'function') return; // 无审批接缝（如无 UI 宿主）：由模型对话纪律兜底
+	let outcome;
+	try {
+		outcome = await approval.request({ agent: exec.agent, toolName, reason, signal: exec.signal });
+	} catch (err) {
+		// request 在回合外等异常情况会抛错：按未批准处理，不静默放行
+		throw new Error(`${toolName} approval could not be requested (${err?.message ?? err}); use the rescue panel in settings instead`);
+	}
+	if (outcome !== 'allowed-once') {
+		throw new Error(`user did not approve this ${toolName} call (outcome: ${outcome ?? 'unavailable'}); ask the user first and only retry after they agree, or use the rescue panel in settings`);
+	}
+}
+
+/** 统一把 dispatch 的 {ok:false,error} 信封转成模型可见的异常（错误码随行）。 */
+async function callDispatch(dispatchRef, endpoint, payload, signal) {
+	if (typeof dispatchRef?.fn !== 'function') throw new Error('workspace-mover RPC is not mounted on this host; the rescue panel is unavailable too');
+	const res = await dispatchRef.fn(endpoint, payload ?? {}, signal);
+	if (!res?.ok) {
+		const err = new Error(`[${res?.error?.code ?? 'internal-error'}] ${res?.error?.message ?? 'request failed'}`);
+		err.code = res?.error?.code;
+		throw err;
+	}
+	return res.value;
+}
+
+const JSON_TEXT = (args, value) => [{ type: 'text', text: JSON.stringify(value) }];
+const LIST_MAX_SESSIONS = 40;
+
+/**
+ * 构造三个 agent 工具（复用 RPC dispatch：锁、错误码、事务语义与面板完全一致）：
+ * - mover_list_sessions   只读：会话/分组清单，供模型把用户口中的名字解析成精确 id
+ * - mover_move_session    迁移单个会话（审批门）
+ * - mover_repair_sessions 一键修复（审批门，只动记账不动文件）
+ */
+function createAgentTools(ctx, dispatchRef) {
+	const SIGNAL_NOTE = 'Cancellation is cooperative: the in-flight step finishes rolling back to a consistent state before stopping.';
+	const tools = [
+		{
+			name: 'mover_list_sessions',
+			description: 'List DSH workspace groups and their sessions for the workspace-mover plugin. Read-only. Returns workspace ids/titles/paths, per-session id/title/path/rescue status (ok / orphaned / unregistered / misfiled / unreadable), aggregate counts, and how many records need manual recovery. Use it to resolve a user-named group or conversation into the exact ids required by mover_move_session and mover_repair_sessions.',
+			parameters: { type: 'object', properties: {}, additionalProperties: false },
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			isConcurrencySafe: () => true,
+			timeoutMs: 30000,
+			async execute(args, exec) {
+				const scan = await callDispatch(dispatchRef, 'mover.scan', {}, exec?.signal);
+				const ws = await callDispatch(dispatchRef, 'mover.workspaces', {}, exec?.signal);
+				const sessions = (scan.items ?? []).slice(0, LIST_MAX_SESSIONS).map((it) => ({
+					sessionId: it.sessionId,
+					title: it.title,
+					cwd: it.cwd,
+					status: it.status,
+					ownerWorkspaceIds: it.ownerWorkspaceIds ?? []
+				}));
+				return {
+					workspaces: (ws.items ?? []).map((w) => ({
+						workspaceId: w.workspaceId,
+						title: w.title,
+						path: w.path,
+						sessionCount: Array.isArray(w.sessionIds) ? w.sessionIds.length : undefined
+					})),
+					sessions,
+					counts: scan.counts ?? {},
+					scanned: scan.scanned,
+					truncated: Boolean(scan.truncated) || (scan.items?.length ?? 0) > LIST_MAX_SESSIONS,
+					recoveryCount: scan.recoveryCount ?? 0,
+					ghosts: (scan.ghosts ?? []).slice(0, 20)
+				};
+			}
+		},
+		{
+			name: 'mover_move_session',
+			description: `Move one DSH session into another workspace group with full protection: byte-level backup is taken before anything changes, then the session header is rewritten, the archive directory is moved atomically, the result is verified by re-reading, and any failure rolls everything back automatically. The session keeps its id and full history; a post-move record enables one-click undo. ${SIGNAL_NOTE} Ask the user to confirm the target group before calling, then pass the exact ids from mover_list_sessions.`,
+			parameters: {
+				type: 'object',
+				properties: {
+					sessionId: { type: 'string', description: 'Exact session id from mover_list_sessions' },
+					targetWorkspaceId: { type: 'string', description: 'Exact workspace id of the destination group from mover_list_sessions' },
+					sessionTitle: { type: 'string', description: 'Optional display title used in move history; omit to use the session\'s own title' }
+				},
+				required: ['sessionId', 'targetWorkspaceId'],
+				additionalProperties: false
+			},
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			timeoutMs: 120000,
+			async execute(args, exec) {
+				const sessionId = validId(args?.sessionId, 'sessionId');
+				const targetWorkspaceId = validId(args?.targetWorkspaceId, 'targetWorkspaceId');
+				await approveOrThrow(ctx, exec, 'mover_move_session', `Move session "${sessionId}" into workspace group "${targetWorkspaceId}" (files are moved on disk with automatic backup and rollback).`);
+				return await callDispatch(dispatchRef, 'mover.move', { sessionId, targetWorkspaceId, sessionTitle: typeof args?.sessionTitle === 'string' ? args.sessionTitle : undefined }, exec?.signal);
+			}
+		},
+		{
+			name: 'mover_repair_sessions',
+			description: `Run one workspace-mover repair pass across all detected session issues: misfiled sessions are re-homed to the group matching their folder, unregistered sessions with a matching group get accounted. Accounting-only — no session files are moved. Anything needing a human decision (orphaned, damaged archives, no matching group) is skipped with a stated reason, and results report fixed / skipped / failed. ${SIGNAL_NOTE} Ask the user to confirm before calling.`,
+			parameters: { type: 'object', properties: {}, additionalProperties: false },
+			output: { schema: { type: 'object' }, render: JSON_TEXT },
+			timeoutMs: 120000,
+			async execute(args, exec) {
+				await approveOrThrow(ctx, exec, 'mover_repair_sessions', 'Run a workspace-mover repair pass (accounting-only fixes for misfiled / unregistered sessions; no files are moved).');
+				return await callDispatch(dispatchRef, 'mover.repairAll', {}, exec?.signal);
+			}
+		}
+	];
+	return tools;
+}
+
+/** 宿主带 dsh-tools 时注册；逐工具隔离失败（一个失败不影响其余），缺服务时静默跳过。 */
+function registerAgentTools(ctx, dispatchRef, logger, agentToolsState = { registered: false }) {
+	if (typeof ctx?.tools?.register !== 'function') return;
+	for (const tool of createAgentTools(ctx, dispatchRef)) {
+		try {
+			ctx.tools.register(tool);
+			agentToolsState.registered = true;
+		} catch (err) {
+			logger?.warn?.(`workspace-mover: agent tool '${tool?.name}' registration failed: ${err?.message ?? err}`);
+		}
+	}
+}
+//#endregion
+
 export function apply(ctx) {
 	const logger = ctx.logger ?? console;
+	const dispatchRef = { fn: null }; // agent 工具在调用期才用到 dispatch，挂载时序无关
+	const agentToolsState = { registered: false };
 	const mount = (owner) => {
 		const connection = owner?.connection;
 		if (!connection?.rpc?.handle) return;
@@ -2254,7 +2389,7 @@ export function apply(ctx) {
 		// to this injected web context so rpc.handle() can register on webServer.
 		const rawConnection = connection[Symbol.for('cordis.original')] ?? connection;
 		const scopedConnection = rawConnection?.[Symbol.for('cordis.extend')]?.({ ctx: owner }) ?? connection;
-		const dispose = scopedConnection.rpc.handle(CHANNEL, async (endpoint, payload = {}, signal) => {
+		const dispatch = async (endpoint, payload = {}, signal) => {
 		if (signal?.aborted) return { ok: false, error: { code: 'cancelled', message: 'cancelled', details: {} } };
 		try {
 			switch (endpoint) {
@@ -2280,6 +2415,7 @@ export function apply(ctx) {
 						channel: CHANNEL,
 						capabilities,
 						degradedFeatures,
+						agentTools: agentToolsState.registered,
 						recoveryCount: recoveryCount()
 					});
 				}
@@ -2432,7 +2568,9 @@ export function apply(ctx) {
 		} catch (err) {
 			return mapError(err);
 		}
-		}, { authority: 'loopback' });
+		};
+		dispatchRef.fn = dispatch;
+		const dispose = scopedConnection.rpc.handle(CHANNEL, dispatch, { authority: 'loopback' });
 		owner.effect?.(() => () => { try { dispose?.(); } catch { /* ignore */ } }, 'workspace-mover: rpc dispose');
 	};
 
@@ -2441,6 +2579,8 @@ export function apply(ctx) {
 	} else {
 		mount(ctx);
 	}
+
+	registerAgentTools(ctx, dispatchRef, logger, agentToolsState);
 }
 
 export { name, inject, CHANNEL, projectKey, encodeSegment, sessionDir, artifactPath, generationLogFilename, parseGenerationLogFilename, listGenerationArtifacts, findHighestArtifact, preferredArtifactName, moveDir, stashBackup, verifyRelocatedArtifact, deleteSessionToTrash, moveSession, moveSessionEntry, validId, SCAN_MAX_ITEMS };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-workspace-mover",
-  "version": "2.0.3",
-  "description": "在 DSH 侧边栏安全迁移会话：真迁移原始档案，支持失联会话恢复、移动历史和一键撤回。",
+  "version": "2.1.0",
+  "description": "在 DSH 侧边栏安全迁移会话：真迁移原始档案，支持失联会话恢复、移动历史、一键撤回和 agent 工具。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -32,7 +32,8 @@
     "workspace",
     "session",
     "session-migration",
-    "drag-and-drop"
+    "drag-and-drop",
+    "agent-tools"
   ],
   "engines": {
     "node": ">=22",

package/test/e2e-sandbox.test.mjs

@@ -1802,3 +1802,120 @@ test('mover.session.delete: archived resident idle session still refuses delete'
   assert.ok(existsSync(artifactPath(root, A, 'session-aaa')), 'artifact untouched');
   assert.deepEqual(ctx.workspaceRegistry.archivedSessionIds, ['session-aaa']);
 });
+
+// ===== v2.1.0 agent 工具 =====
+
+/** 给 ctx 挂上 dsh-tools / dsh-user-approval 的测试替身，返回工具定义捕获数组和审批记录。 */
+function mountToolStubs(approvalOutcome = 'allowed-once') {
+  const registered = [];
+  const approvalCalls = [];
+  ctx.tools = { register: (def) => registered.push(def) };
+  ctx.approval = {
+    async request(req) {
+      approvalCalls.push(req);
+      if (typeof approvalOutcome === 'function') return approvalOutcome(req);
+      return approvalOutcome;
+    }
+  };
+  return { registered, approvalCalls };
+}
+
+const FAKE_EXEC = () => ({ agent: { session: {} }, signal: undefined });
+
+test('v2.1 apply 在带 dsh-tools 的宿主上注册三个 agent 工具，status 汇报能力位', async () => {
+  const { registered } = mountToolStubs();
+  apply(ctx);
+  assert.deepEqual(registered.map((t) => t.name), ['mover_list_sessions', 'mover_move_session', 'mover_repair_sessions']);
+  for (const def of registered) {
+    assert.equal(typeof def.execute, 'function', `${def.name}.execute`);
+    assert.equal(typeof def.output?.render, 'function', `${def.name}.output.render`);
+    assert.equal(def.output?.schema?.type, 'object', `${def.name}.output.schema`);
+  }
+  assert.equal(registered[1].parameters.required.join(','), 'sessionId,targetWorkspaceId');
+  const status = await call('mover.status');
+  assert.equal(status.value.agentTools, true);
+});
+
+test('v2.1 无 dsh-tools 宿主上 apply 不受影响（静默跳过）', async () => {
+  apply(ctx);
+  const status = await call('mover.status');
+  assert.equal(status.ok, true);
+  assert.equal(status.value.agentTools, false);
+});
+
+test('v2.1 mover_list_sessions 合成 scan + workspaces（含状态与计数）', async () => {
+  const { registered } = mountToolStubs();
+  apply(ctx);
+  const list = registered.find((t) => t.name === 'mover_list_sessions');
+  entityA.record.sessionIds.push('session-aaa'); // 夹具本就未记账：记账后断言 ok 路径
+  const value = await list.execute({}, FAKE_EXEC());
+  assert.ok(value.workspaces.some((w) => w.workspaceId === 'wid-a'));
+  assert.ok(value.workspaces.some((w) => w.workspaceId === 'wid-b'));
+  const aaa = value.sessions.find((s) => s.sessionId === 'session-aaa');
+  assert.ok(aaa, 'fixture session listed');
+  assert.equal(aaa.status, 'ok');
+  assert.deepEqual(aaa.ownerWorkspaceIds, ['wid-a']);
+  assert.equal(typeof value.counts, 'object');
+  assert.equal(value.recoveryCount, 0);
+});
+
+test('v2.1 mover_move_session 审批通过后经 dispatch 迁移成功', async () => {
+  const { registered, approvalCalls } = mountToolStubs();
+  apply(ctx);
+  const move = registered.find((t) => t.name === 'mover_move_session');
+  const exec = FAKE_EXEC();
+  const value = await move.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' }, exec);
+  assert.equal(value.verified, true);
+  assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, B);
+  assert.equal(approvalCalls.length, 1);
+  assert.equal(approvalCalls[0].toolName, 'mover_move_session');
+  assert.equal(approvalCalls[0].agent, exec.agent);
+  assert.match(String(approvalCalls[0].reason), /session-aaa/);
+});
+
+test('v2.1 审批拒绝 / 接缝异常时 move 拒绝执行（fail-closed）', async () => {
+  for (const outcome of ['denied', 'cancelled', 'unavailable']) {
+    const { registered } = mountToolStubs(outcome);
+    apply(ctx);
+    const move = registered.find((t) => t.name === 'mover_move_session');
+    await assert.rejects(
+      move.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' }, FAKE_EXEC()),
+      new RegExp(outcome)
+    );
+    assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, A, `${outcome} 后文件未动`);
+  }
+  // 接缝抛错：同样不放行
+  const { registered: reg2 } = mountToolStubs(() => { throw new Error('no open turn'); });
+  apply(ctx);
+  const move2 = reg2.find((t) => t.name === 'mover_move_session');
+  await assert.rejects(move2.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-b' }, FAKE_EXEC()), /could not be requested/);
+  assert.equal(readHeader(readFileSync(findArtifact('session-aaa'))).cwd, A);
+});
+
+test('v2.1 mover_move_session 错误码透传；无效输入不惊动审批', async () => {
+  const { registered, approvalCalls } = mountToolStubs();
+  apply(ctx);
+  const move = registered.find((t) => t.name === 'mover_move_session');
+  await assert.rejects(
+    move.execute({ sessionId: 'session-aaa', targetWorkspaceId: 'wid-nope' }, FAKE_EXEC()),
+    /\[not-found\]/
+  );
+  await assert.rejects(
+    move.execute({ sessionId: 'x'.repeat(301), targetWorkspaceId: 'wid-b' }, FAKE_EXEC()),
+    /\[invalid-input\]|must be a non-empty string/
+  );
+  assert.equal(approvalCalls.length, 1, 'invalid-input 在审批前就被拦截');
+});
+
+test('v2.1 mover_repair_sessions 走审批并修复未记账夹具会话', async () => {
+  const { registered, approvalCalls } = mountToolStubs();
+  apply(ctx);
+  const repair = registered.find((t) => t.name === 'mover_repair_sessions');
+  // 夹具 session-aaa 有匹配分组（wid-a）但未记账：repairAll 应把它补账
+  const value = await repair.execute({}, FAKE_EXEC());
+  assert.equal(value.fixedCount, 1);
+  assert.equal(value.failedCount, 0);
+  assert.ok(entityA.record.sessionIds.includes('session-aaa'), 'repair 后已补账');
+  assert.equal(approvalCalls.length, 1);
+  assert.equal(approvalCalls[0].toolName, 'mover_repair_sessions');
+});