@ct-agents/worker 0.0.1

package/src/sandbox/docker.ts

@@ -0,0 +1,587 @@
+import { Buffer } from 'node:buffer';
+import { posix } from 'node:path';
+import { Writable } from 'node:stream';
+import type {
+  ExecResult,
+  Sandbox,
+  SandboxHandle,
+} from '@ct-agents/protocol';
+
+type DockerContainer = {
+  id?: string;
+  start(): Promise<unknown>;
+  exec(options: DockerExecCreateOptions): Promise<DockerExec>;
+  remove(options?: { force?: boolean; v?: boolean }): Promise<unknown>;
+};
+
+type DockerExec = {
+  start(options?: { hijack?: boolean; stdin?: boolean }): Promise<DockerReadableStream>;
+  inspect(): Promise<{ ExitCode?: number | null; Running?: boolean }>;
+};
+
+type DockerReadableStream = NodeJS.ReadableStream & {
+  destroy?: () => void;
+};
+
+type DockerClient = {
+  createContainer(options: DockerCreateContainerOptions): Promise<DockerContainer>;
+  listContainers?(options?: { all?: boolean; filters?: Record<string, string[]> }): Promise<Array<{ Id?: string; id?: string }>>;
+  getContainer?(id: string): Pick<DockerContainer, 'remove'>;
+};
+
+type DockerExecCreateOptions = {
+  Cmd: string[];
+  AttachStdout: boolean;
+  AttachStderr: boolean;
+  Tty: boolean;
+  User?: string;
+  WorkingDir?: string;
+};
+
+type DockerCreateContainerOptions = {
+  Image: string;
+  name?: string;
+  User: string;
+  WorkingDir: string;
+  Cmd: string[];
+  Tty: boolean;
+  OpenStdin: boolean;
+  NetworkDisabled: boolean;
+  Labels: Record<string, string>;
+  HostConfig: {
+    Runtime?: string;
+    CapDrop: string[];
+    SecurityOpt: string[];
+    ReadonlyRootfs: boolean;
+    NetworkMode: 'none';
+    AutoRemove: boolean;
+    CpuQuota?: number;
+    Memory?: number;
+    PidsLimit?: number;
+    Tmpfs: Record<string, string>;
+  };
+};
+
+export type DockerSandboxRuntime = 'runsc' | 'runc';
+
+export type DockerSandboxOptions = {
+  docker: DockerClient;
+  image: string;
+  runtime?: DockerSandboxRuntime;
+  ownerId?: string;
+  nodeEnv?: string;
+  user?: string;
+  workspaceDir?: string;
+  tmpSize?: string;
+  workspaceSize?: string;
+  cpuQuota?: number;
+  memoryBytes?: number;
+  pidsLimit?: number;
+  defaultMaxOutputBytes?: number;
+  defaultFileTimeoutMs?: number;
+};
+
+export type CreateDockerSandboxOptions = Omit<DockerSandboxOptions, 'runtime'> & {
+  useGvisor?: boolean;
+};
+
+export class DockerSandbox implements Sandbox {
+  readonly kind = 'docker' as const;
+  readonly isolated: boolean;
+  private readonly runtime: DockerSandboxRuntime;
+  private readonly ownerId: string;
+  private readonly user: string;
+  private readonly workspaceDir: string;
+  private readonly tmpSize: string;
+  private readonly workspaceSize: string;
+  private readonly defaultMaxOutputBytes: number;
+  private readonly defaultFileTimeoutMs: number;
+
+  constructor(private readonly options: DockerSandboxOptions) {
+    this.runtime = options.runtime ?? 'runsc';
+    this.isolated = this.runtime === 'runsc';
+    this.ownerId = options.ownerId?.trim() || process.env.CT_AGENTS_SANDBOX_OWNER_ID?.trim() || `pid-${process.pid}`;
+    this.user = options.user ?? '1000:1000';
+    this.workspaceDir = options.workspaceDir ?? '/workspace';
+    this.tmpSize = options.tmpSize ?? '64m';
+    this.workspaceSize = options.workspaceSize ?? '256m';
+    this.defaultMaxOutputBytes = normalizePositiveInteger(options.defaultMaxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES);
+    this.defaultFileTimeoutMs = normalizePositiveInteger(options.defaultFileTimeoutMs, DEFAULT_FILE_TIMEOUT_MS);
+
+    if ((options.nodeEnv ?? process.env.NODE_ENV) === 'production' && !this.isolated) {
+      throw new Error('production 环境必须使用隔离 sandbox runtime');
+    }
+  }
+
+  async launch(input: { sessionId: string }): Promise<SandboxHandle> {
+    const safeSessionId = sanitizeDockerName(input.sessionId);
+    const container = await this.options.docker.createContainer({
+      Image: this.options.image,
+      name: `ct-agents-sandbox-${safeSessionId}`,
+      User: this.user,
+      WorkingDir: this.workspaceDir,
+      Cmd: ['sleep', 'infinity'],
+      Tty: false,
+      OpenStdin: false,
+      NetworkDisabled: true,
+      Labels: {
+        'ct-agents.sandbox': 'true',
+        'ct-agents.sandbox.owner': this.ownerId,
+        'ct-agents.session-id': safeSessionId,
+      },
+      HostConfig: {
+        ...(this.runtime === 'runsc' ? { Runtime: 'runsc' } : {}),
+        CapDrop: ['ALL'],
+        SecurityOpt: ['no-new-privileges'],
+        ReadonlyRootfs: true,
+        NetworkMode: 'none',
+        AutoRemove: false,
+        CpuQuota: this.options.cpuQuota ?? DEFAULT_CPU_QUOTA,
+        Memory: this.options.memoryBytes ?? DEFAULT_MEMORY_BYTES,
+        PidsLimit: this.options.pidsLimit ?? DEFAULT_PIDS_LIMIT,
+        Tmpfs: {
+          '/tmp': `rw,noexec,nosuid,nodev,size=${this.tmpSize}`,
+          [this.workspaceDir]: `rw,nosuid,nodev,size=${this.workspaceSize}`,
+        },
+      },
+    });
+    try {
+      await container.start();
+    } catch (error) {
+      await container.remove({ force: true, v: true }).catch(() => undefined);
+      throw error;
+    }
+    return new DockerSandboxHandle(input.sessionId, this.workspaceDir, container, this.user, this.defaultMaxOutputBytes, this.defaultFileTimeoutMs, this.isolated);
+  }
+
+  async reapOrphanedContainers(): Promise<number> {
+    if (!this.options.docker.listContainers || !this.options.docker.getContainer) {
+      return 0;
+    }
+
+    const containers = await this.options.docker.listContainers({
+      all: true,
+      filters: {
+        label: ['ct-agents.sandbox=true', `ct-agents.sandbox.owner=${this.ownerId}`],
+      },
+    });
+    let removed = 0;
+    for (const containerInfo of containers) {
+      const id = containerInfo.Id ?? containerInfo.id;
+      if (!id) {
+        continue;
+      }
+      await this.options.docker.getContainer(id).remove({ force: true, v: true });
+      removed += 1;
+    }
+    return removed;
+  }
+}
+
+const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+const DEFAULT_FILE_TIMEOUT_MS = 30_000;
+const DEFAULT_CPU_QUOTA = 100_000;
+const DEFAULT_MEMORY_BYTES = 512 * 1024 * 1024;
+const DEFAULT_PIDS_LIMIT = 128;
+
+export function createDockerSandbox(options: CreateDockerSandboxOptions): DockerSandbox {
+  return new DockerSandbox({
+    ...options,
+    runtime: options.useGvisor === false ? 'runc' : 'runsc',
+  });
+}
+
+export async function createDockerSandboxFromDockerode(options: Omit<CreateDockerSandboxOptions, 'docker'>): Promise<DockerSandbox> {
+  const Docker = await import('dockerode');
+  const docker = new Docker.default({ socketPath: '/var/run/docker.sock' }) as DockerClient;
+  return createDockerSandbox({ ...options, docker });
+}
+
+class DockerSandboxHandle implements SandboxHandle {
+  readonly isolated: boolean;
+
+  constructor(
+    readonly sessionId: string,
+    readonly workspaceRoot: string,
+    private readonly container: DockerContainer,
+    private readonly user: string,
+    private readonly defaultMaxOutputBytes: number,
+    private readonly defaultFileTimeoutMs: number,
+    isolated = true,
+  ) {
+    this.isolated = isolated;
+  }
+
+  async exec(command: string, opts: { timeoutMs?: number; maxOutputBytes?: number } = {}): Promise<ExecResult> {
+    return executeInContainer(this.container, buildExecCommand(command, opts.timeoutMs), {
+      user: this.user,
+      workingDir: this.workspaceRoot,
+      timeoutMs: opts.timeoutMs,
+      maxOutputBytes: opts.maxOutputBytes ?? this.defaultMaxOutputBytes,
+    });
+  }
+
+  async readFile(path: string, opts: { offset?: number; limit?: number; maxBytes?: number } = {}): Promise<string> {
+    const safePath = assertSafeRelativePath(path);
+    const readCommand = buildReadFileCommand(safePath, opts, this.workspaceRoot);
+    const result = await executeInContainer(this.container, buildExecCommand(readCommand.command, this.defaultFileTimeoutMs), {
+      user: this.user,
+      workingDir: this.workspaceRoot,
+      timeoutMs: this.defaultFileTimeoutMs,
+      maxOutputBytes: readCommand.maxOutputBytes ?? this.defaultMaxOutputBytes,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || `读取文件失败：${path}`);
+    }
+    if (result.stdoutTruncated) {
+      throw new Error(`读取文件超过 sandbox 输出上限：${path}`);
+    }
+    return decodeCompleteUtf8(decodeBase64Strict(result.stdout, path));
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const safePath = assertSafeRelativePath(path);
+    const encoded = Buffer.from(content, 'utf8').toString('base64');
+    const parentDir = dirnamePortable(safePath);
+    const fileName = basenamePortable(safePath);
+    const command = [
+      ...buildEnsureWorkspaceDirectoryCommands(parentDir, safePath, this.workspaceRoot),
+      buildWorkspacePathGuard('parent', safePath, this.workspaceRoot, true),
+      `target="$parent"/${shellQuote(fileName)}`,
+      `target_real=$(realpath -m -- "$target")`,
+      buildWorkspacePathGuard('target_real', safePath, this.workspaceRoot, false),
+      `if [ -e "$target" ] || [ -L "$target" ]; then if [ ! -f "$target" ]; then echo ${shellQuote(`路径不是普通文件：${safePath}`)} >&2; exit 126; fi; fi`,
+      `tmp=$(mktemp "$parent"/.ct-agents-write.XXXXXX)`,
+      `trap 'rm -f -- "$tmp"' EXIT`,
+      `printf %s ${shellQuote(encoded)} | base64 -d > "$tmp"`,
+      `mv -fT -- "$tmp" "$target"`,
+      `trap - EXIT`,
+    ].join(' && ');
+    const result = await executeInContainer(this.container, buildExecCommand(command, this.defaultFileTimeoutMs), {
+      user: this.user,
+      workingDir: this.workspaceRoot,
+      timeoutMs: this.defaultFileTimeoutMs,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || `写入文件失败：${path}`);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    await this.container.remove({ force: true, v: true });
+  }
+}
+
+function buildEnsureWorkspaceDirectoryCommands(parentDir: string, originalPath: string, workspaceRoot: string): string[] {
+  const commands = [`parent=${shellQuote(workspaceRoot)}`];
+  if (parentDir === '.') {
+    return commands;
+  }
+
+  for (const segment of parentDir.split('/')) {
+    if (!segment || segment === '.') {
+      continue;
+    }
+    commands.push(`next="$parent"/${shellQuote(segment)}`);
+    commands.push(`if [ -L "$next" ]; then echo ${shellQuote(`路径越界：${originalPath}`)} >&2; exit 126; fi`);
+    commands.push(`if [ -e "$next" ] && [ ! -d "$next" ]; then echo ${shellQuote(`路径不是目录：${originalPath}`)} >&2; exit 126; fi`);
+    commands.push(`mkdir -p -- "$next"`);
+    commands.push(`parent=$(realpath -m -- "$next")`);
+    commands.push(buildWorkspacePathGuard('parent', originalPath, workspaceRoot, true));
+  }
+  return commands;
+}
+
+function decodeBase64Strict(value: string, path: string): Buffer {
+  const normalized = value.replace(/\s+/g, '');
+  if (normalized.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(normalized)) {
+    throw new Error(`读取文件返回了损坏的 base64 内容：${path}`);
+  }
+  return Buffer.from(normalized, 'base64');
+}
+
+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 '';
+}
+
+async function executeInContainer(
+  container: DockerContainer,
+  command: string[],
+  options: { user: string; workingDir: string; timeoutMs?: number; maxOutputBytes?: number },
+): Promise<ExecResult> {
+  const exec = await container.exec({
+    Cmd: command,
+    AttachStdout: true,
+    AttachStderr: true,
+    Tty: false,
+    User: options.user,
+    WorkingDir: options.workingDir,
+  });
+  const stream = await exec.start({ hijack: true, stdin: false });
+  const maxOutputBytes = normalizePositiveInteger(options.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES);
+  const stdout = new BoundedBufferSink(maxOutputBytes);
+  const stderr = new BoundedBufferSink(maxOutputBytes);
+  demuxDockerStream(stream, stdout, stderr, () => stream.destroy?.());
+  let timedOut = false;
+  const timer = options.timeoutMs
+    ? setTimeout(() => {
+        timedOut = true;
+        stream.destroy?.();
+      }, options.timeoutMs)
+    : undefined;
+  await onceEnded(stream);
+  if (timer) {
+    clearTimeout(timer);
+  }
+  const inspected = await exec.inspect();
+  if ((inspected.Running === true || inspected.ExitCode === null || inspected.ExitCode === undefined) && !timedOut) {
+    throw new Error('Docker exec 未完成，无法可靠读取退出码');
+  }
+  const exitCode = inspected.ExitCode ?? 124;
+  const commandTimedOut = timedOut || (options.timeoutMs !== undefined && exitCode === 124);
+  return {
+    stdout: stdout.text(),
+    stderr: stderr.text(),
+    exitCode: commandTimedOut ? 124 : exitCode,
+    timedOut: commandTimedOut,
+    ...(stdout.truncated ? { stdoutTruncated: true, totalStdoutBytes: stdout.totalBytes } : {}),
+    ...(stderr.truncated ? { stderrTruncated: true, totalStderrBytes: stderr.totalBytes } : {}),
+  };
+}
+
+class BoundedBufferSink extends Writable {
+  private readonly chunks: Buffer[] = [];
+  private bufferedBytes = 0;
+  totalBytes = 0;
+  truncated = false;
+
+  constructor(private readonly maxBytes: number) {
+    super();
+  }
+
+  _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    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;
+      }
+    }
+    callback();
+  }
+
+  text(): string {
+    return Buffer.concat(this.chunks).toString('utf8');
+  }
+}
+
+function demuxDockerStream(
+  stream: NodeJS.ReadableStream,
+  stdout: BoundedBufferSink,
+  stderr: BoundedBufferSink,
+  onOutputLimitExceeded: () => void,
+): void {
+  let header = Buffer.alloc(0);
+  let currentStreamType: number | undefined;
+  let remainingPayloadBytes = 0;
+  let flushed = false;
+  let stopped = false;
+  stream.on('data', (chunk: Buffer) => {
+    if (stopped) {
+      return;
+    }
+    let offset = 0;
+    while (offset < chunk.length) {
+      if (remainingPayloadBytes === 0) {
+        const headerBytesNeeded = 8 - header.length;
+        const headerChunk = chunk.subarray(offset, offset + headerBytesNeeded);
+        header = Buffer.concat([header, headerChunk]);
+        offset += headerChunk.byteLength;
+        if (header.length < 8) {
+          break;
+        }
+        currentStreamType = header[0];
+        remainingPayloadBytes = header.readUInt32BE(4);
+        header = Buffer.alloc(0);
+        if (remainingPayloadBytes === 0) {
+          currentStreamType = undefined;
+          continue;
+        }
+      }
+
+      const payloadChunkSize = Math.min(remainingPayloadBytes, chunk.length - offset);
+      const payload = chunk.subarray(offset, offset + payloadChunkSize);
+      if (currentStreamType === 2) {
+        stderr.write(payload);
+      } else {
+        stdout.write(payload);
+      }
+      offset += payloadChunkSize;
+      remainingPayloadBytes -= payloadChunkSize;
+      if (remainingPayloadBytes === 0) {
+        currentStreamType = undefined;
+      }
+
+      if (stdout.truncated || stderr.truncated) {
+        stopped = true;
+        onOutputLimitExceeded();
+        break;
+      }
+    }
+  });
+  const flush = () => {
+    if (flushed) {
+      return;
+    }
+    flushed = true;
+    if (header.length > 0) {
+      stdout.write(header);
+      header = Buffer.alloc(0);
+    }
+    stdout.end();
+    stderr.end();
+  };
+  stream.once('end', flush);
+  stream.once('close', flush);
+}
+
+function onceEnded(stream: NodeJS.ReadableStream): Promise<void> {
+  return new Promise((resolveEnded, reject) => {
+    stream.once('end', resolveEnded);
+    stream.once('close', resolveEnded);
+    stream.once('error', reject);
+  });
+}
+
+function buildExecCommand(command: string, timeoutMs?: number): string[] {
+  if (!timeoutMs) {
+    return ['sh', '-lc', command];
+  }
+
+  return [
+    'timeout',
+    '--kill-after=1s',
+    formatTimeoutSeconds(timeoutMs),
+    'sh',
+    '-lc',
+    command,
+  ];
+}
+
+function formatTimeoutSeconds(timeoutMs: number): string {
+  return `${Math.max(0.001, timeoutMs / 1000)}s`;
+}
+
+function sanitizeDockerName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]/g, '_');
+}
+
+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 buildReadFileCommand(
+  safePath: string,
+  opts: { offset?: number; limit?: number; maxBytes?: number },
+  workspaceRoot: string,
+): { command: string; maxOutputBytes?: number } {
+  const offset = normalizeOptionalNonNegativeInteger(opts.offset);
+  const limit = normalizeOptionalPositiveInteger(opts.limit);
+  const maxBytes = normalizeOptionalPositiveInteger(opts.maxBytes);
+  const readBytes = minDefined(limit, maxBytes);
+  const guard = [
+    `target=$(realpath -m -- ${shellQuote(safePath)})`,
+    buildWorkspacePathGuard('target', safePath, workspaceRoot, false),
+  ].join(' && ');
+  const source = offset === undefined
+    ? 'cat "$target"'
+    : `tail -c +${offset + 1} "$target"`;
+  const limited = readBytes === undefined
+    ? source
+    : `${source} | head -c ${readBytes}`;
+  return {
+    command: `${guard} && ${limited} | base64`,
+    ...(readBytes !== undefined ? { maxOutputBytes: encodedBase64Bytes(readBytes) + 4096 } : {}),
+  };
+}
+
+function buildWorkspacePathGuard(
+  variableName: string,
+  originalPath: string,
+  workspaceRoot: string,
+  allowWorkspaceRoot: boolean,
+): string {
+  const quotedWorkspace = shellQuote(workspaceRoot);
+  const rootCase = allowWorkspaceRoot ? `${quotedWorkspace}|` : '';
+  return `case "$${variableName}" in ${rootCase}${quotedWorkspace}/*) ;; *) echo ${shellQuote(`路径越界：${originalPath}`)} >&2; exit 126 ;; esac`;
+}
+
+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);
+}
+
+function encodedBase64Bytes(rawBytes: number): number {
+  return Math.ceil(rawBytes / 3) * 4;
+}
+
+function assertSafeRelativePath(path: string): string {
+  if (!path || path.startsWith('/') || path.includes('\0')) {
+    throw new Error(`路径越界：${path}`);
+  }
+  const normalized = posix.normalize(path);
+  const segments = normalized.split('/');
+  if (normalized === '.' || normalized.startsWith('../') || segments.includes('..')) {
+    throw new Error(`路径越界：${path}`);
+  }
+  return normalized;
+}
+
+function dirnamePortable(path: string): string {
+  const index = path.lastIndexOf('/');
+  return index <= 0 ? '.' : path.slice(0, index);
+}
+
+function basenamePortable(path: string): string {
+  const index = path.lastIndexOf('/');
+  return index < 0 ? path : path.slice(index + 1);
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/src/sandbox/index.ts

@@ -0,0 +1,5 @@
+export * from './docker.js';
+export * from './local-process.js';
+export * from './manager.js';
+export * from './resources-def.js';
+export * from './resources.js';