@ct-agents/worker 0.0.1

package/src/sandbox/local-process.ts

@@ -0,0 +1,334 @@
+import { spawn } from 'node:child_process';
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { lstat, mkdir, open, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import type {
+  ExecResult,
+  Sandbox,
+  SandboxHandle,
+} from '@ct-agents/protocol';
+
+export type LocalProcessSandboxOptions = {
+  rootDir?: string;
+  nodeEnv?: string;
+  defaultMaxOutputBytes?: number;
+};
+
+const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+
+export class LocalProcessSandbox implements Sandbox {
+  readonly kind = 'local' as const;
+  readonly isolated = false;
+  private readonly rootDir: string;
+  private readonly defaultMaxOutputBytes: number;
+
+  constructor(options: LocalProcessSandboxOptions = {}) {
+    const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV;
+    if (nodeEnv === 'production') {
+      throw new Error('LocalProcessSandbox 不能在 production 环境启用');
+    }
+    this.rootDir = options.rootDir ?? join(tmpdir(), 'ct-agents-local-sandbox');
+    this.defaultMaxOutputBytes = normalizePositiveInteger(options.defaultMaxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES);
+  }
+
+  async launch(input: { sessionId: string }): Promise<SandboxHandle> {
+    const workspaceRoot = resolve(this.rootDir, sanitizePathSegment(input.sessionId));
+    await mkdir(workspaceRoot, { recursive: true });
+    return new LocalProcessSandboxHandle(input.sessionId, workspaceRoot, this.defaultMaxOutputBytes);
+  }
+}
+
+class LocalProcessSandboxHandle implements SandboxHandle {
+  readonly isolated = false;
+
+  constructor(
+    readonly sessionId: string,
+    readonly workspaceRoot: string,
+    private readonly defaultMaxOutputBytes: number,
+  ) {}
+
+  exec(command: string, opts: { timeoutMs?: number; maxOutputBytes?: number } = {}): Promise<ExecResult> {
+    return new Promise((resolveResult) => {
+      const child = spawn(command, {
+        cwd: this.workspaceRoot,
+        detached: process.platform !== 'win32',
+        shell: true,
+        windowsHide: true,
+      });
+      const stdout = new BoundedOutputBuffer(normalizePositiveInteger(opts.maxOutputBytes, this.defaultMaxOutputBytes));
+      const stderr = new BoundedOutputBuffer(normalizePositiveInteger(opts.maxOutputBytes, this.defaultMaxOutputBytes));
+      let timedOut = false;
+      let settled = false;
+      let outputExceeded = false;
+      let terminationPromise: Promise<void> | undefined;
+      const stopForOutputLimit = () => {
+        if (outputExceeded) {
+          return;
+        }
+        outputExceeded = true;
+        terminationPromise = terminateProcessTree(child);
+      };
+      const timer = opts.timeoutMs
+        ? setTimeout(() => {
+            timedOut = true;
+            terminationPromise = terminateProcessTree(child);
+          }, opts.timeoutMs)
+        : undefined;
+
+      child.stdout.on('data', (chunk: Buffer) => {
+        if (stdout.append(chunk)) {
+          stopForOutputLimit();
+        }
+      });
+      child.stderr.on('data', (chunk: Buffer) => {
+        if (stderr.append(chunk)) {
+          stopForOutputLimit();
+        }
+      });
+      child.on('error', (error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        void (terminationPromise ?? terminateProcessTree(child)).then(() => {
+          const stdoutResult = stdout.result();
+          const stderrResult = stderr.result();
+          resolveResult({
+            stdout: stdoutResult.text,
+            stderr: stderrResult.text || error.message,
+            exitCode: 1,
+            timedOut,
+            ...(stdoutResult.truncated ? { stdoutTruncated: true, totalStdoutBytes: stdoutResult.totalBytes } : {}),
+            ...(stderrResult.truncated ? { stderrTruncated: true, totalStderrBytes: stderrResult.totalBytes } : {}),
+          });
+        });
+      });
+      child.on('close', (code, signal) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        void (terminationPromise ?? Promise.resolve()).then(() => {
+          const stdoutResult = stdout.result();
+          const stderrResult = stderr.result();
+          const exitCode = code ?? (signal ? 1 : 0);
+          resolveResult({
+            stdout: stdoutResult.text,
+            stderr: stderrResult.text,
+            exitCode: (timedOut || outputExceeded) && exitCode === 0 ? 1 : exitCode,
+            timedOut,
+            ...(stdoutResult.truncated ? { stdoutTruncated: true, totalStdoutBytes: stdoutResult.totalBytes } : {}),
+            ...(stderrResult.truncated ? { stderrTruncated: true, totalStderrBytes: stderrResult.totalBytes } : {}),
+          });
+        });
+      });
+    });
+  }
+
+  async readFile(path: string, opts: { offset?: number; limit?: number; maxBytes?: number } = {}): Promise<string> {
+    const target = this.resolveWorkspacePath(path);
+    await this.assertExistingWorkspaceFile(target, path);
+    const maxBytes = normalizeOptionalPositiveInteger(opts.maxBytes);
+    const offset = normalizeOptionalNonNegativeInteger(opts.offset);
+    const limit = normalizeOptionalPositiveInteger(opts.limit);
+    if (maxBytes !== undefined || offset !== undefined || limit !== undefined) {
+      const start = offset ?? 0;
+      const bytesToRead = minDefined(limit, maxBytes);
+      if (bytesToRead === undefined) {
+        const content = await readFile(target);
+        return decodeCompleteUtf8(content.subarray(start));
+      }
+      return readFileRange(target, start, bytesToRead);
+    }
+    return readFile(target, 'utf8');
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const target = this.resolveWorkspacePath(path);
+    await this.assertWritableWorkspacePath(target, path);
+    await writeFile(target, content, 'utf8');
+  }
+
+  async dispose(): Promise<void> {
+    await rm(this.workspaceRoot, { recursive: true, force: true });
+  }
+
+  private resolveWorkspacePath(path: string): string {
+    const target = resolve(this.workspaceRoot, path);
+    const relativePath = relative(this.workspaceRoot, target);
+    if (relativePath === '..' || relativePath.startsWith('..\\') || relativePath.startsWith('../') || isAbsolute(relativePath)) {
+      throw new Error(`路径越界：${path}`);
+    }
+    return target;
+  }
+
+  private async assertExistingWorkspaceFile(target: string, originalPath: string): Promise<void> {
+    const stat = await lstat(target);
+    if (!stat.isFile()) {
+      throw new Error(`路径不是普通文件：${originalPath}`);
+    }
+    await this.assertRealPathInsideWorkspace(target, originalPath);
+  }
+
+  private async assertWritableWorkspacePath(target: string, originalPath: string): Promise<void> {
+    await mkdir(dirname(target), { recursive: true });
+    await this.assertRealPathInsideWorkspace(dirname(target), originalPath);
+    try {
+      const stat = await lstat(target);
+      if (!stat.isFile()) {
+        throw new Error(`路径不是普通文件：${originalPath}`);
+      }
+      await this.assertRealPathInsideWorkspace(target, originalPath);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  private async assertRealPathInsideWorkspace(target: string, originalPath: string): Promise<void> {
+    const [workspaceRealPath, targetRealPath] = await Promise.all([
+      realpath(this.workspaceRoot),
+      realpath(target),
+    ]);
+    const relativePath = relative(workspaceRealPath, targetRealPath);
+    if (relativePath === '..' || relativePath.startsWith('..\\') || relativePath.startsWith('../') || isAbsolute(relativePath)) {
+      throw new Error(`路径越界：${originalPath}`);
+    }
+  }
+}
+
+function sanitizePathSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+class BoundedOutputBuffer {
+  private readonly chunks: Buffer[] = [];
+  private totalBytes = 0;
+  private bufferedBytes = 0;
+  private truncated = false;
+
+  constructor(private readonly maxBytes: number) {}
+
+  append(chunk: Buffer): boolean {
+    this.totalBytes += chunk.byteLength;
+    if (!this.truncated) {
+      const remainingBytes = this.maxBytes - this.bufferedBytes;
+      if (remainingBytes > 0) {
+        const stored = Buffer.from(chunk.subarray(0, remainingBytes));
+        this.chunks.push(stored);
+        this.bufferedBytes += stored.byteLength;
+      }
+      if (chunk.byteLength > remainingBytes) {
+        this.truncated = true;
+      }
+    }
+    return this.truncated;
+  }
+
+  result() {
+    return {
+      text: Buffer.concat(this.chunks).toString('utf8'),
+      truncated: this.truncated,
+      totalBytes: this.totalBytes,
+    };
+  }
+}
+
+function normalizePositiveInteger(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+function normalizeOptionalPositiveInteger(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+function normalizeOptionalNonNegativeInteger(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return Math.max(0, Math.trunc(value));
+}
+
+function minDefined(left: number | undefined, right: number | undefined): number | undefined {
+  if (left === undefined) {
+    return right;
+  }
+  if (right === undefined) {
+    return left;
+  }
+  return Math.min(left, right);
+}
+
+async function readFileRange(path: string, offset: number, maxBytes: number): Promise<string> {
+  if (maxBytes <= 0) {
+    return '';
+  }
+  const handle = await open(path, 'r');
+  try {
+    const buffer = Buffer.allocUnsafe(maxBytes);
+    const result = await handle.read(buffer, 0, maxBytes, offset);
+    return decodeCompleteUtf8(buffer.subarray(0, result.bytesRead));
+  } finally {
+    await handle.close();
+  }
+}
+
+function decodeCompleteUtf8(bytes: Uint8Array): string {
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  for (let end = bytes.byteLength; end >= 0; end -= 1) {
+    try {
+      return decoder.decode(bytes.subarray(0, end));
+    } catch {
+      // 回退到上一个完整 UTF-8 字符边界。
+    }
+  }
+  return '';
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return error !== null
+    && typeof error === 'object'
+    && 'code' in error
+    && (error as { code?: unknown }).code === 'ENOENT';
+}
+
+function terminateProcessTree(child: ChildProcessWithoutNullStreams): Promise<void> {
+  const pid = child.pid;
+  if (!pid) {
+    child.kill();
+    return Promise.resolve();
+  }
+
+  if (process.platform === 'win32') {
+    return new Promise((resolveTaskkill) => {
+      const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      killer.once('error', () => resolveTaskkill());
+      killer.once('close', () => resolveTaskkill());
+    });
+  }
+
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    child.kill('SIGKILL');
+  }
+  return Promise.resolve();
+}

package/src/sandbox/manager.ts

@@ -0,0 +1,141 @@
+import type {
+  Sandbox,
+  SandboxHandle,
+} from '@ct-agents/protocol';
+
+export type SandboxManagerOptions = {
+  sandbox: Sandbox & { reapOrphanedContainers?: () => Promise<number> };
+  now?: () => number;
+  releaseTimeoutMs?: number;
+};
+
+type SandboxEntry = {
+  handlePromise: Promise<SandboxHandle>;
+  lastUsedAt: number;
+  ready: boolean;
+  disposing?: Promise<void>;
+  releaseWait?: Promise<void>;
+};
+
+export class SandboxManager {
+  private readonly entries = new Map<string, SandboxEntry>();
+  private readonly now: () => number;
+  private readonly releaseTimeoutMs: number;
+  private reapPromise: Promise<number> | undefined;
+  private closed = false;
+
+  constructor(private readonly options: SandboxManagerOptions) {
+    this.now = options.now ?? (() => Date.now());
+    this.releaseTimeoutMs = Math.max(1, Math.trunc(options.releaseTimeoutMs ?? 5000));
+  }
+
+  async forSession(input: { sessionId: string }): Promise<SandboxHandle> {
+    if (this.closed) {
+      throw new Error('SandboxManager 已关闭，不能再创建 sandbox');
+    }
+    if (this.options.sandbox.reapOrphanedContainers) {
+      await this.reapOnce();
+    }
+    const currentNow = this.now();
+    let entry = this.entries.get(input.sessionId);
+    if (entry?.disposing) {
+      await entry.disposing;
+      if (this.closed) {
+        throw new Error('SandboxManager 已关闭，不能再创建 sandbox');
+      }
+      entry = this.entries.get(input.sessionId);
+    }
+    if (!entry) {
+      const handlePromise = this.options.sandbox.launch({ sessionId: input.sessionId });
+      const newEntry: SandboxEntry = {
+        handlePromise,
+        lastUsedAt: currentNow,
+        ready: false,
+      };
+      entry = newEntry;
+      this.entries.set(input.sessionId, entry);
+      void handlePromise.then(
+        () => {
+          if (this.entries.get(input.sessionId) === newEntry) {
+            newEntry.ready = true;
+          }
+        },
+        () => {
+          if (this.entries.get(input.sessionId) === newEntry) {
+            this.entries.delete(input.sessionId);
+          }
+        },
+      );
+    }
+    entry.lastUsedAt = currentNow;
+    return entry.handlePromise;
+  }
+
+  async release(sessionId: string): Promise<void> {
+    const entry = this.entries.get(sessionId);
+    if (!entry) {
+      return;
+    }
+    if (!entry.disposing) {
+      entry.disposing = (async () => {
+        try {
+          const handle = await entry.handlePromise.catch(() => null);
+          if (!handle) {
+            return;
+          }
+          await this.disposeHandle(handle);
+        } finally {
+          if (this.entries.get(sessionId) === entry) {
+            this.entries.delete(sessionId);
+          }
+        }
+      })();
+      entry.releaseWait = this.waitForReleaseTimeout(entry.disposing);
+    }
+    await (entry.releaseWait ?? entry.disposing);
+  }
+
+  async sweepIdle(ttlMs: number): Promise<number> {
+    const threshold = this.now() - Math.max(0, Math.trunc(ttlMs));
+    const idleSessionIds = Array.from(this.entries.entries())
+      .filter(([, entry]) => !entry.disposing && entry.ready && entry.lastUsedAt <= threshold)
+      .map(([sessionId]) => sessionId);
+
+    for (const sessionId of idleSessionIds) {
+      await this.release(sessionId);
+    }
+
+    return idleSessionIds.length;
+  }
+
+  async disposeAll(): Promise<void> {
+    this.closed = true;
+    while (this.entries.size > 0) {
+      const sessionIds = Array.from(this.entries.keys());
+      await Promise.all(sessionIds.map((sessionId) => this.release(sessionId).catch(() => undefined)));
+      if (sessionIds.every((sessionId) => this.entries.has(sessionId))) {
+        break;
+      }
+    }
+  }
+
+  private waitForReleaseTimeout(disposing: Promise<void>) {
+    return Promise.race([
+      disposing,
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, this.releaseTimeoutMs);
+      }),
+    ]);
+  }
+
+  private async disposeHandle(handle: SandboxHandle) {
+    await handle.dispose().catch(() => undefined);
+  }
+
+  private async reapOnce() {
+    if (!this.reapPromise) {
+      this.reapPromise = this.options.sandbox.reapOrphanedContainers?.() ?? Promise.resolve(0);
+    }
+    await this.reapPromise;
+  }
+}

package/src/sandbox/resources-def.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type {
+  ResourceDefinition,
+  Sandbox,
+} from '@ct-agents/protocol';
+
+export type SandboxLifecycle = 'session' | 'work-item';
+
+export type SandboxResourceOptions = {
+  allowedCommands?: string[];
+  deniedCommands?: string[];
+  requireApproval?: boolean;
+  timeoutMs?: number;
+  sandboxLifecycle?: SandboxLifecycle;
+  workspaceRoot?: string;
+  readPaths?: string[];
+  writePaths?: string[];
+  limits?: {
+    cpu?: number;
+    memoryMb?: number;
+    processes?: number;
+  };
+};
+
+export const sandboxResourceOptionsSchema = z.object({
+  allowedCommands: z.array(z.string().trim().min(1)).optional(),
+  deniedCommands: z.array(z.string().trim().min(1)).optional(),
+  requireApproval: z.boolean().optional(),
+  timeoutMs: z.number().int().positive().optional(),
+  sandboxLifecycle: z.enum(['session', 'work-item']).optional(),
+  workspaceRoot: z.string().trim().min(1).optional(),
+  readPaths: z.array(z.string().trim().min(1)).optional(),
+  writePaths: z.array(z.string().trim().min(1)).optional(),
+  limits: z.object({
+    cpu: z.number().positive().optional(),
+    memoryMb: z.number().int().positive().optional(),
+    processes: z.number().int().positive().optional(),
+  }).strict().optional(),
+}).strict();
+
+export function createSandboxResourceDefinition(): ResourceDefinition<Sandbox, SandboxResourceOptions> {
+  return {
+    id: 'sandbox',
+    title: 'Sandbox',
+    description: 'worker 侧 sandbox resource 配置声明。实际 sandbox 句柄由 worker 本地配置和 SandboxManager 注入。',
+    implementations: [
+      {
+        id: 'local-process',
+        title: 'Local process',
+        description: '本地开发用 sandbox 声明；生产应替换为隔离实现。',
+        optionsSchema: sandboxResourceOptionsSchema,
+        optionsJsonSchema: z.toJSONSchema(sandboxResourceOptionsSchema),
+        factory: () => {
+          throw new Error('SANDBOX_RESOURCE_DEFINITION_ONLY');
+        },
+      },
+    ],
+  };
+}

package/src/sandbox/resources.ts

@@ -0,0 +1,30 @@
+import type {
+  Database,
+  MemoryResource,
+  ResourceSlots,
+  SandboxHandle,
+  SkillResource,
+  ToolWorkItem,
+} from '@ct-agents/protocol';
+import type { ResolveResources } from '../index.js';
+
+export type CreateSandboxResolveResourcesInput = {
+  manager: {
+    forSession(input: { sessionId: string }): Promise<SandboxHandle>;
+  };
+  database?: Database;
+  skills?: SkillResource;
+  memory?: MemoryResource;
+};
+
+export function createSandboxResolveResources(input: CreateSandboxResolveResourcesInput): ResolveResources {
+  return async (item: ToolWorkItem): Promise<ResourceSlots> => {
+    const sandbox = await input.manager.forSession({ sessionId: item.sessionId });
+    return {
+      sandbox,
+      ...(input.database ? { database: input.database } : {}),
+      ...(input.skills ? { skills: input.skills } : {}),
+      ...(input.memory ? { memory: input.memory } : {}),
+    };
+  };
+}