agent-gear 2.4.0 → 2.5.0

package/src/commands/harness.ts

@@ -0,0 +1,44 @@
+import type { Command } from 'commander';
+import { collectSecretValues, redactSecrets } from '../workload-executor.js';
+import { formatPrepareSummary, prepareHarness, type PrepareHarnessOptions } from '../harness/prepare.js';
+
+export interface RegisterHarnessCommandsDeps {
+  prepare?: (options?: PrepareHarnessOptions) => Promise<Awaited<ReturnType<typeof prepareHarness>>>;
+}
+
+/**
+ * 注册 `agent-gear harness` 命令组。
+ *
+ * ```
+ * agent-gear harness prepare   # 校验 env → opencode --version → 写 opencode.jsonc
+ * ```
+ *
+ * 失败以退出码 1 结束（供 harness 工作负载 `required=true` 触发容器强制注销）；
+ * 输出/错误均对 `ZAG_MODEL_API_KEY` 等 secret 脱敏。
+ */
+export function registerHarnessCommands(
+  program: Command,
+  deps: RegisterHarnessCommandsDeps = {},
+): Command {
+  const harness = program
+    .command('harness')
+    .description('Prepare harness runtime (OpenCode) for cloud-host containers');
+
+  harness
+    .command('prepare')
+    .description('Validate harness env, verify OpenCode CLI and write provider.zag into opencode.jsonc')
+    .action(async () => {
+      try {
+        const result = await (deps.prepare ?? prepareHarness)();
+        console.log(formatPrepareSummary(result));
+      } catch (error) {
+        const secrets = collectSecretValues(process.env);
+        const message = redactSecrets((error as Error).message, secrets);
+        console.error(`harness prepare failed: ${message}`);
+        // 非零退出：不直接 process.exit，便于测试断言 exitCode 与已刷新的日志。
+        process.exitCode = 1;
+      }
+    });
+
+  return harness;
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { parse, stringify } from 'smol-toml';
@@ -23,9 +23,15 @@ export function readConfig(): ConfigData {
 
 export function writeConfig(data: ConfigData): void {
   if (!existsSync(CONFIG_DIR)) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  // 配置含 Key/resumeToken：仅属主可读写（避免 world-readable 凭据落盘）。
+  writeFileSync(CONFIG_FILE, stringify(data), { encoding: 'utf-8', mode: 0o600 });
+  try {
+    chmodSync(CONFIG_FILE, 0o600);
+  } catch {
+    // 某些平台/文件系统不支持 chmod：不阻断配置写入（已在 Windows 等平台降级）
   }
-  writeFileSync(CONFIG_FILE, stringify(data), 'utf-8');
 }
 
 export function clearConfigKey(): void {

package/src/harness/env.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import { HarnessEnvError, parseModelIds, readHarnessEnv } from './env.js';
+
+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-b"]',
+  ZAG_DEFAULT_WORKSPACE: '/root/workspace',
+};
+
+describe('readHarnessEnv (T-AG7/T-AG11)', () => {
+  it('reads a valid harness env', () => {
+    expect(readHarnessEnv(VALID_ENV)).toEqual({
+      modelBaseUrl: 'http://admin-api:8002/v1',
+      modelApiKey: 'zag_sk_super_secret',
+      modelIds: ['model-a', 'model-b'],
+      defaultWorkspace: '/root/workspace',
+    });
+  });
+
+  it('lists all missing variables by name and never leaks secret values', () => {
+    let error: unknown;
+    try {
+      readHarnessEnv({ ZAG_MODEL_API_KEY: 'zag_sk_super_secret' });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(HarnessEnvError);
+    const message = (error as Error).message;
+    expect(message).toContain('ZAG_MODEL_BASE_URL');
+    expect(message).toContain('ZAG_MODEL_IDS');
+    expect(message).toContain('ZAG_DEFAULT_WORKSPACE');
+    expect(message).not.toContain('ZAG_MODEL_API_KEY');
+    expect(message).not.toContain('zag_sk_super_secret');
+  });
+
+  it('trims values', () => {
+    const env = readHarnessEnv({
+      ...VALID_ENV,
+      ZAG_MODEL_BASE_URL: '  http://admin-api:8002/v1  ',
+    } as NodeJS.ProcessEnv);
+    expect(env.modelBaseUrl).toBe('http://admin-api:8002/v1');
+  });
+
+  it('rejects a missing default workspace', () => {
+    expect(() => readHarnessEnv({ ...VALID_ENV, ZAG_DEFAULT_WORKSPACE: '' })).toThrowError(
+      /ZAG_DEFAULT_WORKSPACE/,
+    );
+  });
+});
+
+describe('parseModelIds (T-AG11)', () => {
+  it('dedupes and drops empty/whitespace entries while preserving order', () => {
+    expect(parseModelIds('["b"," a ","b","","   ","c","a"]')).toEqual(['b', 'a', 'c']);
+  });
+
+  it('accepts an empty array', () => {
+    expect(parseModelIds('[]')).toEqual([]);
+  });
+
+  it('rejects invalid JSON without echoing the raw value', () => {
+    let error: unknown;
+    try {
+      parseModelIds('not-json');
+    } catch (caught) {
+      error = caught;
+    }
+    expect(error).toBeInstanceOf(HarnessEnvError);
+    expect((error as Error).message).toContain('ZAG_MODEL_IDS');
+    expect((error as Error).message).not.toContain('not-json');
+  });
+
+  it('rejects non-array and non-string elements', () => {
+    expect(() => parseModelIds('{"a":1}')).toThrowError(/JSON array of strings/);
+    expect(() => parseModelIds('["a",1]')).toThrowError(/non-string element/);
+    expect(() => parseModelIds('null')).toThrowError(/JSON array of strings/);
+  });
+});

package/src/harness/env.ts

@@ -0,0 +1,89 @@
+/**
+ * harness（OpenCode 云电脑）初始化环境校验。
+ *
+ * 只读取 `harness prepare` 需要的变量；缺失/非法时一次性列出**变量名**，
+ * 绝不回显其它 env 的值（尤其 `ZAG_MODEL_API_KEY` 等 secret）。
+ */
+
+/** harness prepare 需要的环境（已归一）。 */
+export interface HarnessEnv {
+  /** 模型网关地址（`ZAG_MODEL_BASE_URL`）。 */
+  modelBaseUrl: string;
+  /** 运行专用模型 Key（`ZAG_MODEL_API_KEY`，禁止打印）。 */
+  modelApiKey: string;
+  /** 可用模型 ID 列表（`ZAG_MODEL_IDS`，JSON 数组字符串，去空去重）。 */
+  modelIds: string[];
+  /** 默认工作区（`ZAG_DEFAULT_WORKSPACE`）。 */
+  defaultWorkspace: string;
+}
+
+/** env 校验失败（消息不含任何变量值）。 */
+export class HarnessEnvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HarnessEnvError';
+  }
+}
+
+function nonEmpty(value: string | undefined): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * 解析 `ZAG_MODEL_IDS`：必须是字符串 JSON 数组；元素 trim 后去空、去重（保持原顺序）。
+ *
+ * - `[]` 合法（T-AG11：空数组仍写 `models:{}`）；
+ * - 非数组/非法 JSON/含非字符串元素 → 明确报错（不输出原始值）。
+ */
+export function parseModelIds(raw: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new HarnessEnvError('ZAG_MODEL_IDS must be a JSON array of strings (invalid JSON)');
+  }
+  if (!Array.isArray(parsed)) {
+    throw new HarnessEnvError('ZAG_MODEL_IDS must be a JSON array of strings');
+  }
+  if (!parsed.every((item) => typeof item === 'string')) {
+    throw new HarnessEnvError('ZAG_MODEL_IDS must be a JSON array of strings (non-string element)');
+  }
+  const unique: string[] = [];
+  const seen = new Set<string>();
+  for (const item of parsed as string[]) {
+    const value = item.trim();
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    unique.push(value);
+  }
+  return unique;
+}
+
+/**
+ * 读取并校验 harness env。
+ *
+ * 必需：`ZAG_MODEL_BASE_URL` / `ZAG_MODEL_API_KEY` / `ZAG_MODEL_IDS` / `ZAG_DEFAULT_WORKSPACE`
+ * （云电脑 Job env 与 `workload:run.env` 均由 agent-api 注入，缺失说明编排不正确）。
+ */
+export function readHarnessEnv(env: NodeJS.ProcessEnv = process.env): HarnessEnv {
+  const missing: string[] = [];
+  const modelBaseUrl = nonEmpty(env.ZAG_MODEL_BASE_URL);
+  if (!modelBaseUrl) missing.push('ZAG_MODEL_BASE_URL');
+  const modelApiKey = nonEmpty(env.ZAG_MODEL_API_KEY);
+  if (!modelApiKey) missing.push('ZAG_MODEL_API_KEY');
+  const rawModelIds = nonEmpty(env.ZAG_MODEL_IDS);
+  if (!rawModelIds) missing.push('ZAG_MODEL_IDS');
+  const defaultWorkspace = nonEmpty(env.ZAG_DEFAULT_WORKSPACE);
+  if (!defaultWorkspace) missing.push('ZAG_DEFAULT_WORKSPACE');
+
+  if (missing.length > 0) {
+    throw new HarnessEnvError(`missing required environment variable(s): ${missing.join(', ')}`);
+  }
+
+  return {
+    modelBaseUrl,
+    modelApiKey,
+    modelIds: parseModelIds(rawModelIds),
+    defaultWorkspace,
+  };
+}

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

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  OpencodeCliError,
+  extractVersion,
+  verifyOpencodeCli,
+  type CommandRunner,
+} from './opencode-cli.js';
+
+describe('verifyOpencodeCli (T-AG8)', () => {
+  it('runs `opencode --version` and returns the version', async () => {
+    const runner = vi.fn<CommandRunner>(async () => ({ stdout: '1.2.3\n', stderr: '' }));
+
+    await expect(verifyOpencodeCli(runner)).resolves.toBe('1.2.3');
+    expect(runner).toHaveBeenCalledWith('opencode', ['--version']);
+    expect(runner).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to `opencode -v` for legacy CLIs', async () => {
+    const runner = vi.fn<CommandRunner>(async (_command, args) => {
+      if (args[0] === '--version') throw new Error('unknown option');
+      return { stdout: 'v0.9.1\n', stderr: '' };
+    });
+
+    await expect(verifyOpencodeCli(runner)).resolves.toBe('0.9.1');
+    expect(runner).toHaveBeenNthCalledWith(1, 'opencode', ['--version']);
+    expect(runner).toHaveBeenNthCalledWith(2, 'opencode', ['-v']);
+  });
+
+  it('falls back to `-v` when `--version` prints no version', async () => {
+    const runner = vi.fn<CommandRunner>(async (_command, args) =>
+      args[0] === '--version'
+        ? { stdout: '   \n', stderr: '' }
+        : { stdout: '2.0.0\n', stderr: '' },
+    );
+
+    await expect(verifyOpencodeCli(runner)).resolves.toBe('2.0.0');
+  });
+
+  it('throws a version-check error when both commands fail', async () => {
+    const runner = vi.fn<CommandRunner>(async () => {
+      throw new Error('spawn opencode ENOENT');
+    });
+
+    let error: unknown;
+    try {
+      await verifyOpencodeCli(runner);
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(OpencodeCliError);
+    const message = (error as Error).message;
+    expect(message).toContain('version check failed');
+    expect(message).toContain('opencode --version');
+    expect(message).toContain('opencode -v');
+    expect(message).toContain('ENOENT');
+  });
+
+  it('C-5: validates the expected pinned version (tolerates v prefix and command output prefix)', async () => {
+    const runner = vi.fn<CommandRunner>(async () => ({ stdout: 'v2.1.1\n', stderr: '' }));
+    await expect(verifyOpencodeCli(runner, '2.1.1')).resolves.toBe('2.1.1');
+
+    const prefixed = vi.fn<CommandRunner>(async () => ({ stdout: 'opencode 2.1.1\n', stderr: '' }));
+    await expect(verifyOpencodeCli(prefixed, '2.1.1')).resolves.toBe('opencode 2.1.1');
+  });
+
+  it('C-5: throws immediately on a pinned version mismatch', async () => {
+    const runner = vi.fn<CommandRunner>(async () => ({ stdout: '2.0.0\n', stderr: '' }));
+
+    await expect(verifyOpencodeCli(runner, '2.1.1')).rejects.toThrow(
+      /version mismatch: expected 2\.1\.1, got 2\.0\.0/,
+    );
+    // 不匹配即失败，不再退回 `-v`
+    expect(runner).toHaveBeenCalledTimes(1);
+  });
+
+  it('reads the version from stderr when stdout is empty', () => {
+    expect(extractVersion('', 'opencode 1.0.0\n')).toBe('opencode 1.0.0');
+    expect(extractVersion('\n\n3.2.1\n')).toBe('3.2.1');
+    expect(extractVersion('   ')).toBeUndefined();
+  });
+});

package/src/harness/opencode-cli.ts

@@ -0,0 +1,99 @@
+import { execFile } from 'node:child_process';
+
+/** 一次外部命令执行结果（stdout/stderr 均为完整文本）。 */
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+}
+
+/** 可注入的命令执行器（测试使用；生产走 `execFile`）。 */
+export type CommandRunner = (command: string, args: string[]) => Promise<CommandResult>;
+
+/** `opencode --version` 硬校验失败。 */
+export class OpencodeCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OpencodeCliError';
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+const defaultRunner: CommandRunner = (command, args) =>
+  new Promise<CommandResult>((resolve, reject) => {
+    execFile(
+      command,
+      args,
+      { timeout: DEFAULT_TIMEOUT_MS, maxBuffer: 1024 * 1024, encoding: 'utf8' },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve({ stdout: stdout ?? '', stderr: stderr ?? '' });
+      },
+    );
+  });
+
+/** 从版本输出中取第一行非空文本（去掉前后空白与可能的 `v` 前缀）。 */
+export function extractVersion(stdout: string, stderr = ''): string | undefined {
+  const line = `${stdout}\n${stderr}`
+    .split(/\r?\n/)
+    .map((value) => value.trim())
+    .find((value) => value.length > 0);
+  if (!line) return undefined;
+  return line.replace(/^v/i, '');
+}
+
+/**
+ * `opencode --version` 硬校验（`opencode -v` 仅作旧版 CLI 的兼容探测）。
+ *
+ * `expectedVersion` 非空时要求实际版本严格一致（去掉 `v` 前缀后比较），不一致立即失败，
+ * 用于 init 脚本已固定安装版本的二次校验（C-5）。
+ *
+ * 失败时抛 {@link OpencodeCliError}，消息包含「版本校验」提示与命令级错误摘要
+ * （不包含任何 env/secret）。调用方（init 脚本 / `harness prepare`）必须以非零退出。
+ */
+export async function verifyOpencodeCli(
+  runner: CommandRunner = defaultRunner,
+  expectedVersion?: string,
+): Promise<string> {
+  const failures: string[] = [];
+
+  const normalizeVersion = (version: string): string =>
+    (version.trim().split(/\s+/).pop() ?? '').replace(/^v/i, '');
+
+  const ensureExpected = (version: string): string => {
+    if (expectedVersion && normalizeVersion(version) !== normalizeVersion(expectedVersion)) {
+      throw new OpencodeCliError(
+        `OpenCode CLI version mismatch: expected ${expectedVersion}, got ${version}`,
+      );
+    }
+    return version;
+  };
+
+  try {
+    const result = await runner('opencode', ['--version']);
+    const version = extractVersion(result.stdout, result.stderr);
+    if (version) return ensureExpected(version);
+    failures.push('`opencode --version` returned no version output');
+  } catch (error) {
+    if (error instanceof OpencodeCliError) throw error;
+    failures.push(`\`opencode --version\` failed: ${(error as Error).message}`);
+  }
+
+  // 兼容旧版 CLI：仅当 `--version` 不可用时探测 `-v`。
+  try {
+    const result = await runner('opencode', ['-v']);
+    const version = extractVersion(result.stdout, result.stderr);
+    if (version) return ensureExpected(version);
+    failures.push('`opencode -v` returned no version output');
+  } catch (error) {
+    if (error instanceof OpencodeCliError) throw error;
+    failures.push(`\`opencode -v\` failed: ${(error as Error).message}`);
+  }
+
+  throw new OpencodeCliError(
+    `OpenCode CLI version check failed; OpenCode is required by the harness workload (${failures.join('; ')})`,
+  );
+}

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

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const fs = vi.hoisted(() => ({
+  chmod: vi.fn(),
+  mkdir: vi.fn(),
+  readFile: vi.fn(),
+  rename: vi.fn(),
+  rm: vi.fn(),
+  stat: vi.fn(),
+  writeFile: vi.fn(),
+}));
+
+vi.mock('node:fs/promises', () => fs);
+
+import { OpencodeConfigError, writeOpencodeConfig } from './opencode-config.js';
+
+const ENV = {
+  modelBaseUrl: 'http://admin-api:8002/v1',
+  modelApiKey: 'zag_sk_super_secret',
+  modelIds: ['model-a'],
+};
+
+describe('R2-16 opencode config atomic write failure cleanup', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    fs.mkdir.mockResolvedValue(undefined);
+    fs.chmod.mockResolvedValue(undefined);
+    fs.writeFile.mockResolvedValue(undefined);
+    fs.rm.mockResolvedValue(undefined);
+    // 目标文件不存在 → 走新建分支
+    fs.stat.mockRejectedValue(new Error('ENOENT'));
+  });
+
+  it('removes the temp file when rename fails and preserves the original error surface', async () => {
+    fs.rename.mockRejectedValue(new Error('rename failed'));
+
+    await expect(
+      writeOpencodeConfig({ env: ENV, configDir: '/tmp/opencode-r2-16' }),
+    ).rejects.toBeInstanceOf(OpencodeConfigError);
+
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      expect.stringMatching(/\/tmp\/opencode-r2-16\/\.opencode-config\..*\.tmp$/),
+      expect.any(String),
+      { encoding: 'utf-8', mode: 0o600 },
+    );
+    expect(fs.rm).toHaveBeenCalledWith(
+      expect.stringMatching(/\/tmp\/opencode-r2-16\/\.opencode-config\..*\.tmp$/),
+      { force: true },
+    );
+  });
+});