@tencent-ai/agent-harness 0.2.0-beta.2 → 0.2.0-beta.3

package/cli/vendor/shim/brokered-bin/zip

@@ -0,0 +1,187 @@
+#!/bin/sh
+# -e leaves stdin available for zip -@, archive comments and streamed input.
+if [ "${CODEBUDDY_NODE_RUN_AS_NODE:-}" = "1" ]; then export ELECTRON_RUN_AS_NODE=1; fi
+NODE_OPTIONS= exec "${CODEBUDDY_NODE_BIN:-node}" -e '
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const { spawnSync } = require("node:child_process");
+const wrapper = fs.realpathSync(process.argv[1]);
+const program = path.basename(process.argv[1]);
+const shimRoot = path.dirname(path.dirname(wrapper));
+const args = process.argv.slice(2);
+const brokerClient = process.env.CODEBUDDY_BROKER_IPC_CLIENT || path.join(shimRoot, "broker-ipc-client.cjs");
+const { checkProgramPolicy } = require(path.join(shimRoot, "broker-program-policy-check.cjs"));
+const policy = checkProgramPolicy(program, "archive-wrapper", { brokerClientPath: brokerClient });
+if (policy.code) {
+    console.error(policy.error);
+    process.exit(policy.code);
+}
+
+// Only single-archive options are tracked. Do not guess targets for -m, split
+// archives, --out, log files or options injected through ZIPOPT.
+function zipTarget() {
+    if (process.env.ZIPOPT) { return undefined; }
+    let archive;
+    let literal = false;
+    for (const arg of args) {
+        if (!literal && arg === "--") { literal = true; continue; }
+        if (!literal && arg.startsWith("-") && arg !== "-") {
+            // Conservatively exclude any cluster containing lf before parsing.
+            // Even ll+f must be separate arguments to retain rollback tracking.
+            if (arg.includes("lf")) { return undefined; }
+            if (arg === "-FS") { continue; }
+            for (let i = 1; i < arg.length; i++) {
+                // Info-ZIP matches two-character options before single flags,
+                // including inside clusters (e.g. -qlf consumes a log path).
+                const pair = arg.slice(i, i + 2);
+                if (["db", "dc", "dd", "dg", "ds", "du", "dv", "DF", "fd", "fz", "ll", "lf", "la", "li"].includes(pair)) {
+                    if (!["dc", "dd", "dg", "du", "fd", "fz", "ll"].includes(pair)) { return undefined; }
+                    i++;
+                } else if (!/^[0-9rqjXDdufgoyl@cze]$/.test(arg[i])) {
+                    return undefined;
+                }
+            }
+        } else if (archive === undefined) {
+            archive = arg;
+        }
+    }
+    if (archive === "") { return undefined; }
+    if (archive === undefined || archive === "-") { return null; }
+    return path.resolve(path.basename(archive).includes(".") ? archive : archive + ".zip");
+}
+
+function commandArchiveTarget() {
+    const rar = program === "rar";
+    if (rar && !args.includes("-cfg-")) {
+        const home = process.env.HOME || os.homedir();
+        const config = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+        if (process.env.RARINISWITCHES || [path.join(home, ".rarrc"), "/etc/.rarrc", path.join(config, "rar")]
+            .some(file => fs.existsSync(file))) { return undefined; }
+    }
+    let command;
+    let archive;
+    let type = rar ? "rar" : "7z";
+    let literal = false;
+    for (const arg of args) {
+        if (!literal && arg === "--") { literal = true; continue; }
+        if (!literal && arg.startsWith("-")) {
+            if (!rar && /^-t(7z|zip)$/.test(arg)) { type = arg.slice(2); continue; }
+            const supported = rar
+                ? /^(?:-cfg-|-r[0-]?|-m[0-5]|-ma[45]|-id[a-z]+|-y|-s-?|-ep[123]?|-p.*|-hp.*)$/
+                : /^(?:-r[0-]?|-y|-mx=?[0-9]|-mmt(?:=?[0-9]+)?|-p.*|-bb[0-3]|-bd|-b[spo][0-2])$/;
+            if (!supported.test(arg)) { return undefined; }
+        } else if (!command) {
+            command = arg;
+        } else if (archive === undefined) {
+            archive = arg;
+        }
+    }
+    if (!(rar ? ["a", "u", "f"] : ["a", "u"]).includes(command)) { return undefined; }
+    if (!archive || archive.startsWith("@") || /[*?]/.test(archive)) { return undefined; }
+    // RAR first tries an existing exact path; 7-Zip instead appends its default
+    // extension. A trailing dot has special 7-Zip naming semantics we do not infer.
+    if (!rar && archive.endsWith(".")) { return undefined; }
+    if (rar && fs.existsSync(path.resolve(archive))) { return path.resolve(archive); }
+    return path.resolve(path.basename(archive).includes(".") ? archive : archive + "." + type);
+}
+
+function tarTarget() {
+    if (process.env.TAR_OPTIONS) { return undefined; }
+    let archive;
+    let create = false;
+    let literal = false;
+    const modes = new Set(["--create", "--gzip", "--bzip2", "--xz", "--auto-compress", "--verbose"]);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (literal) { continue; }
+        if (arg === "--") { literal = true; continue; }
+        if (modes.has(arg)) { if (arg === "--create") { create = true; } continue; }
+        if (arg === "--file" || arg === "--directory") {
+            const value = args[++i];
+            if (value === undefined) { return undefined; }
+            if (arg === "--file") {
+                if (archive !== undefined) { return undefined; }
+                archive = value;
+            }
+            continue;
+        }
+        if (arg.startsWith("--file=")) {
+            if (archive !== undefined) { return undefined; }
+            archive = arg.slice(7); continue;
+        }
+        if (arg.startsWith("--directory=")) { continue; }
+        if (arg.startsWith("--")) { return undefined; }
+        const oldStyle = i === 0 && /^[cvzjJahfC]+$/.test(arg);
+        if (!arg.startsWith("-") && !oldStyle) { continue; }
+        const flags = oldStyle ? arg : arg.slice(1);
+        for (let j = 0; j < flags.length; j++) {
+            const flag = flags[j];
+            if (flag === "c") { create = true; }
+            else if ("vzjJah".includes(flag)) { continue; }
+            else if (flag === "f" || flag === "C") {
+                const value = !oldStyle && j + 1 < flags.length ? flags.slice(j + 1) : args[++i];
+                if (value === undefined) { return undefined; }
+                if (flag === "f") {
+                    if (archive !== undefined) { return undefined; }
+                    archive = value;
+                }
+                if (!oldStyle) { break; }
+            } else { return undefined; }
+        }
+    }
+    if (!create || !archive) { return undefined; }
+    if (archive === "-") { return null; }
+    if (archive.includes(":")) { return undefined; }
+    return path.resolve(archive);
+}
+
+const brokerEnabled = Boolean(process.env.CODEBUDDY_SANDBOX_BROKER_IPC_ADDRESS
+    && process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID);
+const target = program === "zip" ? zipTarget() : program === "tar" ? tarTarget() : commandArchiveTarget();
+let send;
+function notify(command) {
+    const response = send({ command, operation: "write", path: target,
+        sessionId: process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID,
+        toolCallId: process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID,
+        brokerTraceId: process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID,
+        runtime: "archive-wrapper" });
+    if (!response || (response.ok !== true && response.decision !== "sandbox")) {
+        throw new Error(response?.error || "Archive rollback registration denied");
+    }
+}
+if (brokerEnabled && target === undefined) {
+    console.error("WorkBuddy: file rollback is not tracked for these " + program + " options.");
+}
+if (brokerEnabled && target) {
+    try {
+        const command = process.env.CODEBUDDY_SANDBOX_FILE_TOKEN_OPERATION_COMMAND;
+        if (!command) { throw new Error("Archive write preflight unavailable"); }
+        send = require(brokerClient).sendBrokerRequestSync;
+        notify(command);
+    } catch (error) {
+        console.error(error.message);
+        process.exit(13);
+    }
+}
+
+// Preserve the native command, excluding aliases of this wrapper to avoid recursion.
+const nativePath = (process.env.PATH || "").split(path.delimiter).filter(dir => {
+    try { return fs.realpathSync(path.resolve(dir, program)) !== wrapper; }
+    catch { return true; }
+}).join(path.delimiter);
+const result = spawnSync(program, args, { stdio: "inherit", env: { ...process.env, PATH: nativePath } });
+let status = result.status ?? (result.error?.code === "ENOENT" ? 127 : 1);
+if (result.error) { console.error(result.error.message); }
+// Nonzero exit can still leave an archive. The host checks existence and remembers
+// whether this path was missing at preflight; never infer that from the exit code.
+if (send) {
+    try { notify("FileWriteCompleted"); }
+    catch (error) {
+        console.error("WorkBuddy: " + program + " rollback registration failed: " + error.message);
+        if (status === 0) { status = 13; }
+    }
+}
+if (result.signal) { process.kill(process.pid, result.signal); }
+else { process.exit(status); }
+' "$0" "$@"

package/docs/in-process.md

@@ -64,13 +64,26 @@ await harness.close();
 | `tools` | 工具预设或显式工具数组，见下文。默认使用 `default`。 |
 | `mcp.toolsSyncTtlMs` | 工具目录的兜底刷新间隔，默认 15 分钟；`null` 关闭过期刷新，变更通知仍生效。 |
 | `strictMcpConfig` | 为 `true` 时只使用会话显式传入的 MCP；默认还发现用户和插件 MCP。 |
-| `telemetry` | 日志 sink、队列和刷新设置。库入口默认不写 CLI 日志文件；传入的 sink 由 Harness flush/close。 |
+| `telemetry` | Harness 的结构化日志 sink、队列和刷新设置；传入的 sink 由 Harness flush/close。Agent 内核日志在本地模式默认写入 `configDir/logs`，与此 sink 分开。 |
 | `signal` | Harness 的生命周期取消信号，覆盖创建和运行阶段。 |
 
-当前每个进程支持一个 Harness，关闭后不能在同一进程重启 Agent runtime。不同窗口或工作区使用同一 Harness 的多个 Client/Session。配置目录是进程级设置；文件系统、会话历史及 user/project/local settings 使用现有本地实现。
+每个进程同时支持一个 Harness。不同窗口或工作区使用同一 Harness 的多个 Client/Session。完整关闭后可以创建新实例：
+
+```ts
+const first = await createHarness({ configDir: firstConfigDir });
+// 使用 first …
+await first.close();
+const second = await createHarness({ configDir: secondConfigDir });
+```
+
+`close()` 等待执行任务与连接释放，`closed` 也可以用于等待关闭完成。关闭失败时应处理错误，当前进程不会接纳新实例。旧实例的 `close()` 可以重复调用；连接和会话需要在新实例上重新创建或恢复。
+
+配置目录是进程级设置；关闭后恢复 Harness 写入的环境配置，宿主期间主动修改的值保留。文件系统、会话历史及 user/project/local settings 使用现有本地实现。
 
 项目 Skills、命令、Agent 定义及已启用插件的 persona、MCP、Skills、命令、Agent 和 hooks 随会话的 `cwd` 装载并隔离。磁盘文件与插件提供的 output style、插件 LSP 暂不在多工作区库模式下启用；应用仍可通过 Product 提供 output style。
 
+支持 Desktop 的 welcome-mode + interaction-mode + prompt-common 组合，沿用 CLI 的模板与工具声明规则。插件按会话启用，切换模式后下一轮采用新的指令和工具列表。未声明 `tools` 时继承宿主工具；显式 `tools: []` 清空内置及宿主注册的裸名工具，命名空间 MCP 工具仍沿用原有的 MCP 筛选规则。插件声明只筛选已有工具，宿主仍通过 `createHarness.tools` 注册实现。
+
 `host` 描述应用，`clientInfo` 描述具体连接；账号、Product 模式和凭据仍通过 Client 协商和设置。模型、权限、工作区目录、插件和 Skills 使用现有会话及领域 API。参见 [认证接入](authentication-guide.md)、[Product 配置](product.md) 和 [Client 指南](client.md)。
 
 `productConfig` 在创建时复制；后续修改原对象不会改变 Harness。应用应先解析自己的配置文件和环境选择，再传入结果。需要指定公开 feature 名称时，也可传入 [Product 配置文件](product.md#2-product-文件) 的版本化对象及 `presentation`。
@@ -80,6 +93,8 @@ managed Product 由 Harness 基于这份启动配置和账号解析；external P
 
 库入口不安装进程信号处理器，也不会调用 `process.exit()`。独立进程的 listener、网络认证以及 Windows 宿主进程树回收由入口负责，见 [Server 装配](server.md)。
 
+本地 Harness 默认启用 Agent 的文件日志和 shell snapshot；日志写入 `configDir/logs`，snapshot 暂存于 `configDir/shell-snapshots`（未指定目录时使用 `~/.codebuddy`）。宿主可在创建 Harness 前设置 `CODEBUDDY_DISABLE_FILE_LOGS=1` 或 `CODEBUDDY_DISABLE_SHELL_SNAPSHOT=1` 分别关闭。shell snapshot 在没有 Git Bash 的 Windows 环境仍按 Agent 的平台规则跳过。直接使用 Agent `./server` 的云端宿主保持原有的默认关闭行为。
+
 Windows 上的 Bash 使用非交互 pipe 输出，支持前台、后台任务和终端输出通知；沙箱规则与权限审批照常生效。
 Linux 上安装了对应架构的 `@tencent-ai/sandbox-cli-linux-*` 原生包时，Harness 默认开启平台支持，Session Config Options 提供 `sandbox` 开关。宿主也可通过 `WORKBUDDY_ENABLE_LINUX_SANDBOX_CLI=0` 关闭，或设为 `1` 显式开启（需提供可用的原生程序）。工作区外的 `ask` 规则通过 ACP 请求权限。
 
@@ -148,6 +163,15 @@ const { sessionId } = await client.session.new({
 
 本地 Transport 不写入历史。重新连接或冷恢复会话时重新提供 `mcpServers`；关闭会话或 Client 会关闭其已建立的 MCP 连接。会话挂载 MCP 时，Harness 通过 Executor 发现工具并建立目录；Agent 与 MCP 管理 API 使用同一份会话视图，工具调用也经过 Executor。
 
+会话空闲时，可通过 `session.resume()` 替换完整的 Client MCP 列表，下一次 prompt 使用新目录。省略 `mcpServers` 或传 `[]` 会移除 Client 提供的服务器，用户配置和插件中的 MCP 仍按原合并规则生效。省略 `replayFrom` 不回放历史：
+
+```ts
+await client.session.resume({ sessionId, cwd, mcpServers: nextServers });
+await client.session.resume({ sessionId, cwd, mcpServers: [] });
+```
+
+替换成功会关闭被移除的 MCP 连接并释放 Client 的 Transport 注册；准备失败则保留原列表。前台或 Subagent 仍在执行时，替换返回 busy，待任务结束后重试。多个 Client 共享会话时，由当前持有 MCP 的 Client 更新；旁观 Client 不会接管另一连接的 MCP。
+
 普通 HTTP/stdio MCP 描述仍然受支持。`mcpServers` 属于会话，`tools` 属于应用；两者可以一起使用。
 
 

package/docs/protocol.md

@@ -51,6 +51,8 @@ Harness 在进程内装配 Agent CLI `./server` 与原有管理组件。MCP 的
 
 默认按 Host > 用户 > 插件的优先级合并 MCP。以 `--strict-mcp-config` 启动时，只接受 `session/new` / `session/resume` 的 `mcpServers`；省略或空数组表示无 MCP。该选项在冷恢复和插件选择变更后继续生效，不影响插件的 Commands、Skills、Agents、Hooks、LSP 等组件。
 
+`session/resume.mcpServers` 表示本次 Client 的完整列表，已挂载会话也可以在空闲时替换。省略或空数组会清空 Client 提供的部分；`replayFrom` 独立控制是否回放历史。前台或 Subagent 运行期间不替换连接，返回 busy 供 Client 稍后重试。多连接共享会话时，MCP 的更新权属于当前持有这些连接的 Client。
+
 ## 会话与事件
 
 `session/prompt` 返回接受 ACK，其中 `_meta['codebuddy.ai/requestId']` 标识本轮执行。ACK 不代表模型执行完成。应用通过 `session/update` 的 `state_update` 观察前台 running / idle 与 stopReason；后台任务在前台 idle 后仍可运行，完成后可触发自动续跑。
@@ -99,7 +101,7 @@ Prompt 接受 ACP content，包括 text、image、resource 与 resource_link。A
 
 管理目录与会话当前执行目录是两个视图。`plugin/list`、`skills/list` 和 `agent/list` 用于查询可发现的组件；会话可执行命令以 `available_commands_update` 的完整快照为准。
 
-`config/read` 省略 cwd 时读取 user scope；显式 cwd 时合并相应 workspace 的配置。持久化写入支持版本冲突检测；失败分类见 [错误契约](errors.md)。`session/set_config_option` 只接受该会话 response 或 update 已声明的选项。
+`config/read` 省略 cwd 时读取 user scope；显式 cwd 时合并相应 workspace 的配置。持久化写入支持版本冲突检测；失败分类见 [错误契约](errors.md)。`session/set_config_option` 只接受该会话 response 或 update 已声明的选项；它不会改写用户或项目配置。Harness 只为同一 session 的恢复保留显式选择，sandbox 的展示默认值从当前有效配置读取；其他选项按各自的 Product 和会话初始化规则解析。新选择记录使用独立的 `.selections.json` 文件，不覆盖旧版记录；降级不会恢复新版期间修改的选择。
 
 配置写入与 ConfigChange hooks 已接通。活跃会话的 config/plugin/skill 全量 reload 仍受配置缓存与加载边界限制；不能将写入成功视为所有已加载会话已重载。新建、恢复及插件选择后的命令目录可在提问前取得。
 
@@ -108,3 +110,7 @@ Prompt 接受 ACP content，包括 text、image、resource 与 resource_link。A
 JSON-RPC 边界返回稳定错误分类，不暴露内部异常栈、凭据或上游完整响应。执行期间的诊断通过 error update 交付，并由终态结束前台执行；详情见 [错误契约](errors.md)。
 
 `client.close()` 关闭连接并终止该 Client 实例。进程宿主在 stdin EOF 后会关闭会话与执行设施，再自然退出。网络连接断开后的会话归属、恢复顺序和历史合并见 [ACP v2](acp-v2.md)；应用应使用持久化 sessionId 恢复，而不是假定传输连接本身持有历史。
+
+会话配置恢复保留旧版模型、模式等选择，仅丢弃旧版错误投影的 `sandbox:false`。
+首次 Agent 配置帧用于同步展示；后续实际配置变更更新当前会话的选择记录，不写入全局设置。
+配置默认值在装载及显式 reload 时刷新，不在每次 prompt 确认前读取。读取失败保留已有展示。

package/docs/server.md

@@ -2,6 +2,8 @@
 
 完整应用的 `createHarness()` 与本地工具接入见 [同进程接入](in-process.md)。
 
+Harness 的 Agent 接入使用 `subscribe(sessionId, listener, { format: 'acp-v2' })`，由 Agent Server 直接投影原生事件。消息、附件和工具编码与历史回放共用；Harness 负责连接、配置和权限等宿主策略。
+
 本文面向实现 Harness 领域模块、装配 Server 或扩展 Transport 的开发者。
 IDE、CLI、TUI 等应用的接入方式见 [Client 接入指南](client.md)，完整 binary 的启动与
 进程管理见 [启动进程与接入](client-processes.md)。