@fitlab-ai/agent-infra 0.9.13 → 0.9.15

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

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { acquireFileLock, NATIVE_LOCK_PRIMITIVE, probeNativeLockCapability } from '../../fs/file-lock.ts';
+export { probeNativeLockCapability };
+
+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 LOCK_ROOT_NAME = path.join('.agent-infra', 'sandbox-locks');
+
+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 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);
+  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 acquireSandboxResourceLock(
+  carrierIdentity: string,
+  options: Readonly<{ lockDomain?: string; home?: string }> = {}
+): SandboxResourceLock {
+  const namespace = resolveSandboxLockNamespace(carrierIdentity, options);
+  try {
+    const lock = acquireFileLock(namespace.lockPath);
+    return { path: namespace.lockPath, lockDomain: namespace.lockDomain, release: lock.release };
+  } catch (error) {
+    throw new Error(String(error instanceof Error ? error.message : error).replaceAll('FILE_LOCK_', 'SANDBOX_LOCK_'));
+  }
+}

package/lib/sandbox/control/protocol.ts

@@ -3,6 +3,14 @@ import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../t
 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';
+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;
@@ -13,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;
@@ -37,8 +45,9 @@ 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;
+  generation: string; controlRootId: string; channelDir: string; publicStatusDir: string; processingDir: string;
 }>;
 export type SandboxControlManifest = SandboxControlManifestBase & Readonly<{ runtimeDir: string }>;
 export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
@@ -47,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;
@@ -54,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: [];
@@ -66,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;
@@ -107,9 +132,9 @@ export type SandboxControlResponse = Readonly<{
   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;
@@ -283,8 +308,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');
   }
@@ -305,11 +347,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');