agent-gear 2.1.0 → 2.2.0

package/src/socketio-client.ts

@@ -18,8 +18,13 @@ import { gatewayManager } from './gateway.js';
 import { processRegistry, isProcessAlive } from './acp/process-registry.js';
 import { McpRelay } from './mcp/relay.js';
 import { LocalMcpServer } from './mcp/local-server.js';
+import { WorkloadExecutor, type WorkloadRunPayload } from './workload-executor.js';
 
-const CONTROLLER_VERSION = '2.1.0';
+const CONTROLLER_VERSION = '2.2.0';
+// 进程内全局单实例：工作负载批次严格串行（新批次打断旧批次，见 workload-executor）。
+const workloadExecutor = new WorkloadExecutor();
+// shutdown 到达时若仍有 post 批次在跑，最多等待该时长后退出（契约 §2.8）。
+const SHUTDOWN_WORKLOAD_WAIT_MS = 5000;
 const acpBridges = new Map<string, AcpSessionBridge>();
 const permissionRequestBridge = new Map<string, AcpSessionBridge>();
 const elicitationRequestBridge = new Map<string, AcpSessionBridge>();
@@ -261,6 +266,26 @@ export function stripTokenFromEndpoint(endpoint: string): string {
   }
 }
 
+/**
+ * 展开 Socket.IO 连接错误的底层细节。engine.io 的 TransportError 会携带
+ * `type`/`description`/`context`（例如服务端返回非 101 状态、TLS 失败、协议错误），
+ * 而 `message` 常常只有 "websocket error"，不足以定位问题。
+ */
+export function describeConnectError(err: Error): string {
+  const detail = err as Error & { type?: string; description?: string; context?: unknown };
+  const parts: string[] = [];
+  if (detail.type) parts.push(`type=${detail.type}`);
+  if (detail.description) parts.push(`description=${detail.description}`);
+  if (detail.context !== undefined) {
+    try {
+      parts.push(`context=${JSON.stringify(detail.context)}`);
+    } catch {
+      parts.push('context=<unserializable>');
+    }
+  }
+  return parts.length > 0 ? ` (${parts.join(' ')})` : '';
+}
+
 export function connectToServer(
   endpoint: string,
   key: string,
@@ -310,6 +335,8 @@ export function connectToServer(
       homeDir: homedir(),
       platform: platform(),
     });
+    // 重连重放：将未确认的工作负载执行结果重新上报；服务端按终态幂等忽略（契约 §2.9）。
+    workloadExecutor.replayPendingResults((result) => socket.emit('workload:result', result));
   });
 
   socket.on('registered', (data: RegisteredPayload) => {
@@ -351,10 +378,32 @@ export function connectToServer(
 
   socket.on('shutdown', (data: ShutdownPayload) => {
     console.log(`Shutdown requested: ${data.reason}`);
-    heartbeat.stop();
-    clearConfigKey();
-    socket.close();
-    process.exit(0);
+    const finishShutdown = (): void => {
+      heartbeat.stop();
+      clearConfigKey();
+      socket.close();
+      process.exit(0);
+    };
+    // post 批次仍在执行时，等待其结束（≤5s）后再退出，避免清理脚本被中途打断。
+    // 无批次在跑时保持同步退出，行为与现状完全一致。
+    if (workloadExecutor.isRunning()) {
+      workloadExecutor.waitForIdle(SHUTDOWN_WORKLOAD_WAIT_MS).then(finishShutdown);
+    } else {
+      finishShutdown();
+    }
+  });
+
+  // Workload events
+  socket.on('workload:run', (data: WorkloadRunPayload) => {
+    if (!data || !Array.isArray(data.items)) {
+      console.warn(`[Workload] workload:run ignored: invalid payload ${JSON.stringify(data)}`);
+      return;
+    }
+    const budget = typeof data.budgetMs === 'number' ? ` budgetMs=${data.budgetMs}` : '';
+    console.log(`[Workload] workload:run received: phase=${data.phase} items=${data.items.length}${budget}`);
+    workloadExecutor.runBatch(data, (result) => socket.emit('workload:result', result)).catch((error: Error) => {
+      console.error(`[Workload] batch execution failed: ${error.message}`);
+    });
   });
 
   // ACP events
@@ -1144,7 +1193,9 @@ export function connectToServer(
   });
 
   socket.on('connect_error', (err) => {
-    console.error(`Connection error: ${err.message}`);
+    // 传输层失败时 err.message 往往只有笼统的 "websocket error"，真实原因在 description/context
+    // （如 HTTP 404/502、TLS 失败、协议错误）里——一并打印，避免"看不出为何连不上"。
+    console.error(`Connection error: ${err.message}${describeConnectError(err)}`);
   });
 
   return socket;

package/src/workload-executor.test.ts

@@ -0,0 +1,296 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdtemp, mkdir, rm, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import {
+  WorkloadExecutor,
+  MAX_OUTPUT_BYTES,
+  MAX_PENDING_RESULTS,
+  EMPTY_SCRIPT_MESSAGE,
+  type WorkloadResult,
+} from './workload-executor.js';
+
+const TMP_BASE = '/tmp/opencode';
+
+function collect() {
+  const results: WorkloadResult[] = [];
+  return { results, sink: (result: WorkloadResult) => results.push(result) };
+}
+
+async function makeTmpDir(): Promise<string> {
+  await mkdir(TMP_BASE, { recursive: true });
+  return mkdtemp(join(TMP_BASE, 'we-'));
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('WorkloadExecutor', () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it('T-WE1 runs items serially, merges stdout+stderr and reports success in item order', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'a', workloadName: 'A', script: 'echo out-a; echo err-a >&2', timeoutMs: 5000 },
+          { logId: 'b', workloadName: 'B', script: 'echo out-b', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results.map((r) => r.logId)).toEqual(['a', 'b']);
+    expect(results[0]).toMatchObject({ status: 'success', exitCode: 0 });
+    expect(results[0].log).toContain('out-a');
+    expect(results[0].log).toContain('err-a');
+    expect(results[1]).toMatchObject({ status: 'success', exitCode: 0 });
+    expect(results[1].log).toContain('out-b');
+    expect(results[0].startedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(results[0].finishedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it('T-WE2 reports failed with exitCode on non-zero exit and continues the batch', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'fail', workloadName: 'F', script: 'echo boom >&2; exit 3', timeoutMs: 5000 },
+          { logId: 'ok', workloadName: 'O', script: 'echo ok', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+
+    expect(results[0]).toMatchObject({ logId: 'fail', status: 'failed', exitCode: 3 });
+    expect(results[0].log).toContain('boom');
+    expect(results[1]).toMatchObject({ logId: 'ok', status: 'success' });
+  });
+
+  it('T-WE3 kills the whole process group on per-item timeout and continues', async () => {
+    const dir = await makeTmpDir();
+    dirs.push(dir);
+    const marker = join(dir, 'leaked.txt');
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    const started = Date.now();
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'slow', workloadName: 'S', script: `( sleep 1.5; echo leaked > ${marker} ) & sleep 30`, timeoutMs: 300 },
+          { logId: 'next', workloadName: 'N', script: 'echo next', timeoutMs: 5000 },
+        ],
+      },
+      sink,
+    );
+    const elapsed = Date.now() - started;
+
+    expect(elapsed).toBeLessThan(5000);
+    expect(results[0]).toMatchObject({ logId: 'slow', status: 'timeout', exitCode: null });
+    expect(results[1]).toMatchObject({ logId: 'next', status: 'success' });
+
+    // the backgrounded child would write the marker at 1.5s if the group was not killed
+    await delay(2000);
+    expect(await fileExists(marker)).toBe(false);
+  }, 15000);
+
+  it('T-WE4 truncates oversized output keeping the tail <= 256 KiB', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [{ logId: 'big', workloadName: 'Big', script: "yes A | head -c 300000; printf 'ENDMARK'", timeoutMs: 10000 }],
+      },
+      sink,
+    );
+
+    expect(results).toHaveLength(1);
+    expect(results[0].status).toBe('success');
+    expect(Buffer.byteLength(results[0].log, 'utf8')).toBeLessThanOrEqual(MAX_OUTPUT_BYTES);
+    expect(results[0].log.endsWith('ENDMARK')).toBe(true);
+  }, 15000);
+
+  it('T-WE4b: skips a leading split UTF-8 continuation byte when truncating the tail', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    // 总长 262145 字节（3 字节「中」+ 262142 个 A），尾部保留 262144 字节 => 起点落在
+    // 「中」的第 2 个字节（续字节）上；截断后必须跳过续字节到字符边界，首字符不得是乱码。
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          {
+            logId: 'utf8',
+            workloadName: 'Utf8',
+            script: "printf '中'; head -c 262142 /dev/zero | tr '\\0' 'A'",
+            timeoutMs: 10000,
+          },
+        ],
+      },
+      sink,
+    );
+
+    expect(results).toHaveLength(1);
+    const log = results[0].log;
+    expect(log.includes('\uFFFD')).toBe(false);
+    expect(log).toBe('A'.repeat(262142));
+    expect(Buffer.byteLength(log, 'utf8')).toBeLessThanOrEqual(MAX_OUTPUT_BYTES);
+  }, 15000);
+
+  it('T-WE5 shares the post budget and reports timeout without starting later items', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    const started = Date.now();
+    await executor.runBatch(
+      {
+        phase: 'post',
+        budgetMs: 300,
+        items: [
+          { logId: 'p1', workloadName: 'P1', script: 'sleep 2', timeoutMs: 10000 },
+          { logId: 'p2', workloadName: 'P2', script: 'echo should-not-run', timeoutMs: 10000 },
+        ],
+      },
+      sink,
+    );
+    const elapsed = Date.now() - started;
+
+    expect(elapsed).toBeLessThan(5000);
+    expect(results.map((r) => r.logId)).toEqual(['p1', 'p2']);
+    expect(results[0]).toMatchObject({ status: 'timeout', exitCode: null });
+    expect(results[1]).toMatchObject({ status: 'timeout', exitCode: null });
+    expect(results[1].log).not.toContain('should-not-run');
+  }, 15000);
+
+  it('T-WE6 buffers unconfirmed results and replays then clears on reconnect', async () => {
+    const executor = new WorkloadExecutor();
+
+    await executor.runBatch(
+      {
+        phase: 'init',
+        items: [
+          { logId: 'r1', workloadName: 'R1', script: 'echo one', timeoutMs: 5000 },
+          { logId: 'r2', workloadName: 'R2', script: 'echo two', timeoutMs: 5000 },
+        ],
+      },
+      () => {},
+    );
+
+    expect(executor.getPendingResults().map((r) => r.logId)).toEqual(['r1', 'r2']);
+
+    const replayed: WorkloadResult[] = [];
+    executor.replayPendingResults((result) => replayed.push(result));
+
+    expect(replayed.map((r) => r.logId)).toEqual(['r1', 'r2']);
+    expect(executor.getPendingResults()).toHaveLength(0);
+  });
+
+  it('T-WE6b caps the replay buffer at 50 results', async () => {
+    const executor = new WorkloadExecutor();
+    const items = Array.from({ length: MAX_PENDING_RESULTS + 5 }, (_, i) => ({
+      logId: `x${i}`,
+      workloadName: `X${i}`,
+      script: ':',
+      timeoutMs: 5000,
+    }));
+
+    await executor.runBatch({ phase: 'init', items }, () => {});
+
+    const pending = executor.getPendingResults();
+    expect(pending).toHaveLength(MAX_PENDING_RESULTS);
+    expect(pending[pending.length - 1].logId).toBe(`x${MAX_PENDING_RESULTS + 4}`);
+  }, 30000);
+
+  it('T-WE7 terminates the running init batch when a new post batch arrives', async () => {
+    const dir = await makeTmpDir();
+    dirs.push(dir);
+    const startedFile = join(dir, 'init-started');
+    const executor = new WorkloadExecutor();
+
+    const initResults: WorkloadResult[] = [];
+    const initBatch = executor.runBatch(
+      {
+        phase: 'init',
+        items: [{ logId: 'init-1', workloadName: 'Init', script: `touch ${startedFile}; sleep 30`, timeoutMs: 60000 }],
+      },
+      (result) => initResults.push(result),
+    );
+
+    // wait until the init child process has actually started
+    const deadline = Date.now() + 5000;
+    let startedFlag = false;
+    while (Date.now() < deadline) {
+      if (await fileExists(startedFile)) {
+        startedFlag = true;
+        break;
+      }
+      await delay(25);
+    }
+    expect(startedFlag).toBe(true);
+
+    const postResults: WorkloadResult[] = [];
+    await executor.runBatch(
+      { phase: 'post', items: [{ logId: 'post-1', workloadName: 'Post', script: 'echo post-ok', timeoutMs: 5000 }] },
+      (result) => postResults.push(result),
+    );
+    await initBatch;
+
+    expect(postResults.map((r) => r.logId)).toEqual(['post-1']);
+    expect(postResults[0].status).toBe('success');
+    // the interrupted init item is not reported; the server marks it TIMEOUT
+    expect(initResults).toHaveLength(0);
+  }, 20000);
+
+  it('T-WE8 reports failed for an empty script and does nothing for empty items', async () => {
+    const executor = new WorkloadExecutor();
+    const { results, sink } = collect();
+
+    await executor.runBatch(
+      { phase: 'init', items: [{ logId: 'empty', workloadName: 'Empty', script: '   ', timeoutMs: 5000 }] },
+      sink,
+    );
+
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({ logId: 'empty', status: 'failed', exitCode: null, log: EMPTY_SCRIPT_MESSAGE });
+
+    const empty = collect();
+    await executor.runBatch({ phase: 'init', items: [] }, empty.sink);
+    expect(empty.results).toHaveLength(0);
+  });
+
+  it('T-WE9 exposes running state and waitForIdle resolves after the batch completes', async () => {
+    const executor = new WorkloadExecutor();
+    expect(executor.isRunning()).toBe(false);
+
+    const batch = executor.runBatch(
+      { phase: 'post', items: [{ logId: 'w', workloadName: 'W', script: 'sleep 0.4', timeoutMs: 5000 }] },
+      () => {},
+    );
+    expect(executor.isRunning()).toBe(true);
+
+    await executor.waitForIdle(2000);
+    expect(executor.isRunning()).toBe(false);
+    await batch;
+  }, 10000);
+});