agent-gear 2.3.0 → 2.5.0

package/src/harness/opencode-config.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { chmod, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'jsonc-parser';
+import {
+  OpencodeConfigError,
+  ZAG_PROVIDER_NPM,
+  buildZagProvider,
+  resolveOpencodeConfigPath,
+  writeOpencodeConfig,
+} from './opencode-config.js';
+
+const TMP_BASE = '/tmp/opencode';
+
+const ENV = {
+  modelBaseUrl: 'http://admin-api:8002/v1',
+  modelApiKey: 'zag_sk_super_secret',
+  modelIds: ['model-a', 'model-b'],
+};
+
+async function makeDir(): Promise<string> {
+  await mkdir(TMP_BASE, { recursive: true });
+  return mkdtemp(join(TMP_BASE, 'opencode-config-'));
+}
+
+async function fileMode(path: string): Promise<number> {
+  return (await stat(path)).mode & 0o777;
+}
+
+describe('buildZagProvider (T-AG9/T-AG11)', () => {
+  it('builds an OpenAI-compatible provider with baseURL/apiKey/models', () => {
+    expect(buildZagProvider(ENV)).toEqual({
+      npm: '@ai-sdk/openai-compatible',
+      name: 'ZAG',
+      options: {
+        baseURL: 'http://admin-api:8002/v1',
+        apiKey: 'zag_sk_super_secret',
+      },
+      models: {
+        'model-a': { name: 'model-a' },
+        'model-b': { name: 'model-b' },
+      },
+    });
+    expect(ZAG_PROVIDER_NPM).toBe('@ai-sdk/openai-compatible');
+  });
+
+  it('writes models:{} for an empty model list', () => {
+    expect(buildZagProvider({ ...ENV, modelIds: [] }).models).toEqual({});
+  });
+});
+
+describe('writeOpencodeConfig (T-AG9..T-AG12)', () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it('T-AG9: creates opencode.jsonc with provider.zag and 0600 permissions', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+
+    const result = await writeOpencodeConfig({ env: ENV, configDir: dir });
+
+    expect(result.path).toBe(join(dir, 'opencode.jsonc'));
+    expect(result.created).toBe(true);
+    expect(result.modelCount).toBe(2);
+    expect(await fileMode(result.path)).toBe(0o600);
+
+    const config = parse(await readFile(result.path, 'utf-8'));
+    expect(config.provider.zag.options.baseURL).toBe('http://admin-api:8002/v1');
+    expect(config.provider.zag.options.apiKey).toBe('zag_sk_super_secret');
+    expect(config.provider.zag.models).toEqual({
+      'model-a': { name: 'model-a' },
+      'model-b': { name: 'model-b' },
+    });
+  });
+
+  it('T-AG10: merges an existing config, preserving comments and other providers and replacing provider.zag', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const target = join(dir, 'opencode.jsonc');
+    await writeFile(
+      target,
+      `{
+  // keep this comment
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    // existing provider must survive
+    "other": {
+      "npm": "@example/other",
+      "name": "Other",
+      "options": { "baseURL": "http://other" },
+      "models": { "x": { "name": "x" } }
+    },
+    "zag": {
+      "npm": "old-npm",
+      "name": "Old ZAG",
+      "options": { "baseURL": "http://old", "apiKey": "old-key" },
+      "models": {}
+    }
+  }
+}
+`,
+      'utf-8',
+    );
+
+    await writeOpencodeConfig({ env: ENV, configDir: dir });
+
+    const text = await readFile(target, 'utf-8');
+    expect(text).toContain('// keep this comment');
+    expect(text).toContain('// existing provider must survive');
+
+    const config = parse(text);
+    expect(config.$schema).toBe('https://opencode.ai/config.json');
+    expect(config.provider.other).toMatchObject({ npm: '@example/other', name: 'Other' });
+    expect(config.provider.zag).toMatchObject({
+      npm: ZAG_PROVIDER_NPM,
+      name: 'ZAG',
+      options: { baseURL: 'http://admin-api:8002/v1', apiKey: 'zag_sk_super_secret' },
+    });
+    // 旧 apiKey/baseURL 已被替换
+    expect(text).not.toContain('old-key');
+    expect(text).not.toContain('http://old');
+  });
+
+  it('T-AG11: writes models:{} when ZAG_MODEL_IDS is an empty array', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+
+    await writeOpencodeConfig({ env: { ...ENV, modelIds: [] }, configDir: dir });
+
+    const config = parse(await readFile(join(dir, 'opencode.jsonc'), 'utf-8'));
+    expect(config.provider.zag.models).toEqual({});
+  });
+
+  it('T-AG12: merges an existing opencode.json instead of creating a new .jsonc', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const jsonPath = join(dir, 'opencode.json');
+    await writeFile(jsonPath, '{\n  "theme": "dark"\n}\n', 'utf-8');
+
+    const result = await writeOpencodeConfig({ env: ENV, configDir: dir });
+
+    expect(result.path).toBe(jsonPath);
+    expect(result.created).toBe(false);
+    expect(await fileMode(jsonPath)).toBe(0o600);
+
+    const config = parse(await readFile(jsonPath, 'utf-8'));
+    expect(config.theme).toBe('dark');
+    expect(config.provider.zag.name).toBe('ZAG');
+
+    // 不创建并存的 .jsonc
+    await expect(stat(join(dir, 'opencode.jsonc'))).rejects.toThrow();
+  });
+
+  it('T-AG9b: tightens permissions of an existing config to 0600', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const target = join(dir, 'opencode.jsonc');
+    await writeFile(target, '{}\n', 'utf-8');
+    await chmod(target, 0o644);
+
+    await writeOpencodeConfig({ env: ENV, configDir: dir });
+
+    expect(await fileMode(target)).toBe(0o600);
+  });
+
+  it('C-7: tightens an existing config directory to 0700', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    await chmod(dir, 0o755);
+
+    await writeOpencodeConfig({ env: ENV, configDir: dir });
+
+    expect(await fileMode(dir)).toBe(0o700);
+  });
+
+  it('C-7: writes atomically via a temp file and leaves no partial/temp files', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const target = join(dir, 'opencode.jsonc');
+    await writeFile(target, '{\n  "theme": "dark"\n}\n', 'utf-8');
+
+    await writeOpencodeConfig({ env: ENV, configDir: dir });
+
+    // 同目录只应有目标文件（临时文件已 rename 掉）
+    expect(await readdir(dir)).toEqual(['opencode.jsonc']);
+    expect(await fileMode(target)).toBe(0o600);
+    const config = parse(await readFile(target, 'utf-8'));
+    expect(config.theme).toBe('dark');
+    expect(config.provider.zag.name).toBe('ZAG');
+  });
+
+  it('C-7: keeps the original file intact when the write path fails', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const target = join(dir, 'opencode.jsonc');
+    const original = '{\n  "theme": "dark"\n}\n';
+    await writeFile(target, original, 'utf-8');
+    // 目标文件不可读（解析阶段失败）：不得产生临时文件，原文件保持原样。
+    await chmod(target, 0o200);
+
+    await expect(writeOpencodeConfig({ env: ENV, configDir: dir })).rejects.toBeInstanceOf(
+      OpencodeConfigError,
+    );
+
+    expect(await readdir(dir)).toEqual(['opencode.jsonc']);
+    await chmod(target, 0o600);
+    expect(await readFile(target, 'utf-8')).toBe(original);
+  });
+
+  it('rejects invalid JSONC and leaves the file untouched', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const target = join(dir, 'opencode.jsonc');
+    const original = '{ "provider": ';
+    await writeFile(target, original, 'utf-8');
+
+    await expect(writeOpencodeConfig({ env: ENV, configDir: dir })).rejects.toBeInstanceOf(
+      OpencodeConfigError,
+    );
+    expect(await readFile(target, 'utf-8')).toBe(original);
+  });
+
+  it('T-AG12b: resolves the target file by precedence', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+
+    expect(await resolveOpencodeConfigPath(dir)).toBe(join(dir, 'opencode.jsonc'));
+
+    await writeFile(join(dir, 'opencode.json'), '{}\n', 'utf-8');
+    expect(await resolveOpencodeConfigPath(dir)).toBe(join(dir, 'opencode.json'));
+
+    await writeFile(join(dir, 'opencode.jsonc'), '{}\n', 'utf-8');
+    expect(await resolveOpencodeConfigPath(dir)).toBe(join(dir, 'opencode.jsonc'));
+  });
+});

package/src/harness/opencode-config.ts

@@ -0,0 +1,176 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  applyEdits,
+  modify,
+  parse,
+  printParseErrorCode,
+  type FormattingOptions,
+  type ParseError,
+} from 'jsonc-parser';
+import type { HarnessEnv } from './env.js';
+
+/** OpenCode 配置中 `provider.zag` 的结构（OpenAI-compatible 自定义 provider）。 */
+export interface ZagProviderConfig {
+  npm: string;
+  name: string;
+  options: {
+    baseURL: string;
+    apiKey: string;
+  };
+  models: Record<string, { name: string }>;
+}
+
+/** 写入 OpenCode 配置失败（消息只含路径/变量名，不含 key 等 secret）。 */
+export class OpencodeConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OpencodeConfigError';
+  }
+}
+
+/** `provider.zag` 固定使用 OpenAI compatible provider 包。 */
+export const ZAG_PROVIDER_NPM = '@ai-sdk/openai-compatible';
+
+/** 由 harness env 构造 `provider.zag`（模型列表为空时 `models: {}`）。 */
+export function buildZagProvider(
+  env: Pick<HarnessEnv, 'modelBaseUrl' | 'modelApiKey' | 'modelIds'>,
+): ZagProviderConfig {
+  const models: Record<string, { name: string }> = {};
+  for (const id of env.modelIds) {
+    if (!id) continue;
+    models[id] = { name: id };
+  }
+  return {
+    npm: ZAG_PROVIDER_NPM,
+    name: 'ZAG',
+    options: {
+      baseURL: env.modelBaseUrl,
+      apiKey: env.modelApiKey,
+    },
+    models,
+  };
+}
+
+/** 默认配置目录：`~/.config/opencode`。 */
+export function defaultConfigDir(): string {
+  return join(homedir(), '.config', 'opencode');
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 选择配置目标文件（A13）：
+ *
+ * 1. 同目录存在 `opencode.jsonc` → 用它；
+ * 2. 否则同目录只存在 `opencode.json` → 合并该文件（不另建 `.jsonc`）；
+ * 3. 都不存在 → 新建 `opencode.jsonc`。
+ */
+export async function resolveOpencodeConfigPath(configDir = defaultConfigDir()): Promise<string> {
+  const jsoncPath = join(configDir, 'opencode.jsonc');
+  if (await exists(jsoncPath)) return jsoncPath;
+  const jsonPath = join(configDir, 'opencode.json');
+  if (await exists(jsonPath)) return jsonPath;
+  return jsoncPath;
+}
+
+export interface WriteOpencodeConfigOptions {
+  env: Pick<HarnessEnv, 'modelBaseUrl' | 'modelApiKey' | 'modelIds'>;
+  /** 覆盖配置目录（测试/定制场景；缺省 `~/.config/opencode`）。 */
+  configDir?: string;
+}
+
+export interface WriteOpencodeConfigResult {
+  /** 实际写入的配置文件路径。 */
+  path: string;
+  /** 是否为新建文件。 */
+  created: boolean;
+  /** 写入的模型数量。 */
+  modelCount: number;
+}
+
+/**
+ * 写入/合并 OpenCode 配置：
+ *
+ * - 用 `jsonc-parser` 的 `modify` 仅替换 `provider.zag`，保留注释与既有 provider；
+ * - 文件权限固定 `0600`（含已存在文件），目录权限收紧为 `0700`（含已存在目录）；
+ * - 同目录临时文件 + `rename` 原子替换（避免半写文件，C-7）；
+ * - 非法 JSONC 直接报错（不覆盖用户配置，避免静默丢数据）。
+ */
+export async function writeOpencodeConfig(
+  options: WriteOpencodeConfigOptions,
+): Promise<WriteOpencodeConfigResult> {
+  const dir = options.configDir ?? defaultConfigDir();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // `mkdir` 的 mode 只对新建目录生效：已存在目录显式收紧到 0700（可能含模型 Key）。
+  try {
+    await chmod(dir, 0o700);
+  } catch (error) {
+    throw new OpencodeConfigError(
+      `cannot set permissions on OpenCode config directory ${dir}: ${(error as Error).message}`,
+    );
+  }
+
+  const target = await resolveOpencodeConfigPath(dir);
+  const created = !(await exists(target));
+
+  let text = '';
+  if (!created) {
+    try {
+      text = await readFile(target, 'utf-8');
+    } catch (error) {
+      throw new OpencodeConfigError(`cannot read OpenCode config at ${target}: ${(error as Error).message}`);
+    }
+  }
+  if (text.trim().length === 0) {
+    text = '{}\n';
+  }
+
+  const parseErrors: ParseError[] = [];
+  const parsed = parse(text, parseErrors, { allowTrailingComma: true });
+  if (parseErrors.length > 0) {
+    const first = parseErrors[0];
+    throw new OpencodeConfigError(
+      `cannot parse OpenCode config at ${target}: ${printParseErrorCode(first.error)} at offset ${first.offset}`,
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new OpencodeConfigError(`invalid OpenCode config at ${target}: expected a JSON object`);
+  }
+
+  const formattingOptions: FormattingOptions = {
+    insertSpaces: true,
+    tabSize: 2,
+    eol: text.includes('\r\n') ? '\r\n' : '\n',
+  };
+  const provider = buildZagProvider(options.env);
+  const edits = modify(text, ['provider', 'zag'], provider, { formattingOptions });
+  let content = applyEdits(text, edits);
+  if (!content.endsWith('\n')) content += '\n';
+
+  const tempPath = join(dir, `.opencode-config.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    // 先写同目录临时文件（0600）再 rename：失败时原配置保持完整，不产生半写文件。
+    await writeFile(tempPath, content, { encoding: 'utf-8', mode: 0o600 });
+    await chmod(tempPath, 0o600);
+    await rename(tempPath, target);
+  } catch (error) {
+    await rm(tempPath, { force: true }).catch(() => {});
+    throw new OpencodeConfigError(`cannot write OpenCode config at ${target}: ${(error as Error).message}`);
+  }
+
+  return {
+    path: target,
+    created,
+    modelCount: Object.keys(provider.models).length,
+  };
+}

package/src/harness/prepare.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'jsonc-parser';
+import { formatPrepareSummary, prepareHarness } from './prepare.js';
+import { HarnessEnvError } from './env.js';
+import { OpencodeCliError } from './opencode-cli.js';
+import type { CommandRunner } from './opencode-cli.js';
+
+const TMP_BASE = '/tmp/opencode';
+
+const VALID_ENV: NodeJS.ProcessEnv = {
+  ZAG_MODEL_BASE_URL: 'http://admin-api:8002/v1',
+  ZAG_MODEL_API_KEY: 'zag_sk_super_secret',
+  ZAG_MODEL_IDS: '["model-a","model-a"," model-b ",""]',
+  ZAG_DEFAULT_WORKSPACE: '/root/workspace',
+};
+
+async function makeDir(): Promise<string> {
+  await mkdir(TMP_BASE, { recursive: true });
+  return mkdtemp(join(TMP_BASE, 'prepare-'));
+}
+
+describe('prepareHarness (T-AG7..T-AG12)', () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it('validates env, verifies OpenCode, creates the workspace and writes the config', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const workspace = join(dir, 'workspace');
+    const configDir = join(dir, 'config');
+    const runner = vi.fn<CommandRunner>(async () => ({ stdout: '1.2.3\n', stderr: '' }));
+
+    const result = await prepareHarness({
+      env: { ...VALID_ENV, ZAG_DEFAULT_WORKSPACE: workspace },
+      runner,
+      configDir,
+      makeDir: async (path: string) => {
+        await mkdir(path, { recursive: true });
+      },
+    });
+
+    expect(runner).toHaveBeenCalledWith('opencode', ['--version']);
+    expect(result.opencodeVersion).toBe('1.2.3');
+    expect(result.env).toMatchObject({
+      modelBaseUrl: 'http://admin-api:8002/v1',
+      defaultWorkspace: workspace,
+      modelCount: 2,
+    });
+    expect((await stat(workspace)).isDirectory()).toBe(true);
+
+    const config = parse(await readFile(join(configDir, 'opencode.jsonc'), 'utf-8'));
+    expect(Object.keys(config.provider.zag.models)).toEqual(['model-a', 'model-b']);
+    expect(config.provider.zag.options.apiKey).toBe('zag_sk_super_secret');
+  });
+
+  it('fails on missing env before touching OpenCode or the filesystem', async () => {
+    const runner = vi.fn<CommandRunner>(async () => ({ stdout: '1.2.3', stderr: '' }));
+    const makeDirSpy = vi.fn(async () => {});
+
+    await expect(
+      prepareHarness({
+        env: { ...VALID_ENV, ZAG_MODEL_IDS: '' },
+        runner,
+        makeDir: makeDirSpy,
+      }),
+    ).rejects.toBeInstanceOf(HarnessEnvError);
+
+    expect(runner).not.toHaveBeenCalled();
+    expect(makeDirSpy).not.toHaveBeenCalled();
+  });
+
+  it('fails with a version-check error before writing config when OpenCode is unavailable', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const runner = vi.fn<CommandRunner>(async () => {
+      throw new Error('spawn opencode ENOENT');
+    });
+    const configDir = join(dir, 'config');
+
+    await expect(
+      prepareHarness({
+        env: VALID_ENV,
+        runner,
+        configDir,
+        makeDir: async (path: string) => {
+          await mkdir(path, { recursive: true });
+        },
+      }),
+    ).rejects.toBeInstanceOf(OpencodeCliError);
+
+    await expect(stat(configDir)).rejects.toThrow();
+  });
+
+  it('formats a summary without any secret', async () => {
+    const dir = await makeDir();
+    dirs.push(dir);
+    const result = await prepareHarness({
+      env: VALID_ENV,
+      runner: async () => ({ stdout: '1.2.3', stderr: '' }),
+      configDir: join(dir, 'config'),
+      makeDir: async () => {},
+    });
+
+    const summary = formatPrepareSummary(result);
+    expect(summary).toContain('OpenCode harness prepared');
+    expect(summary).toContain('version=1.2.3');
+    expect(summary).toContain('models=2');
+    expect(summary).toContain('workspace=/root/workspace');
+    expect(summary).not.toContain('zag_sk_super_secret');
+    expect(summary).not.toContain('admin-api');
+  });
+});

package/src/harness/prepare.ts

@@ -0,0 +1,69 @@
+import { mkdir } from 'node:fs/promises';
+import { readHarnessEnv, type HarnessEnv } from './env.js';
+import { verifyOpencodeCli, type CommandRunner } from './opencode-cli.js';
+import { writeOpencodeConfig, type WriteOpencodeConfigResult } from './opencode-config.js';
+
+/** `harness prepare` 结果摘要（不含任何 secret）。 */
+export interface HarnessPrepareResult {
+  opencodeVersion: string;
+  env: Pick<HarnessEnv, 'modelBaseUrl' | 'defaultWorkspace'> & { modelCount: number };
+  config: WriteOpencodeConfigResult;
+}
+
+export interface PrepareHarnessOptions {
+  env?: NodeJS.ProcessEnv;
+  /** 命令执行器（测试注入）。 */
+  runner?: CommandRunner;
+  /** 覆盖 OpenCode 配置目录（测试/定制场景）。 */
+  configDir?: string;
+  /** 创建工作区的实现（测试注入）。 */
+  makeDir?: (path: string) => Promise<void>;
+}
+
+/**
+ * 准备 OpenCode harness 环境（契约/计划 Phase 6）：
+ *
+ * 1. 校验 harness env（缺失项明确报错）；
+ * 2. `opencode --version` 硬校验（不通过即失败）；
+ * 3. `mkdir -p ZAG_DEFAULT_WORKSPACE`（幂等）；
+ * 4. 写入/合并 `opencode.jsonc` 的 `provider.zag`（权限 0600）。
+ *
+ * secret 只写入配置文件，不进入日志/错误/返回值。
+ */
+export async function prepareHarness(
+  options: PrepareHarnessOptions = {},
+): Promise<HarnessPrepareResult> {
+  const env = readHarnessEnv(options.env ?? process.env);
+  // init 脚本 export OPENCODE_CLI_VERSION：agent-gear 侧做二次硬校验（C-5，缺省不启用）。
+  const expectedOpencodeVersion = (options.env ?? process.env).OPENCODE_CLI_VERSION;
+  const opencodeVersion = await verifyOpencodeCli(options.runner, expectedOpencodeVersion);
+
+  const makeDir = options.makeDir ?? ((path: string) => mkdir(path, { recursive: true }).then(() => undefined));
+  await makeDir(env.defaultWorkspace);
+
+  const config = await writeOpencodeConfig({
+    env,
+    configDir: options.configDir,
+  });
+
+  return {
+    opencodeVersion,
+    env: {
+      modelBaseUrl: env.modelBaseUrl,
+      defaultWorkspace: env.defaultWorkspace,
+      modelCount: env.modelIds.length,
+    },
+    config,
+  };
+}
+
+/** 输出一行摘要（不含 `ZAG_MODEL_API_KEY` / provider apiKey）。 */
+export function formatPrepareSummary(result: HarnessPrepareResult): string {
+  const created = result.config.created ? 'created' : 'updated';
+  return [
+    `OpenCode harness prepared: version=${result.opencodeVersion}`,
+    `models=${result.env.modelCount}`,
+    `workspace=${result.env.defaultWorkspace}`,
+    `config=${result.config.path} (${created})`,
+  ].join(' ');
+}

package/src/heartbeat.ts

@@ -4,6 +4,8 @@ export class Heartbeat {
   private intervalId: ReturnType<typeof setInterval> | null = null;
 
   start(sendFn: () => void): void {
+    // 重连/重复 registered 时不得遗留旧 interval（否则每轮多一个心跳定时器）。
+    this.stop();
     this.intervalId = setInterval(() => {
       sendFn();
     }, HEARTBEAT_INTERVAL_MS);

package/src/index.ts

@@ -7,6 +7,8 @@ import { connectToServer } from './socketio-client.js';
 import { writePid, removePid, isRunning } from './daemon.js';
 import { startMcpRegistration } from './commands/mcp-proxy.js';
 import { startMcpProxy } from './commands/mcp.js';
+import { registerHarnessCommands } from './commands/harness.js';
+import { isCloudHostMode, startCloudHostSupervisor } from './cloud-host/supervisor.js';
 import { processRegistry, isProcessAlive } from './acp/process-registry.js';
 
 // 版本号唯一事实源为 package.json（`--version` 与 npm 发布版本保持一致，避免手工同步漂移）。
@@ -29,6 +31,23 @@ program
       process.exit(1);
     }
 
+    // 云电脑模式（`ZAG_HOST_ENDPOINT` + `ZAG_HOST_KEY` + `ZAG_CONTROLLER_KEY` 同时存在）：
+    // 双连接编排（/worker 初始化 → controller-api 标准连接），不读取/写入本地 key 配置。
+    if (isCloudHostMode()) {
+      writePid();
+      process.on('exit', () => {
+        removePid();
+      });
+      try {
+        await startCloudHostSupervisor();
+      } catch (error) {
+        console.error(`Cloud host supervisor failed: ${(error as Error).message}`);
+        removePid();
+        process.exit(1);
+      }
+      return;
+    }
+
     const key = resolveKey(options.key);
     if (!key) {
       console.error('No key provided. Use --key, ZAG_CONTROLLER_KEY env, or configure in ~/.zag/config.toml');
@@ -115,4 +134,7 @@ program
     });
   });
 
+// 云电脑 harness 初始化子命令：`agent-gear harness prepare`（init 脚本调用）。
+registerHarnessCommands(program);
+
 program.parse();