@fitlab-ai/agent-infra 0.11.11 → 0.11.13

package/lib/sandbox/control/executor.ts

@@ -10,8 +10,6 @@ import {
   taskCreateFailure,
   type TaskCreateResult
 } from '../../task/create-service.ts';
-import { applyTaskFinalization } from '../../task/finalization.ts';
-import { serializeTaskFinalizationEnvelope } from '../../task/finalization-envelope.ts';
 import {
   bindSandboxControlTask,
   validateSandboxControlRequest,
@@ -35,13 +33,8 @@ import {
   type TaskControlOperation
 } from '../../task/control-authority.ts';
 import { assertSandboxControlBrokerOwner, readSandboxControlManifest, type BrokerOwner } from './lifecycle.ts';
-import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import {
-  closeCodexControllerRegistration,
-  CodexControllerRegistrationError,
-  openCodexControllerRegistration,
-  resolveCodexControllerBinding
-} from './controller-registration.ts';
+import { executeAgentClientOperation, validateAgentClientOperation } from './agent-operation.ts';
+import type { AgentClientSandboxControlOperation } from '../../agent-clients/adapter.ts';
 
 export type SandboxControlExecutionResult = {
   exitCode: number;
@@ -234,24 +227,6 @@ function waitForGate(nonce: string, timeoutMs = 2_000): Promise<Readonly<{ owner
   });
 }
 
-function controllerFailure(error: unknown): SandboxControlExecutionResult {
-  const code = error instanceof CodexControllerRegistrationError
-    ? error.code
-    : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
-      ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
-  const message = error instanceof CodexControllerRegistrationError
-    ? error.message
-    : `${code}: controller operation failed; inspect the sandbox controller and rebuild the sandbox if needed`;
-  const payload = {
-    version: 1,
-    status: 'failed',
-    changed: false,
-    lease: null,
-    error: { code, message, retryable: false }
-  };
-  return { exitCode: 1, stdout: `${JSON.stringify(payload)}\n`, stderr: '' };
-}
-
 function lifecycleFailure(code: string, message: string): SandboxControlExecutionResult {
   return {
     exitCode: 1,
@@ -279,26 +254,9 @@ function taskCreateExecutionFailure(requestId: string, code: string, message: st
   }));
 }
 
-function finalizationResult(result: Awaited<ReturnType<typeof applyTaskFinalization>>): SandboxControlExecutionResult {
-  const payload = {
-    version: 1,
-    status: result.status,
-    changed: result.changed,
-    accepted: true,
-    result,
-    error: result.error
-  };
-  return {
-    exitCode: result.status === 'completed' ? 0 : result.status === 'blocked' ? 2 : 1,
-    stdout: `${JSON.stringify(payload)}\n`,
-    stderr: ''
-  };
-}
-
 type ExecuteRequestOptions = Readonly<{
-  buildIdentity?: typeof computeLifecycleBuildIdentity;
-  resolveControllerBinding?: typeof resolveCodexControllerBinding;
   createTask?: typeof createTask;
+  agentClientOperation?: AgentClientSandboxControlOperation;
 }>;
 
 async function executeRequestInner(
@@ -321,78 +279,9 @@ async function executeRequestInner(
       return taskCreateExecutionFailure(request.id, code, detail);
     }
   }
-  if (request.family === 'codex-controller') {
-    try {
-      if (request.command === 'verify') {
-        const binding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
-          manifest,
-          manifestPath,
-          proof: request.controllerProof!,
-          buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
-        });
-        return {
-          exitCode: 0,
-          stdout: `${JSON.stringify({
-            version: 1,
-            status: 'verified',
-            changed: false,
-            lease: null,
-            binding: {
-              taskId: manifest.taskId,
-              controlGeneration: binding.controlGeneration,
-              controllerInstanceDigest: binding.instanceDigest
-            },
-            error: null
-          })}\n`,
-          stderr: ''
-        };
-      }
-      const result = request.command === 'open'
-        ? openCodexControllerRegistration({
-            manifest,
-            manifestPath,
-            controllerProcess: request.controllerProcess!,
-            buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
-          })
-        : closeCodexControllerRegistration({
-            manifest,
-            manifestPath,
-            proof: request.controllerProof!
-          });
-      return { exitCode: 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
-    } catch (error) {
-      const errorCode = error instanceof CodexControllerRegistrationError
-        ? error.code
-        : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
-          ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
-      appendExecutorAudit(manifest, 'controller-operation-failed', {
-        ...requestAuditFields(manifest, request),
-        controllerCommand: request.command,
-        errorCode,
-        errorType: error instanceof Error ? error.name : typeof error,
-      });
-      return controllerFailure(error);
-    }
-  }
-  if (request.family === 'task-finalization') {
-    const parsed = parseTaskControlOperation(
-      'task-finalization', [manifest.taskId!, 'complete', '--agent', request.agent]
-    );
-    if (parsed.family !== 'task-finalization') throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
-    const operation = parsed;
-    const result = dispatchTaskControlOperation(
-      createSandboxExecutorExecutionContext({
-        repoRoot: manifest.repoRoot,
-        worktreeRoot: manifest.worktreeRoot,
-        runtimeDir: manifest.runtimeDir,
-        taskId: manifest.taskId!,
-        generation: manifest.generation,
-        manifestPath,
-        requestId: request.id
-      }),
-      operation
-    );
-    return finalizationResult(await result);
+  if (request.family === 'agent-client') {
+    validateAgentClientOperation(request, manifest);
+    return executeAgentClientOperation(request, manifest, manifestPath, options.agentClientOperation);
   }
   const boundArgs = bindSandboxControlTask(request, manifest.taskId!);
   let operation: TaskControlOperation;
@@ -433,7 +322,8 @@ export async function executeRequest(
   const fields = requestAuditFields(manifest, request);
   appendExecutorAudit(manifest, 'executor-request-start', fields);
   try {
-    const result = await executeRequestInner(manifest, manifestPath, request, options);
+    let result: SandboxControlExecutionResult;
+    result = await executeRequestInner(manifest, manifestPath, request, options);
     appendExecutorAudit(manifest, 'executor-request-finished', {
       requestId: request.id,
       requestFamily: request.family,
@@ -500,17 +390,17 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
   let result: SandboxControlExecutionResult;
   try {
     assertSandboxControlExecutorAuthority(manifest, gateOwner);
-    const operation = request.family === 'task-lifecycle'
+  const operation = request.family === 'task-lifecycle'
       ? (() => {
         try { return parseTaskControlOperation(request.family, request.args); } catch { return null; }
       })()
-      : null;
+      : request.family === 'agent-client' ? request.operation : null;
     const context = createSandboxControlAuditContext(manifest, {
       requestId: request.id,
       family: request.family,
-      operation: operation?.family === 'task-lifecycle'
+      operation: operation && typeof operation === 'object' && 'family' in operation && operation.family === 'task-lifecycle'
         ? operation.request.intent
-          : request.family === 'task-finalization' ? request.operation : null,
+        : request.family === 'agent-client' ? request.operation : null,
       phase: 'started-committed',
       outcome: 'in-progress'
     });
@@ -526,20 +416,7 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
     });
     const detail = error instanceof Error ? error.message : String(error);
     const code = /^([A-Z][A-Z0-9_]+)/u.exec(detail)?.[1] ?? 'SANDBOX_CONTROL_EXECUTOR_FAILED';
-    result = request.family === 'task-finalization'
-      ? {
-        exitCode: 1,
-        stdout: serializeTaskFinalizationEnvelope({
-          status: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 'unknown' : 'failed',
-          changed: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? null : false,
-          accepted: true,
-          requestId: request.id,
-          result: null,
-          error: { code, message: detail, retryable: false }
-        }),
-        stderr: ''
-      }
-      : request.family === 'task-create'
+    result = request.family === 'task-create'
         ? taskCreateExecutionFailure(request.id, code, detail)
         : lifecycleFailure(code, detail);
   }

package/lib/sandbox/control/lifecycle.ts

@@ -23,6 +23,7 @@ import {
   type SandboxResourceLock
 } from './native-file-lock.ts';
 import { isSandboxAuthorityEvidence } from '../engines/authority.ts';
+import { validateSandboxControlIdentity } from './identity-sentinel.ts';
 import {
   parseSandboxControlStatus,
   readExecution,
@@ -639,6 +640,51 @@ function markSandboxControlRootQuiescing(root: string): void {
   }
 }
 
+function readTaskCompletionManifest(
+  root: string,
+  binding: Readonly<{ taskId: string; generation: string; controlRootId: string; statusDir: string }>
+): SandboxControlManifest {
+  const manifest = readSandboxControlManifest(path.join(root, 'manifest.json'));
+  const identity = validateSandboxControlIdentity({
+    publicStatusDir: binding.statusDir,
+    root,
+    mode: manifest.mode,
+    taskId: manifest.taskId,
+    generation: manifest.generation,
+    controlRootId: manifest.controlRootId
+  });
+  if (identity.state !== 'valid' || manifest.mode !== 'task-bound'
+    || manifest.taskId !== binding.taskId || manifest.generation !== binding.generation
+    || manifest.controlRootId !== binding.controlRootId) {
+    throw new Error('SANDBOX_CONTROL_IDENTITY_MISMATCH');
+  }
+  return manifest;
+}
+
+export async function quiesceSandboxControlForTaskCompletion(
+  root: string,
+  binding: Readonly<{ taskId: string; generation: string; controlRootId: string; statusDir: string }>,
+  timeoutMs = DEFAULT_QUIESCE_TIMEOUT_MS
+): Promise<void> {
+  const resolvedRoot = path.resolve(root);
+  const manifest = readTaskCompletionManifest(resolvedRoot, binding);
+  markSandboxControlRootQuiescing(resolvedRoot);
+  const deadline = Date.now() + timeoutMs;
+  const startupPath = path.join(resolvedRoot, BROKER_STARTING_FILE);
+  const brokerPath = path.join(resolvedRoot, 'broker.json');
+  while (true) {
+    const startup = readStartupOwner(startupPath);
+    if (fs.existsSync(startupPath) && !startup) throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+    const broker = readBrokerOwner(brokerPath);
+    if (broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
+      throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    if (!startup && !broker) return;
+    if (Date.now() >= deadline) throw new Error('SANDBOX_CONTROL_BROKER_DRAIN_TIMEOUT');
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+}
+
 function recordSandboxRemovalPending(
   root: string,
   manifest: SandboxControlManifest,
@@ -1108,12 +1154,29 @@ function readSandboxControlManifestValue(manifestPath: string): SandboxControlMa
     || (candidate.mode === 'branch-only' && candidate.taskId !== null)
     || !isSandboxAuthorityEvidence(candidate.authorityEvidence)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   const root = path.dirname(path.resolve(manifestPath));
-  if (path.resolve(candidate.channelDir) !== path.join(root, 'channel')
-    || path.resolve(candidate.publicStatusDir) !== path.join(root, 'public')
-    || path.resolve(candidate.processingDir) !== path.join(root, 'processing')) {
+  const canonicalRoot = fs.realpathSync.native(root);
+  const matchesControlChildPath = (candidatePath: string, name: string): boolean => {
+    const resolved = path.resolve(candidatePath);
+    if (path.basename(resolved) !== name) return false;
+    const expected = path.join(canonicalRoot, name);
+    try {
+      return fs.realpathSync.native(resolved) === expected;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      try {
+        return fs.realpathSync.native(path.dirname(resolved)) === canonicalRoot;
+      } catch (parentError) {
+        if ((parentError as NodeJS.ErrnoException).code !== 'ENOENT') throw parentError;
+        return false;
+      }
+    }
+  };
+  if (!matchesControlChildPath(candidate.channelDir, 'channel')
+    || !matchesControlChildPath(candidate.publicStatusDir, 'public')
+    || !matchesControlChildPath(candidate.processingDir, 'processing')) {
     throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   }
-  if (path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
+  if (!matchesControlChildPath(candidate.runtimeDir, 'runtime')) {
     throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   }
   const normalized: SandboxControlManifest = {

package/lib/sandbox/control/protocol.ts

@@ -1,8 +1,7 @@
 import { createHash } from 'node:crypto';
 import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../task/create.ts';
-import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
+import { isAgentClientId } from '../../agent-clients/types.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';
 
@@ -15,7 +14,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-finalization', 'task-create', 'codex-controller'] as const;
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-create', 'agent-client'] as const;
 export type SandboxControlTimingPolicy = Readonly<{
   controlTickMs: number;
   parkedBindingInitialMs: number;
@@ -58,24 +57,20 @@ export type SandboxControlExecutorGateV2 = Readonly<{
 }>;
 type RequestBase = Readonly<{
   version: 4; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
-  controllerProcess: ProcessIdentity | null;
-  controllerProof: CodexControllerLeaseProofV1 | null;
 }>;
 export type SandboxTaskCommandRequest = RequestBase & Readonly<{
   family: 'task-lifecycle'; args: string[];
 }>;
-export type SandboxTaskFinalizationRequest = RequestBase & Readonly<{
-  family: 'task-finalization'; operation: 'complete'; agent: string; args: [];
-}>;
 export type SandboxTaskCreateRequest = RequestBase & Readonly<{
   family: 'task-create'; candidate: TaskCreateCandidateV1;
 }>;
-export type SandboxCodexControllerRequest = RequestBase & Readonly<{
-  family: 'codex-controller';
-  command: 'open' | 'close' | 'verify';
-  args: [];
+export type SandboxAgentClientRequest = RequestBase & Readonly<{
+  family: 'agent-client';
+  agentClient: string;
+  operation: string;
+  payload: Record<string, unknown>;
 }>;
-export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest;
+export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskCreateRequest | SandboxAgentClientRequest;
 export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
 export type SandboxControlResultEvidence = Readonly<{
   version: 1;
@@ -252,89 +247,50 @@ export function validateSandboxControlRequest(
     fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
   }
   if (request.family === 'task-create') {
-    const expected = ['candidate', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    const expected = ['candidate', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
     if (Object.keys(request).sort().join(',') !== expected.sort().join(',')) {
       fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
     }
-    if (request.controllerProcess !== null || request.controllerProof !== null) {
-      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create cannot carry controller authority');
-    }
     return { ...request, candidate: validateTaskCreateCandidate(request.candidate) } as SandboxTaskCreateRequest;
   }
-  if (request.family === 'codex-controller') {
-    const expected = ['args', 'command', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
-    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
-      || !Array.isArray(request.args) || request.args.length !== 0
-      || !['open', 'close', 'verify'].includes(request.command as string)
-      || !validControllerProcess(request.controllerProcess)
-      || (request.command === 'open' && request.controllerProof !== null)
-      || (request.command !== 'open' && !validControllerProof(request.controllerProof))
-      || (request.command === 'verify'
-        && JSON.stringify(request.controllerProcess) !== JSON.stringify((request.controllerProof as CodexControllerLeaseProofV1).controllerProcess))) {
-      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller request schema is invalid');
-    }
-    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
-      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot register a Codex controller');
-    }
-    return request as SandboxCodexControllerRequest;
-  }
-  if (request.family === 'task-finalization') {
-    const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'token', 'version'];
+  if (request.family === 'agent-client') {
+    const expected = ['agentClient', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'payload', 'token', 'version'];
     if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
-      || request.operation !== 'complete'
-      || !Array.isArray(request.args) || request.args.length !== 0
-      || typeof request.agent !== 'string' || normalizeAgentToken(request.agent) !== request.agent
-      || request.controllerProcess !== null || request.controllerProof !== null) {
-      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization request schema or authorization is invalid');
+      || !isAgentClientId(request.agentClient)
+      || typeof request.operation !== 'string' || !/^[a-z][a-z0-9.-]{0,63}$/u.test(request.operation)
+      || !request.payload || typeof request.payload !== 'object' || Array.isArray(request.payload)) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'agent-client request schema is invalid');
     }
     if (manifest.mode !== 'task-bound' || !manifest.taskId) {
-      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks');
+      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot coordinate agent clients');
     }
-    return request as SandboxTaskFinalizationRequest;
+    return request as SandboxAgentClientRequest;
   }
-  const expected = ['args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+  const expected = ['args', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
   if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
     || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
   }
+  if (request.args[1] === 'complete') {
+    fail('SANDBOX_CONTROL_COMMAND_DENIED', 'complete must use task-finalization');
+  }
   if (manifest.mode !== 'task-bound' || !manifest.taskId) {
     fail(
       'SANDBOX_CONTROL_BRANCH_ONLY',
       "branch-only sandboxes cannot coordinate tasks; return to the host and run 'ai sandbox start --recreate <task-ref-or-correct-branch>'"
     );
   }
-  if (request.controllerProcess !== null || request.controllerProof !== null) {
-    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller authority is invalid');
-  }
   return request as SandboxTaskCommandRequest;
 }
 
 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 === 'agent-client') {
     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');
   return [taskId, ...request.args.slice(1)];
 }
 
-function validControllerProcess(value: unknown): value is ProcessIdentity {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  const processValue = value as Record<string, unknown>;
-  return Object.keys(processValue).sort().join(',') === 'pid,startTime'
-    && Number.isSafeInteger(processValue.pid) && (processValue.pid as number) > 0
-    && Number.isSafeInteger(processValue.startTime) && (processValue.startTime as number) >= 0;
-}
-
-function validControllerProof(value: unknown): value is CodexControllerLeaseProofV1 {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  const proof = value as Record<string, unknown>;
-  return Object.keys(proof).sort().join(',') === 'controllerProcess,leaseId,leaseSecret,version'
-    && proof.version === 1
-    && typeof proof.leaseId === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseId)
-    && typeof proof.leaseSecret === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseSecret)
-    && validControllerProcess(proof.controllerProcess);
-}
-
 export function controlError(error: unknown): SandboxControlError {
   if (error instanceof SandboxControlProtocolError) {
     return { code: error.code, message: error.message, retryable: error.retryable };