@fitlab-ai/agent-infra 0.9.14 → 0.10.0

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

@@ -1,26 +1,10 @@
 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;
-}>;
+import { acquireFileLock, NATIVE_LOCK_PRIMITIVE, probeNativeLockCapability } from '../../fs/file-lock.ts';
+export { probeNativeLockCapability };
 
 export type SandboxLockNamespace = Readonly<{
   lockRoot: string;
@@ -36,17 +20,8 @@ export type SandboxResourceLock = Readonly<{
   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');
 }
@@ -97,8 +72,7 @@ export function resolveSandboxLockNamespace(
   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}`);
+  const lockDomain = options.lockDomain ?? digest(`${process.platform}\0${process.arch}\0${NATIVE_LOCK_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);
@@ -120,90 +94,15 @@ export function stableSandboxLockPath(
   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');
-    }
+    const lock = acquireFileLock(namespace.lockPath);
+    return { path: namespace.lockPath, lockDomain: namespace.lockDomain, release: lock.release };
   } 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)}`);
+    throw new Error(String(error instanceof Error ? error.message : error).replaceAll('FILE_LOCK_', 'SANDBOX_LOCK_'));
   }
-
-  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

@@ -5,6 +5,12 @@ 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';
+import { validateTaskWorkflowRequest, type TaskWorkflowRequest } from './task-workflow.ts';
+import {
+  validateLifecycleAuthorityRequest,
+  type LifecycleAuthorityRequestV1,
+  type LifecycleRecoveryAttestationV1
+} from '../../task/control-authority.ts';
 
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
 export const SANDBOX_CONTROL_MAX_LOGICAL_RECORDS = 1024;
@@ -15,7 +21,7 @@ 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;
 export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
-export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-finalization', 'task-create', 'codex-controller'] as const;
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-finalization', 'task-create', 'codex-controller', 'task-workflow'] as const;
 export type SandboxControlTimingPolicy = Readonly<{
   controlTickMs: number;
   parkedBindingInitialMs: number;
@@ -41,7 +47,7 @@ export type SandboxControlManifestBase = Readonly<{
   containerIdentity: SandboxControlContainerIdentity;
   authorityEvidence: SandboxAuthorityEvidenceV1;
   branch: string; mode: 'task-bound' | 'branch-only'; taskId: string | null; token: string;
-  generation: string; channelDir: string; publicStatusDir: string; processingDir: string;
+  generation: string; controlRootId: string; channelDir: string; publicStatusDir: string; processingDir: string;
 }>;
 export type SandboxControlManifest = SandboxControlManifestBase & Readonly<{ runtimeDir: string }>;
 export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
@@ -50,6 +56,15 @@ export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
   token: string;
   generation: string;
 }>;
+export type SandboxControlExecutorGateV2 = Readonly<{
+  version: 2;
+  nonce: string;
+  owner: SandboxControlBrokerOwner;
+  requestId: string;
+  operationId: string;
+  phase: 'orchestration.prepare' | 'artifact.finalize-local' | 'task-event.completed';
+  authority: LifecycleRecoveryAttestationV1 | null;
+}>;
 type RequestBase = Readonly<{
   version: 3; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
   controllerProcess: ProcessIdentity | null;
@@ -57,6 +72,7 @@ type RequestBase = Readonly<{
 }>;
 export type SandboxTaskCommandRequest = RequestBase & Readonly<{
   family: 'task-lifecycle' | 'task-orchestration'; args: string[];
+  authority?: LifecycleAuthorityRequestV1;
 }>;
 export type SandboxTaskFinalizationRequest = RequestBase & Readonly<{
   family: 'task-finalization'; operation: 'complete'; agent: string; args: [];
@@ -69,7 +85,13 @@ export type SandboxCodexControllerRequest = RequestBase & Readonly<{
   command: 'open' | 'close' | 'verify';
   args: [];
 }>;
-export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest;
+export type SandboxTaskWorkflowRequest = RequestBase & Readonly<{
+  family: 'task-workflow';
+  args: [];
+  workflow: TaskWorkflowRequest;
+  authority?: LifecycleAuthorityRequestV1;
+}>;
+export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest | SandboxTaskWorkflowRequest;
 export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
 export type SandboxControlResultEvidence = Readonly<{
   version: 1;
@@ -109,6 +131,11 @@ export type SandboxControlResponse = Readonly<{
   outputState?: 'available' | 'unavailable';
   payload?: SandboxControlPayloadReference | null;
 }>;
+export type SandboxControlRecoveryWarning = Readonly<{
+  code: string;
+  message: string;
+  action: string;
+}>;
 export type SandboxControlStatus = Readonly<{
   version: 3; generation: string; broker: ProcessIdentity & { brokerId: string };
   state: 'starting' | 'healthy' | 'busy' | 'parked'; reasonCode: string | null;
@@ -286,8 +313,25 @@ export function validateSandboxControlRequest(
     }
     return request as SandboxTaskFinalizationRequest;
   }
-  const expected = ['args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
-  if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+  if (request.family === 'task-workflow') {
+    const expected = ['args', 'authority', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version', 'workflow'];
+    const baseExpected = expected.filter((key) => key !== 'authority');
+    if (![baseExpected, expected].some((keys) => Object.keys(request).sort().join(',') === keys.sort().join(','))
+      || !Array.isArray(request.args) || request.args.length !== 0
+      || request.controllerProcess !== null || request.controllerProof !== null) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-workflow request schema is invalid');
+    }
+    if (manifest.mode !== 'task-bound' || !manifest.taskId) fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot use task-workflow');
+    const workflow = validateTaskWorkflowRequest(request.workflow);
+    if (workflow.taskId !== manifest.taskId || workflow.generation !== manifest.generation || workflow.id !== request.id) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-workflow binding does not match the sandbox manifest');
+    }
+    if (request.authority !== undefined) validateAuthoritySelector(request.authority, request, manifest);
+    return { ...request, workflow } as SandboxTaskWorkflowRequest;
+  }
+  const expected = ['args', 'authority', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+  const baseExpected = expected.filter((key) => key !== 'authority');
+  if (![baseExpected, expected].some((keys) => Object.keys(request).sort().join(',') === keys.sort().join(','))
     || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
   }
@@ -308,11 +352,41 @@ export function validateSandboxControlRequest(
   if (request.family !== 'task-orchestration' && request.controllerProof !== null) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller proof is not allowed for this family');
   }
+  if (request.authority !== undefined) validateAuthoritySelector(request.authority, request, manifest);
   return request as SandboxTaskCommandRequest;
 }
 
+function validateAuthoritySelector(
+  value: unknown,
+  request: Record<string, unknown>,
+  manifest: SandboxControlManifest
+): asserts value is LifecycleAuthorityRequestV1 {
+  let authority: LifecycleAuthorityRequestV1;
+  try { authority = validateLifecycleAuthorityRequest(value); }
+  catch { fail('SANDBOX_CONTROL_AUTHORITY_INVALID', 'lifecycle authority selector is invalid'); }
+  if (authority.requestId !== request.id
+    || authority.taskId !== manifest.taskId
+    || authority.expectedControlGeneration !== manifest.generation) {
+    fail('SANDBOX_CONTROL_AUTHORITY_INVALID', 'lifecycle authority selector is not bound to this request');
+  }
+  const args = Array.isArray(request.args) ? request.args : [];
+  if (request.family === 'task-orchestration'
+    && (args[1] !== 'prepare' || authority.phase !== 'orchestration.prepare')) {
+    fail('SANDBOX_CONTROL_AUTHORITY_INVALID', 'orchestration authority is only valid for prepare');
+  }
+  const workflow = request.workflow as TaskWorkflowRequest | undefined;
+  if (request.family === 'task-workflow') {
+    const expectedPhase = workflow?.operation === 'artifact-finalize-local'
+      ? 'artifact.finalize-local'
+      : workflow?.operation === 'event' ? 'task-event.completed' : null;
+    if (authority.phase !== expectedPhase) {
+      fail('SANDBOX_CONTROL_AUTHORITY_INVALID', 'workflow authority phase does not match the workflow operation');
+    }
+  }
+}
+
 export function bindSandboxControlTask(request: SandboxControlRequest, taskId: string): string[] {
-  if (request.family === 'task-create' || request.family === 'codex-controller' || request.family === 'task-finalization') {
+  if (request.family === 'task-create' || request.family === 'codex-controller' || request.family === 'task-finalization' || request.family === 'task-workflow') {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', `${request.family} requests do not bind a current task`);
   }
   if (request.args.length === 0) fail('SANDBOX_CONTROL_REQUEST_INVALID', 'command arguments are required');