agent-gear 2.4.0 → 2.5.0

package/src/workload-executor.ts

@@ -39,6 +39,52 @@ export interface WorkloadRunPayload {
   items: WorkloadItem[];
   /** `post` 批次共享总预算（毫秒）；`init` 不携带。 */
   budgetMs?: number;
+  /**
+   * 容器级环境变量（仅 `purpose=harness` 下发，如 `ZAG_MODEL_*` / `ZAG_HOST_*`）。
+   * 对批次内所有 item 生效；`item.params` 派生的 `WORKLOAD_PARAM_*` 同名时优先。
+   */
+  env?: Record<string, string>;
+}
+
+/** 需要在日志/错误/脚本输出中脱敏的环境变量名（契约 §2.9「云电脑初始化 env」）。 */
+export const SECRET_ENV_KEYS = ['ZAG_MODEL_API_KEY', 'ZAG_HOST_KEY', 'ZAG_CONTROLLER_KEY'] as const;
+
+/** 脱敏占位符。 */
+export const REDACTED = '***';
+
+/**
+ * 收集需要脱敏的 secret 值（仅非空值；调用方可叠加批次 `env` 与 `process.env`）。
+ */
+export function collectSecretValues(...sources: Array<Record<string, string | undefined> | undefined>): string[] {
+  const values = new Set<string>();
+  for (const source of sources) {
+    if (!source) continue;
+    for (const key of SECRET_ENV_KEYS) {
+      const value = source[key];
+      if (typeof value === 'string' && value.length > 0) values.add(value);
+    }
+  }
+  // 长值优先替换，避免短 secret 是长 secret 的子串时留下残片。
+  return [...values].sort((a, b) => b.length - a.length);
+}
+
+/** 将文本中出现的 secret 值替换为 `***`（日志、错误与脚本输出统一口径）。 */
+export function redactSecrets(text: string, secrets: Iterable<string>): string {
+  let result = text;
+  for (const secret of secrets) {
+    if (!secret) continue;
+    result = result.split(secret).join(REDACTED);
+  }
+  return result;
+}
+
+export interface WorkloadBatchOutcome {
+  /** 批次是否被新批次/销毁流程打断（打断时不得视为初始化完成）。 */
+  cancelled: boolean;
+  /** 已上报的失败/超时条目数（含 required 短路前的当前条）。 */
+  failedCount: number;
+  /** 本批条目总数。 */
+  total: number;
 }
 
 export type WorkloadStatus = 'success' | 'failed' | 'timeout';
@@ -112,6 +158,20 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+/**
+ * 归一容器级 `env`：只接受字符串键值（服务端报文里 `ZAG_*` 均为字符串），
+ * 非对象/数组一律视为未下发（普通容器行为不变）。
+ */
+function normalizeContainerEnv(env: Record<string, string> | undefined): Record<string, string> {
+  if (!env || typeof env !== 'object' || Array.isArray(env)) return {};
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!key || typeof value !== 'string') continue;
+    normalized[key] = value;
+  }
+  return normalized;
+}
+
 /** 单个参数值 → 环境变量字符串（契约 §2.9「参数注入约定」）。 */
 function encodeParamValue(value: unknown): string {
   if (typeof value === 'string') return value;
@@ -123,17 +183,23 @@ function encodeParamValue(value: unknown): string {
 }
 
 /**
- * 由 `process.env` 派生单条 item 的执行环境：
+ * 由 `process.env` + 容器级 `env` 派生单条 item 的执行环境：
+ * - 容器级 `env`（harness 下发的 `ZAG_*`）先合并，对批次所有 item 生效；
  * - `WORKLOAD_PARAMS`：完整参数 JSON 字符串（缺省 `{}`）；
- * - `WORKLOAD_PARAM_<KEY_UPPER>`：单值编码（字符串原样、布尔 `"true"`/`"false"`、多选 JSON 数组字符串）。
+ * - `WORKLOAD_PARAM_<KEY_UPPER>`：单值编码（字符串原样、布尔 `"true"`/`"false"`、多选 JSON 数组字符串），
+ *   同名时**覆盖**容器 `env`（item 参数优先）。
  *
- * 每次 spawn 都从当前 `process.env` 重新派生，参数 env 仅对当前 item 生效、不污染后续脚本；
+ * 每次 spawn 都重新派生，参数 env 仅对当前 item 生效、不污染后续脚本；
  * 不修改脚本文本、不做字符串替换（避免注入）。
  */
-function buildWorkloadEnv(params: Record<string, unknown> | undefined): NodeJS.ProcessEnv {
+function buildWorkloadEnv(
+  params: Record<string, unknown> | undefined,
+  containerEnv: Record<string, string> | undefined,
+): NodeJS.ProcessEnv {
   const normalized = params && typeof params === 'object' && !Array.isArray(params) ? params : {};
   const env: NodeJS.ProcessEnv = {
     ...process.env,
+    ...normalizeContainerEnv(containerEnv),
     WORKLOAD_PARAMS: JSON.stringify(normalized),
   };
   for (const [key, value] of Object.entries(normalized)) {
@@ -158,7 +224,7 @@ function buildWorkloadEnv(params: Record<string, unknown> | undefined): NodeJS.P
  */
 export class WorkloadExecutor {
   private active: ActiveRun | null = null;
-  private activePromise: Promise<void> | null = null;
+  private activePromise: Promise<WorkloadBatchOutcome> | null = null;
   private pendingResults: WorkloadResult[] = [];
 
   /** 当前是否有批次正在执行。 */
@@ -207,7 +273,7 @@ export class WorkloadExecutor {
   /**
    * 执行一个批次。若已有批次在跑，先终止其进程组并停止推进，再执行新批次。
    */
-  runBatch(payload: WorkloadRunPayload, onResult: WorkloadResultSink): Promise<void> {
+  runBatch(payload: WorkloadRunPayload, onResult: WorkloadResultSink): Promise<WorkloadBatchOutcome> {
     this.interruptActive();
 
     const run: ActiveRun = { cancelled: false, child: null };
@@ -227,22 +293,33 @@ export class WorkloadExecutor {
     payload: WorkloadRunPayload,
     onResult: WorkloadResultSink,
     run: ActiveRun,
-  ): Promise<void> {
+  ): Promise<WorkloadBatchOutcome> {
     const items = Array.isArray(payload?.items) ? payload.items : [];
-    if (items.length === 0) return;
+    const total = items.length;
+    let failedCount = 0;
+    const outcome = (): WorkloadBatchOutcome => ({
+      cancelled: run.cancelled,
+      failedCount,
+      total,
+    });
+    if (items.length === 0) return outcome();
 
     const budgetMs = typeof payload.budgetMs === 'number' && payload.budgetMs > 0 ? payload.budgetMs : null;
     const batchStart = Date.now();
     const phase = payload.phase;
+    const containerEnv = normalizeContainerEnv(payload.env);
+    const secrets = collectSecretValues(process.env, containerEnv);
 
     for (const item of items) {
-      if (run.cancelled) return;
+      if (run.cancelled) return outcome();
 
       // 必须项短路（省时优化，服务端仍为唯一裁决）：init 阶段的必须项失败/超时后，
       // 上报本条结果即结束本批，不再启动后续条目。post 批次不参与必须判定。
       const shortCircuitOnFailure = phase === 'init' && item.required === true;
       const reportThenMaybeStop = (result: WorkloadResult): boolean => {
-        this.report(onResult, result);
+        if (result.status !== 'success') failedCount += 1;
+        const redactedLog = redactSecrets(result.log, secrets);
+        this.report(onResult, redactedLog === result.log ? result : { ...result, log: redactedLog });
         return shortCircuitOnFailure && (result.status === 'failed' || result.status === 'timeout');
       };
 
@@ -251,21 +328,22 @@ export class WorkloadExecutor {
         const remaining = budgetMs - (Date.now() - batchStart);
         if (remaining <= 0) {
           // 预算耗尽：后续条目不再启动进程，直接回报 timeout
-          if (reportThenMaybeStop(this.emptyResult(item.logId, 'timeout', ''))) return;
+          if (reportThenMaybeStop(this.emptyResult(item.logId, 'timeout', ''))) return outcome();
           continue;
         }
         effectiveTimeoutMs = Math.min(item.timeoutMs, remaining);
       }
 
       if (!item.script || item.script.trim().length === 0) {
-        if (reportThenMaybeStop(this.emptyResult(item.logId, 'failed', EMPTY_SCRIPT_MESSAGE))) return;
+        if (reportThenMaybeStop(this.emptyResult(item.logId, 'failed', EMPTY_SCRIPT_MESSAGE))) return outcome();
         continue;
       }
 
-      const outcome = await this.executeItem(item, effectiveTimeoutMs, run);
-      if (outcome.cancelled) return;
-      if (outcome.result && reportThenMaybeStop(outcome.result)) return;
+      const itemOutcome = await this.executeItem(item, effectiveTimeoutMs, run, containerEnv);
+      if (itemOutcome.cancelled) return outcome();
+      if (itemOutcome.result && reportThenMaybeStop(itemOutcome.result)) return outcome();
     }
+    return outcome();
   }
 
   private report(onResult: WorkloadResultSink, result: WorkloadResult): void {
@@ -281,7 +359,12 @@ export class WorkloadExecutor {
     return { logId, status, exitCode: null, log, startedAt: now, finishedAt: now };
   }
 
-  private executeItem(item: WorkloadItem, timeoutMs: number, run: ActiveRun): Promise<ItemOutcome> {
+  private executeItem(
+    item: WorkloadItem,
+    timeoutMs: number,
+    run: ActiveRun,
+    containerEnv: Record<string, string>,
+  ): Promise<ItemOutcome> {
     return new Promise<ItemOutcome>((resolve) => {
       if (run.cancelled) {
         resolve({ cancelled: true });
@@ -294,7 +377,7 @@ export class WorkloadExecutor {
         child = spawn('bash', ['-c', item.script], {
           cwd: homedir(),
           detached: true,
-          env: buildWorkloadEnv(item.params),
+          env: buildWorkloadEnv(item.params, containerEnv),
         });
       } catch (error) {
         resolve({

package/tests/commands/harness.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Command } from 'commander';
+import { registerHarnessCommands } from '../../src/commands/harness.js';
+import type { HarnessPrepareResult } from '../../src/harness/prepare.js';
+
+function buildProgram(deps: Parameters<typeof registerHarnessCommands>[1] = {}) {
+  const program = new Command();
+  program.name('agent-gear').exitOverride();
+  registerHarnessCommands(program, deps);
+  return program;
+}
+
+const SUCCESS_RESULT: HarnessPrepareResult = {
+  opencodeVersion: '1.2.3',
+  env: {
+    modelBaseUrl: 'http://admin-api:8002/v1',
+    defaultWorkspace: '/root/workspace',
+    modelCount: 2,
+  },
+  config: {
+    path: '/root/.config/opencode/opencode.jsonc',
+    created: true,
+    modelCount: 2,
+  },
+};
+
+describe('agent-gear harness command (T-AG15)', () => {
+  const originalExitCode = process.exitCode;
+
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    process.exitCode = undefined;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.exitCode = originalExitCode;
+    delete process.env.ZAG_MODEL_API_KEY;
+  });
+
+  it('shows prepare in `agent-gear harness --help`', async () => {
+    let output = '';
+    const program = buildProgram();
+    program.configureOutput({ writeOut: (text) => { output += text; }, writeErr: () => {} });
+
+    await program.parseAsync(['node', 'agent-gear', 'harness', '--help']).catch(() => {});
+
+    expect(output).toContain('prepare');
+  });
+
+  it('rejects unknown subcommands with a non-zero exit code', async () => {
+    const program = buildProgram();
+    program.configureOutput({ writeOut: () => {}, writeErr: () => {} });
+
+    await expect(
+      program.parseAsync(['node', 'agent-gear', 'harness', 'bogus']),
+    ).rejects.toMatchObject({ exitCode: 1 });
+  });
+
+  it('prints a secret-free summary on success', async () => {
+    const prepare = vi.fn(async () => SUCCESS_RESULT);
+    const program = buildProgram({ prepare });
+
+    await program.parseAsync(['node', 'agent-gear', 'harness', 'prepare']);
+
+    expect(prepare).toHaveBeenCalledTimes(1);
+    expect(process.exitCode).toBeUndefined();
+    const output = vi.mocked(console.log).mock.calls.flat().join(' ');
+    expect(output).toContain('OpenCode harness prepared');
+    expect(output).toContain('version=1.2.3');
+    expect(output).not.toContain('zag_sk_');
+  });
+
+  it('exits non-zero and redacts secrets when prepare fails', async () => {
+    process.env.ZAG_MODEL_API_KEY = 'zag_sk_super_secret';
+    const prepare = vi.fn(async () => {
+      throw new Error('failed with key zag_sk_super_secret');
+    });
+    const program = buildProgram({ prepare });
+
+    await program.parseAsync(['node', 'agent-gear', 'harness', 'prepare']);
+
+    expect(process.exitCode).toBe(1);
+    const errors = vi.mocked(console.error).mock.calls.flat().join(' ');
+    expect(errors).toContain('harness prepare failed');
+    expect(errors).not.toContain('zag_sk_super_secret');
+    expect(errors).toContain('***');
+  });
+});

package/tests/socketio-client.test.ts

@@ -229,7 +229,7 @@ describe('SocketIO Client', () => {
       expect(mockSocket.emit).toHaveBeenCalledWith('register', {
         key: 'zag_k_1_abc123',
         hostname: 'my-machine',
-        version: '2.4.0',
+        version: '2.5.0',
         resumeToken: undefined,
         homeDir: '/home/user',
         platform: 'linux',
@@ -247,7 +247,7 @@ describe('SocketIO Client', () => {
       expect(mockSocket.emit).toHaveBeenCalledWith('register', {
         key: 'zag_k_1_abc123',
         hostname: 'test-machine',
-        version: '2.4.0',
+        version: '2.5.0',
         resumeToken: undefined,
         homeDir: '/home/user',
         platform: 'linux',
@@ -328,6 +328,144 @@ describe('SocketIO Client', () => {
 
       expect(console.error).toHaveBeenCalledWith('Connection error: connection failed');
     });
+
+    it('T-AG16: uses an explicit handshake token instead of the key (controller-api standard connection)', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('wss://controller.example.com', 'zag_k_1_host_key', {
+        handshakeToken: 'zag_k_1_host_key',
+      });
+
+      expect(io).toHaveBeenCalledWith('wss://controller.example.com', expect.objectContaining({
+        auth: { token: 'zag_k_1_host_key' },
+      }));
+    });
+
+    it('T-AG16b: never puts the host key into the URL/query and supports handshakeToken=false', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('wss://controller.example.com?token=leaked', 'zag_k_1_host_key', {
+        handshakeToken: false,
+      });
+
+      expect(io).toHaveBeenCalledWith(expect.not.stringContaining('token='), expect.objectContaining({ auth: {} }));
+    });
+
+    it('T-AG3: forwards the full registered payload (including initializing) to onRegistered', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      const onRegistered = vi.fn();
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', { onRegistered });
+      mockSocket._trigger('registered', { controllerId: 'ctrl-1', initializing: true });
+
+      expect(onRegistered).toHaveBeenCalledWith({ controllerId: 'ctrl-1', initializing: true });
+    });
+
+    it('T-AG4: invokes onWorkloadBatchComplete after an init batch ends', async () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      const onWorkloadBatchComplete = vi.fn();
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', { onWorkloadBatchComplete });
+      mockSocket._trigger('workload:run', {
+        phase: 'init',
+        // 空脚本立即产生失败结果（不需要真实 spawn），用于锚定「批次结束即回调且摘要反映失败」
+        items: [{ logId: 'init-1', workloadName: 'Init', script: '', timeoutMs: 5000 }],
+      });
+
+      await vi.waitFor(() => {
+        expect(mockSocket.emit).toHaveBeenCalledWith('workload:result', expect.objectContaining({ logId: 'init-1' }));
+        expect(onWorkloadBatchComplete).toHaveBeenCalledWith({
+          phase: 'init',
+          itemCount: 1,
+          status: 'failed',
+          cancelled: false,
+          failedCount: 1,
+        });
+      });
+    });
+
+    it('T-AG4b: invokes onWorkloadBatchComplete even when a required init item fails', async () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      const onWorkloadBatchComplete = vi.fn();
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', { onWorkloadBatchComplete });
+      mockSocket._trigger('workload:run', {
+        phase: 'init',
+        items: [{ logId: 'init-fail', workloadName: 'Fail', script: '', timeoutMs: 5000, required: true }],
+      });
+
+      await vi.waitFor(() => {
+        expect(onWorkloadBatchComplete).toHaveBeenCalledWith({
+          phase: 'init',
+          itemCount: 1,
+          status: 'failed',
+          cancelled: false,
+          failedCount: 1,
+        });
+      });
+    });
+
+    it('T-AG18: skips the local MCP server when skipLocalMcpStart is set (dual connection singleton)', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', { skipLocalMcpStart: true });
+
+      expect(localServerInstances).toHaveLength(0);
+    });
+
+    it('T-AG17: delegates shutdown to onShutdown without clearing local config or exiting', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      const onShutdown = vi.fn();
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', { onShutdown });
+      mockSocket._trigger('shutdown', { reason: 'container destroyed' });
+
+      expect(onShutdown).toHaveBeenCalledWith({ reason: 'container destroyed' });
+      expect(clearConfigKey).not.toHaveBeenCalled();
+      expect(process.exit).not.toHaveBeenCalled();
+    });
+
+    it('T-AG16c: does not handle workload events when handleWorkload=false', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      const onWorkloadBatchComplete = vi.fn();
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123', {
+        handleWorkload: false,
+        onWorkloadBatchComplete,
+      });
+      mockSocket._trigger('connect');
+      mockSocket._trigger('workload:run', {
+        phase: 'init',
+        items: [{ logId: 'x', workloadName: 'X', script: 'echo nope', timeoutMs: 5000 }],
+      });
+
+      expect(onWorkloadBatchComplete).not.toHaveBeenCalled();
+      expect(mockSocket.emit).not.toHaveBeenCalledWith('workload:result', expect.anything());
+    });
+
+    it('T-AG13: redacts secret values from invalid workload payload logs', () => {
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+      mockSocket._trigger('workload:run', {
+        phase: 'init',
+        items: 'invalid',
+        env: { ZAG_MODEL_API_KEY: 'zag_sk_super_secret' },
+      });
+
+      expect(warnSpy).toHaveBeenCalledWith(expect.not.stringContaining('zag_sk_super_secret'));
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('***'));
+    });
   });
 
   describe('unregister', () => {