agent-gear 2.3.0 → 2.5.0

package/src/workload-executor.test.ts

@@ -7,6 +7,9 @@ import {
   MAX_OUTPUT_BYTES,
   MAX_PENDING_RESULTS,
   EMPTY_SCRIPT_MESSAGE,
+  redactSecrets,
+  collectSecretValues,
+  REDACTED,
   type WorkloadResult,
 } from './workload-executor.js';
 
@@ -439,3 +442,237 @@ describe('WorkloadExecutor', () => {
     await batch;
   }, 10000);
 });
+
+describe('WorkloadExecutor required short-circuit (T-WE-REQ)', () => {
+  it('T-WE-REQ14: a required init item that fails stops subsequent items', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'req', workloadName: 'Req', script: 'exit 3', timeoutMs: 5000, required: true },
+          { logId: 'after', workloadName: 'After', script: 'echo should-not-run', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['req']);
+    expect(results[0].status).toBe('failed');
+    expect(results[0].exitCode).toBe(3);
+  });
+
+  it('T-WE-REQ15: a required item as the last item failing ends the batch normally', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'ok', workloadName: 'Ok', script: 'echo ok', timeoutMs: 5000 },
+          { logId: 'req', workloadName: 'Req', script: 'exit 1', timeoutMs: 5000, required: true },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['ok', 'req']);
+    expect(results.map((r) => r.status)).toEqual(['success', 'failed']);
+  });
+
+  it('T-WE-REQ16: a non-required failure continues subsequent items', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'bad', workloadName: 'Bad', script: 'exit 2', timeoutMs: 5000, required: false },
+          { logId: 'good', workloadName: 'Good', script: 'echo good', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['bad', 'good']);
+    expect(results.map((r) => r.status)).toEqual(['failed', 'success']);
+  });
+
+  it('T-WE-REQ17: missing required field behaves exactly like the legacy executor', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'bad', workloadName: 'Bad', script: 'exit 1', timeoutMs: 5000 },
+          { logId: 'good', workloadName: 'Good', script: 'echo good', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['bad', 'good']);
+    expect(results.map((r) => r.status)).toEqual(['failed', 'success']);
+  });
+
+  it('T-WE-REQ18: a required post item failure does not short-circuit (post is never must)', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'post',
+        items: [
+          { logId: 'bad', workloadName: 'Bad', script: 'exit 1', timeoutMs: 5000, required: true },
+          { logId: 'good', workloadName: 'Good', script: 'echo cleaned', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['bad', 'good']);
+    expect(results.map((r) => r.status)).toEqual(['failed', 'success']);
+  });
+
+  it('T-WE-REQ14: a required init item timing out stops subsequent items', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'req', workloadName: 'Req', script: 'sleep 5', timeoutMs: 300, required: true },
+          { logId: 'after', workloadName: 'After', script: 'echo should-not-run', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['req']);
+    expect(results[0].status).toBe('timeout');
+  }, 10000);
+});
+
+describe('WorkloadExecutor container env + secret redaction (T-AG13/T-AG14)', () => {
+  it('T-AG14: injects container env into every item and lets item params win on WORKLOAD_PARAM_*', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        env: {
+          ZAG_MODEL_IDS: '["model-a","model-b"]',
+          ZAG_DEFAULT_WORKSPACE: '/root/workspace',
+          ZAG_USER_ID: 'user-1',
+          WORKLOAD_PARAM_VERSION: 'from-container-env',
+        },
+        items: [
+          {
+            logId: 'first',
+            workloadName: 'First',
+            script: `printf 'IDS=%s\\n' "$ZAG_MODEL_IDS"; printf 'WS=%s\\n' "$ZAG_DEFAULT_WORKSPACE"; printf 'USER=%s\\n' "$ZAG_USER_ID"; printf 'V=%s\\n' "$WORKLOAD_PARAM_VERSION"`,
+            timeoutMs: 5000,
+            params: { version: 'from-item-param' },
+          },
+          {
+            logId: 'second',
+            workloadName: 'Second',
+            script: `printf 'IDS=%s\\n' "$ZAG_MODEL_IDS"; printf 'V=%s\\n' "$WORKLOAD_PARAM_VERSION"`,
+            timeoutMs: 5000,
+          },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['first', 'second']);
+    expect(results[0].log).toContain('IDS=["model-a","model-b"]');
+    expect(results[0].log).toContain('WS=/root/workspace');
+    expect(results[0].log).toContain('USER=user-1');
+    // item 参数优先于容器 env 的同名 WORKLOAD_PARAM_*
+    expect(results[0].log).toContain('V=from-item-param');
+    expect(results[1].log).toContain('V=from-container-env');
+  });
+
+  it('T-AG14b: keeps legacy behavior when the payload has no container env', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          {
+            logId: 'legacy',
+            workloadName: 'Legacy',
+            script: `printf 'ENV=%s\\n' "\${ZAG_MODEL_IDS-unset}"; printf 'P=%s\\n' "$WORKLOAD_PARAMS"`,
+            timeoutMs: 5000,
+          },
+        ],
+      },
+      sink,
+    );
+
+    expect(results[0].status).toBe('success');
+    expect(results[0].log).toContain('ENV=unset');
+    expect(results[0].log).toContain('P={}');
+  });
+
+  it('T-AG13: redacts secret values from script output (container env + process env)', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+    const previousHostKey = process.env.ZAG_HOST_KEY;
+    process.env.ZAG_HOST_KEY = 'zag_k_process_secret';
+    try {
+      await executor.runBatch(
+        {
+          phase: 'init',
+          env: {
+            ZAG_MODEL_API_KEY: 'zag_sk_container_secret',
+            ZAG_CONTROLLER_KEY: 'controller-token-secret',
+          },
+          items: [
+            {
+              logId: 'leak',
+              workloadName: 'Leak',
+              script: `printf 'A=%s\\n' "$ZAG_MODEL_API_KEY"; printf 'B=%s\\n' "$ZAG_HOST_KEY"; printf 'C=%s\\n' "$ZAG_CONTROLLER_KEY"`,
+              timeoutMs: 5000,
+            },
+          ],
+        },
+        sink,
+      );
+    } finally {
+      if (previousHostKey === undefined) delete process.env.ZAG_HOST_KEY;
+      else process.env.ZAG_HOST_KEY = previousHostKey;
+    }
+
+    expect(results).toHaveLength(1);
+    const log = results[0].log;
+    expect(log).not.toContain('zag_sk_container_secret');
+    expect(log).not.toContain('zag_k_process_secret');
+    expect(log).not.toContain('controller-token-secret');
+    expect(log).toContain(`A=${REDACTED}`);
+    expect(log).toContain(`B=${REDACTED}`);
+    expect(log).toContain(`C=${REDACTED}`);
+  });
+
+  it('T-AG13b: redactSecrets handles multiple secrets and ignores empty values', () => {
+    const secrets = collectSecretValues(
+      { ZAG_MODEL_API_KEY: 'sk-1', ZAG_HOST_KEY: '', ZAG_CONTROLLER_KEY: 'ct-2' },
+      { ZAG_HOST_KEY: 'host-3' },
+    );
+    expect(secrets.sort()).toEqual(['ct-2', 'host-3', 'sk-1'].sort());
+
+    expect(redactSecrets('a sk-1 b ct-2 c host-3 d', secrets)).toBe(`a ${REDACTED} b ${REDACTED} c ${REDACTED} d`);
+    expect(redactSecrets('nothing to hide', secrets)).toBe('nothing to hide');
+  });
+});

package/src/workload-executor.ts

@@ -23,6 +23,11 @@ export interface WorkloadItem {
   script: string;
   /** 本次执行参数，键为参数标识；缺省 `{}`（等价旧行为）。 */
   params?: Record<string, unknown>;
+  /**
+   * 本次启动该条是否为「必须」项（仅 `phase=init` 有意义，缺省/非 true 按非必须）。
+   * 服务端为唯一裁决；worker 仅在该项失败/超时后省去后续无谓执行。
+   */
+  required?: boolean;
   /** 单条脚本超时（毫秒）。 */
   timeoutMs: number;
 }
@@ -34,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';
@@ -107,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;
@@ -118,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)) {
@@ -144,7 +215,8 @@ function buildWorkloadEnv(params: Record<string, unknown> | undefined): NodeJS.P
  * - 按 `items` 顺序**串行**执行 `bash -c <script>`（`cwd=os.homedir()`，继承进程环境并按 item 注入
  *   `WORKLOAD_PARAMS` / `WORKLOAD_PARAM_*`，stdout/stderr 合并捕获）；
  * - 单条超时或收到新批次时终止整个进程组（`detached: true` + `kill(-pid)`）；
- * - 非零退出回报 `failed` + `exitCode`，不影响后续条目；
+ * - 非零退出回报 `failed` + `exitCode`，不影响后续条目；**例外**：`init` 阶段的必须项
+ *   （`item.required === true`）失败/超时后不再启动后续条目（服务端仍会中断剩余记录并注销容器）；
  * - `post` 批次共享 `budgetMs`：剩余预算耗尽时后续条目直接回报 `timeout`（不启动进程）；
  * - 未被服务端确认的结果保存在内存（上限 50 条）供重连重放。
  *
@@ -152,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[] = [];
 
   /** 当前是否有批次正在执行。 */
@@ -201,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 };
@@ -221,36 +293,57 @@ 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 => {
+        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');
+      };
 
       let effectiveTimeoutMs = item.timeoutMs;
       if (budgetMs !== null) {
         const remaining = budgetMs - (Date.now() - batchStart);
         if (remaining <= 0) {
           // 预算耗尽：后续条目不再启动进程，直接回报 timeout
-          this.report(onResult, this.emptyResult(item.logId, 'timeout', ''));
+          if (reportThenMaybeStop(this.emptyResult(item.logId, 'timeout', ''))) return outcome();
           continue;
         }
         effectiveTimeoutMs = Math.min(item.timeoutMs, remaining);
       }
 
       if (!item.script || item.script.trim().length === 0) {
-        this.report(onResult, this.emptyResult(item.logId, 'failed', EMPTY_SCRIPT_MESSAGE));
+        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) this.report(onResult, outcome.result);
+      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 {
@@ -266,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 });
@@ -279,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('***');
+  });
+});