@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/sandbox/control/native-file-lock.ts

@@ -0,0 +1,209 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+type NativeFsExt = Readonly<{
+  flockSync: (fd: number, flags: string) => void;
+  lockFileExSync: (fd: number, flags: number, offsetLow: number, offsetHigh: number, lengthLow: number, lengthHigh: number) => void;
+  unlockFileExSync: (fd: number, offsetLow: number, offsetHigh: number, lengthLow: number, lengthHigh: number) => void;
+  constants: Readonly<{
+    LOCKFILE_EXCLUSIVE_LOCK: number;
+    LOCKFILE_FAIL_IMMEDIATELY: number;
+  }>;
+  getNativeModuleSource?: () => string;
+}>;
+
+export type SandboxLockCapability = Readonly<{
+  supported: boolean;
+  primitive: 'flock' | 'LockFileEx' | 'unavailable';
+  binarySource: string | null;
+  reason?: string;
+}>;
+
+export type SandboxLockNamespace = Readonly<{
+  lockRoot: string;
+  domainDirectory: string;
+  lockDomain: string;
+  carrierIdentityDigest: string;
+  lockPath: string;
+}>;
+
+export type SandboxResourceLock = Readonly<{
+  path: string;
+  lockDomain: string;
+  release(): void;
+}>;
+
+const require = createRequire(import.meta.url);
+const LOCK_ROOT_NAME = path.join('.agent-infra', 'sandbox-locks');
+
+function loadNative(): NativeFsExt {
+  try {
+    return require('fs-ext-extra-prebuilt') as NativeFsExt;
+  } catch {
+    throw new Error('SANDBOX_LOCK_UNSUPPORTED: native lock module is unavailable');
+  }
+}
+
+function digest(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function assertPrivateDirectory(directory: string, home: string): void {
+  const resolvedHome = path.resolve(home);
+  let current = resolvedHome;
+  const relative = path.relative(resolvedHome, path.resolve(directory));
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock root must be below the user home');
+  }
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (fs.existsSync(current)) {
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace contains a link or non-directory');
+      }
+      if (process.platform !== 'win32' && typeof process.getuid === 'function'
+        && stat.uid !== process.getuid()) {
+        throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace owner mismatch');
+      }
+    } else {
+      try {
+        fs.mkdirSync(current, { mode: 0o700 });
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+          throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace contains a link or non-directory');
+        }
+      }
+    }
+    if (process.platform !== 'win32') fs.chmodSync(current, 0o700);
+  }
+  const real = fs.realpathSync.native(path.resolve(directory));
+  const realRelative = path.relative(fs.realpathSync.native(resolvedHome), real);
+  if (!realRelative || realRelative.startsWith('..') || path.isAbsolute(realRelative)) {
+    throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace realpath escapes the user home');
+  }
+}
+
+export function resolveSandboxLockNamespace(
+  carrierIdentity: string,
+  options: Readonly<{ lockDomain?: string; home?: string }> = {}
+): SandboxLockNamespace {
+  if (!carrierIdentity.trim()) throw new Error('SANDBOX_LOCK_IDENTITY_INVALID');
+  const home = path.resolve(options.home ?? os.homedir());
+  const lockRoot = path.join(home, LOCK_ROOT_NAME);
+  assertPrivateDirectory(lockRoot, home);
+  const primitive = process.platform === 'win32' ? 'LockFileEx' : 'flock';
+  const lockDomain = options.lockDomain ?? digest(`${process.platform}\0${process.arch}\0${primitive}`);
+  if (!/^[a-f0-9]{64}$/u.test(lockDomain)) throw new Error('SANDBOX_LOCK_DOMAIN_INVALID');
+  const domainDirectory = path.join(lockRoot, lockDomain);
+  assertPrivateDirectory(domainDirectory, home);
+  const carrierIdentityDigest = digest(carrierIdentity);
+  return {
+    lockRoot,
+    domainDirectory,
+    lockDomain,
+    carrierIdentityDigest,
+    lockPath: path.join(domainDirectory, `${carrierIdentityDigest}.lock`)
+  };
+}
+
+export function stableSandboxLockPath(
+  carrierIdentity: string,
+  lockDomain?: string,
+  options: Readonly<{ home?: string }> = {}
+): string {
+  return resolveSandboxLockNamespace(carrierIdentity, { lockDomain, home: options.home }).lockPath;
+}
+
+export function probeNativeLockCapability(): SandboxLockCapability {
+  try {
+    const native = loadNative();
+    return {
+      supported: true,
+      primitive: process.platform === 'win32' ? 'LockFileEx' : 'flock',
+      binarySource: native.getNativeModuleSource?.() ?? null
+    };
+  } catch (error) {
+    return {
+      supported: false,
+      primitive: 'unavailable',
+      binarySource: null,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+export function acquireSandboxResourceLock(
+  carrierIdentity: string,
+  options: Readonly<{ lockDomain?: string; home?: string }> = {}
+): SandboxResourceLock {
+  const native = loadNative();
+  const namespace = resolveSandboxLockNamespace(carrierIdentity, options);
+  if (fs.existsSync(namespace.lockPath)) {
+    const existing = fs.lstatSync(namespace.lockPath);
+    if (existing.isSymbolicLink() || !existing.isFile()) {
+      throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock object is not a regular file');
+    }
+    if (process.platform !== 'win32' && typeof process.getuid === 'function'
+      && existing.uid !== process.getuid()) {
+      throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock object owner mismatch');
+    }
+  }
+  let fd: number | undefined;
+  try {
+    const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+      ? fs.constants.O_NOFOLLOW : 0;
+    fd = fs.openSync(namespace.lockPath, fs.constants.O_CREAT | fs.constants.O_RDWR | noFollow, 0o600);
+    if (process.platform !== 'win32') fs.chmodSync(namespace.lockPath, 0o600);
+    if (process.platform === 'win32') {
+      native.lockFileExSync(
+        fd,
+        native.constants.LOCKFILE_EXCLUSIVE_LOCK | native.constants.LOCKFILE_FAIL_IMMEDIATELY,
+        0, 0, 1, 0
+      );
+    } else {
+      native.flockSync(fd, 'exnb');
+    }
+  } catch (error) {
+    try {
+      if (fd !== undefined) fs.closeSync(fd);
+    } catch {
+      // Preserve the lock acquisition error.
+    }
+    const code = error && typeof error === 'object' && 'code' in error ? String((error as { code?: unknown }).code) : '';
+    if (['EAGAIN', 'EACCES', 'EWOULDBLOCK'].includes(code)) {
+      throw new Error('SANDBOX_LOCK_BUSY');
+    }
+    throw new Error(`SANDBOX_LOCK_UNSUPPORTED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  let released = false;
+  return {
+    path: namespace.lockPath,
+    lockDomain: namespace.lockDomain,
+    release() {
+      if (released) return;
+      released = true;
+      let failure: unknown = null;
+      try {
+        if (fd === undefined) throw new Error('descriptor is missing');
+        if (process.platform === 'win32') native.unlockFileExSync(fd, 0, 0, 1, 0);
+        else native.flockSync(fd, 'un');
+      } catch (error) {
+        failure = error;
+      } finally {
+        try {
+          if (fd !== undefined) fs.closeSync(fd);
+        } catch (error) {
+          failure ??= error;
+        }
+      }
+      if (failure) throw new Error(`SANDBOX_LOCK_RELEASE_FAILED: ${failure instanceof Error ? failure.message : String(failure)}`);
+    }
+  };
+}

package/lib/sandbox/control/protocol.ts

@@ -1,9 +1,16 @@
+import { createHash } from 'node:crypto';
 import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../task/create.ts';
 import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
 import type { ProcessIdentity } from '../../server/process-state.ts';
 import type { CodexControllerLeaseProofV1 } from './controller-registration.ts';
+import type { SandboxAuthorityEvidenceV1 } from '../engines/authority.ts';
+import type { SandboxTaskView } from './task-view.ts';
 
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
+export const SANDBOX_CONTROL_MAX_LOGICAL_RECORDS = 1024;
+export const SANDBOX_CONTROL_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+export const SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES = 1024 * 1024;
+export const SANDBOX_CONTROL_RESERVATION_BYTES = SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES + 4 * 1024;
 export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
 export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
 export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
@@ -32,6 +39,7 @@ export type SandboxControlContainerIdentity = Readonly<{
 export type SandboxControlManifestBase = Readonly<{
   engine: string; repoRoot: string; worktreeRoot: string; project: string; container: string;
   containerIdentity: SandboxControlContainerIdentity;
+  authorityEvidence: SandboxAuthorityEvidenceV1;
   branch: string; mode: 'task-bound' | 'branch-only'; taskId: string | null; token: string;
   generation: string; channelDir: string; publicStatusDir: string; processingDir: string;
 }>;
@@ -63,14 +71,48 @@ export type SandboxCodexControllerRequest = RequestBase & Readonly<{
 }>;
 export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest;
 export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
+export type SandboxControlResultEvidence = Readonly<{
+  version: 1;
+  id: string;
+  generation: string;
+  exitCode: number;
+  stdoutBytes: number;
+  stderrBytes: number;
+  stdoutSha256: string;
+  stderrSha256: string;
+  captureState: 'metadata-only';
+}>;
+export type SandboxControlPayloadReference = Readonly<{
+  version: 1;
+  id: string;
+  generation: string;
+  stdoutBytes: number;
+  stderrBytes: number;
+  stdoutSha256: string;
+  stderrSha256: string;
+}>;
+export type SandboxControlPayload = SandboxControlPayloadReference & Readonly<{
+  stdout: string;
+  stderr: string;
+}>;
+export type SandboxControlReservation = Readonly<{
+  version: 1;
+  id: string;
+  generation: string;
+  logicalRecords: 1;
+  bytes: number;
+  createdAt: number;
+}>;
 export type SandboxControlResponse = Readonly<{
   version: 2; id: string; phase: 'accepted' | 'completed' | 'rejected'; exitCode: number | null;
   stdout: string; stderr: string; error: SandboxControlError | null;
+  outputState?: 'available' | 'unavailable';
+  payload?: SandboxControlPayloadReference | null;
 }>;
 export type SandboxControlStatus = Readonly<{
-  version: 2; generation: string; broker: ProcessIdentity & { brokerId: string };
+  version: 3; generation: string; broker: ProcessIdentity & { brokerId: string };
   state: 'starting' | 'healthy' | 'busy' | 'parked'; reasonCode: string | null;
-  activeRequestId: string | null; updatedAt: number;
+  activeRequestId: string | null; updatedAt: number; taskView: SandboxTaskView;
 }>;
 export type SandboxControlLease = Readonly<{
   version: 2; generation: string; nonce: string; owner: ProcessIdentity;
@@ -97,6 +139,80 @@ function fail(code: string, message: string, retryable = false): never {
   throw new SandboxControlProtocolError(code, message, retryable);
 }
 
+export function parseSandboxControlResultEvidence(value: unknown): SandboxControlResultEvidence {
+  const evidence = value as Partial<SandboxControlResultEvidence> | null;
+  const keys = evidence && typeof evidence === 'object' ? Object.keys(evidence).sort().join(',') : '';
+  if (keys !== 'captureState,exitCode,generation,id,stderrBytes,stderrSha256,stdoutBytes,stdoutSha256,version'
+    || evidence?.version !== 1
+    || typeof evidence.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(evidence.id)
+    || typeof evidence.generation !== 'string' || evidence.generation.length === 0
+    || !Number.isSafeInteger(evidence.exitCode)
+    || !Number.isSafeInteger(evidence.stdoutBytes) || (evidence.stdoutBytes as number) < 0
+    || !Number.isSafeInteger(evidence.stderrBytes) || (evidence.stderrBytes as number) < 0
+    || (evidence.stdoutBytes as number) + (evidence.stderrBytes as number) > SANDBOX_CONTROL_MAX_RESPONSE_BYTES
+    || typeof evidence.stdoutSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(evidence.stdoutSha256)
+    || typeof evidence.stderrSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(evidence.stderrSha256)
+    || evidence.captureState !== 'metadata-only') {
+    throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+  }
+  return evidence as SandboxControlResultEvidence;
+}
+
+function validPayloadReference(value: unknown, id: string, generation: string): value is SandboxControlPayloadReference {
+  const payload = value as Partial<SandboxControlPayloadReference> | null;
+  const keys = payload && typeof payload === 'object' ? Object.keys(payload).sort().join(',') : '';
+  return keys === 'generation,id,stderrBytes,stderrSha256,stdoutBytes,stdoutSha256,version'
+    && payload?.version === 1
+    && payload.id === id
+    && payload.generation === generation
+    && Number.isSafeInteger(payload.stdoutBytes) && (payload.stdoutBytes as number) >= 0
+    && Number.isSafeInteger(payload.stderrBytes) && (payload.stderrBytes as number) >= 0
+    && (payload.stdoutBytes as number) + (payload.stderrBytes as number) <= SANDBOX_CONTROL_MAX_RESPONSE_BYTES
+    && typeof payload.stdoutSha256 === 'string' && /^[a-f0-9]{64}$/u.test(payload.stdoutSha256)
+    && typeof payload.stderrSha256 === 'string' && /^[a-f0-9]{64}$/u.test(payload.stderrSha256);
+}
+
+export function parseSandboxControlPayload(value: unknown): SandboxControlPayload {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+  const payload = value as Partial<SandboxControlPayload>;
+  const reference: Partial<SandboxControlPayloadReference> = {
+    version: payload.version,
+    id: payload.id,
+    generation: payload.generation,
+    stdoutBytes: payload.stdoutBytes,
+    stderrBytes: payload.stderrBytes,
+    stdoutSha256: payload.stdoutSha256,
+    stderrSha256: payload.stderrSha256
+  };
+  const keys = Object.keys(payload).sort().join(',');
+  if (keys !== 'generation,id,stderr,stderrBytes,stderrSha256,stdout,stdoutBytes,stdoutSha256,version'
+    || !validPayloadReference(reference, reference.id as string, reference.generation as string)
+    || typeof payload.stdout !== 'string' || typeof payload.stderr !== 'string'
+    || Buffer.byteLength(payload.stdout, 'utf8') !== payload.stdoutBytes
+    || Buffer.byteLength(payload.stderr, 'utf8') !== payload.stderrBytes
+    || createHash('sha256').update(payload.stdout, 'utf8').digest('hex') !== payload.stdoutSha256
+    || createHash('sha256').update(payload.stderr, 'utf8').digest('hex') !== payload.stderrSha256) {
+    throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+  }
+  return payload as SandboxControlPayload;
+}
+
+export function parseSandboxControlReservation(value: unknown): SandboxControlReservation {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+  const reservation = value as Partial<SandboxControlReservation>;
+  const keys = Object.keys(reservation).sort().join(',');
+  if (keys !== 'bytes,createdAt,generation,id,logicalRecords,version'
+    || reservation.version !== 1
+    || typeof reservation.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(reservation.id)
+    || typeof reservation.generation !== 'string' || reservation.generation.length === 0
+    || reservation.logicalRecords !== 1
+    || !Number.isSafeInteger(reservation.bytes) || (reservation.bytes as number) < SANDBOX_CONTROL_RESERVATION_BYTES
+    || !Number.isSafeInteger(reservation.createdAt)) {
+    throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+  }
+  return reservation as SandboxControlReservation;
+}
+
 export function isSandboxControlFamily(value: string): value is SandboxControlFamily {
   return SANDBOX_CONTROL_FAMILIES.includes(value as SandboxControlFamily);
 }