@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/sandbox/control/audit.ts

@@ -0,0 +1,253 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { SandboxControlManifest, SandboxControlFamily, SandboxControlRequest } from './protocol.ts';
+import { identityDigest as digestIdentity } from './identity-sentinel.ts';
+import { acquireSandboxResourceLock } from './native-file-lock.ts';
+import { fsyncDirectory, writeDurableFile } from '../../fs/durable-write.ts';
+
+export const SANDBOX_CONTROL_AUDIT_PHASES = Object.freeze([
+  'validated', 'gated', 'reserved', 'prepared', 'accepted-authorized', 'accepted-committed',
+  'start-authorized', 'started-committed', 'completed', 'evidence-written',
+  'publish-authorized', 'published-committed', 'rejected', 'recovered'
+] as const);
+export type SandboxControlAuditPhase = typeof SANDBOX_CONTROL_AUDIT_PHASES[number];
+export type SandboxControlAuditOutcome = 'not-executed' | 'in-progress' | 'success' | 'failure' | 'unknown' | 'rejected';
+
+export type SandboxControlAuditContext = Readonly<{
+  requestId: string;
+  taskId: string | null;
+  family: SandboxControlFamily | null;
+  operation: string | null;
+  phase: SandboxControlAuditPhase;
+  outcome: SandboxControlAuditOutcome;
+  generation: string;
+  identityDigest: string;
+}>;
+
+export type SandboxControlTransition = Readonly<{
+  version: 1;
+  requestId: string;
+  generation: string;
+  phase: SandboxControlAuditPhase;
+  at: number;
+  identityDigest: string;
+  reference: string | null;
+}>;
+
+const REQUEST_ID = /^[a-f0-9-]{16,64}$/u;
+const SAFE_OPERATION = /^[a-z][a-z0-9.-]{0,96}$/u;
+const AUDIT_MAX_BYTES = 1024 * 1024;
+
+export function requestAuditFields(manifest: SandboxControlManifest, request: SandboxControlRequest) {
+  return {
+    requestId: request.id, requestFamily: request.family, sandboxTaskId: manifest.taskId,
+    requestGeneration: request.generation, requestIssuedAt: request.issuedAt, requestExpiresAt: request.expiresAt
+  };
+}
+
+export function resultAuditFields(result: Readonly<{ exitCode: number; stdout: string; stderr: string }>) {
+  return {
+    exitCode: result.exitCode,
+    outputBytes: Buffer.byteLength(result.stdout, 'utf8'), errorBytes: Buffer.byteLength(result.stderr, 'utf8'),
+    outputDigest: createHash('sha256').update(result.stdout, 'utf8').digest('hex'),
+    errorDigest: createHash('sha256').update(result.stderr, 'utf8').digest('hex')
+  };
+}
+
+function auditRoot(manifest: SandboxControlManifest): string {
+  return path.dirname(path.resolve(manifest.publicStatusDir));
+}
+
+function auditPath(manifest: SandboxControlManifest): string {
+  return path.join(auditRoot(manifest), 'audit.ndjson');
+}
+
+function manifestIdentityDigest(manifest: SandboxControlManifest): string {
+  return digestIdentity({
+    version: 1,
+    mode: manifest.mode,
+    taskId: manifest.taskId,
+    generation: manifest.generation,
+    controlRootId: manifest.controlRootId
+  });
+}
+
+export function createSandboxControlAuditContext(
+  manifest: SandboxControlManifest,
+  params: Readonly<{
+    requestId: string;
+    family: SandboxControlFamily | null;
+    operation?: string | null;
+    phase: SandboxControlAuditPhase;
+    outcome: SandboxControlAuditOutcome;
+  }>
+): SandboxControlAuditContext {
+  if (!REQUEST_ID.test(params.requestId)) throw new Error('SANDBOX_CONTROL_AUDIT_REQUEST_INVALID');
+  if (params.operation !== null && params.operation !== undefined && !SAFE_OPERATION.test(params.operation)) {
+    throw new Error('SANDBOX_CONTROL_AUDIT_OPERATION_INVALID');
+  }
+  if (!SANDBOX_CONTROL_AUDIT_PHASES.includes(params.phase)) throw new Error('SANDBOX_CONTROL_AUDIT_PHASE_INVALID');
+  return {
+    requestId: params.requestId,
+    taskId: manifest.taskId,
+    family: params.family,
+    operation: params.operation ?? null,
+    phase: params.phase,
+    outcome: params.outcome,
+    generation: manifest.generation,
+    identityDigest: manifestIdentityDigest(manifest)
+  };
+}
+
+function safeFields(fields: Readonly<Record<string, string | number | boolean | null>>): Record<string, string | number | boolean | null> {
+  const result: Record<string, string | number | boolean | null> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (!/^[a-z][a-zA-Z0-9]{0,63}$/u.test(key)) continue;
+    if (/(token|secret|credential|proof|password|path|root|cwd|stdout|stderr|args|command|taskref)/iu.test(key)) continue;
+    if (typeof value === 'string' && value.length > 256) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+function requestHasTerminalTransition(directory: string): boolean {
+  const transitions = path.join(directory, 'transitions');
+  if (!fs.existsSync(transitions)) return false;
+  return ['published-committed', 'recovered'].some((phase) => fs.existsSync(path.join(transitions, `${phase}.json`)));
+}
+
+function hasActiveRequest(manifest: SandboxControlManifest): boolean {
+  if (!fs.existsSync(manifest.processingDir)) return false;
+  return fs.readdirSync(manifest.processingDir, { withFileTypes: true })
+    .some((entry) => entry.isDirectory() && REQUEST_ID.test(entry.name)
+      && !requestHasTerminalTransition(path.join(manifest.processingDir, entry.name)));
+}
+
+function rotateAuditUnderLock(manifest: SandboxControlManifest, filePath: string): void {
+  if (!fs.existsSync(filePath) || fs.statSync(filePath).size < AUDIT_MAX_BYTES) return;
+  if (hasActiveRequest(manifest)) return;
+  fs.rmSync(`${filePath}.1`, { force: true });
+  fs.renameSync(filePath, `${filePath}.1`);
+  fsyncDirectory(auditRoot(manifest));
+  const descriptor = fs.openSync(filePath, 'a', 0o600);
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function appendAuditRecord(
+  manifest: SandboxControlManifest,
+  record: Readonly<Record<string, unknown>>,
+  critical: boolean
+): void {
+  const root = auditRoot(manifest);
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  const lock = acquireSandboxResourceLock(`sandbox-control-audit:${root}`);
+  try {
+    const filePath = auditPath(manifest);
+    rotateAuditUnderLock(manifest, filePath);
+    const descriptor = fs.openSync(filePath, 'a', 0o600);
+    try {
+      fs.writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, 'utf8');
+      if (critical) fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  } catch (error) {
+    if (critical) throw new Error(`SANDBOX_CONTROL_AUDIT_UNAVAILABLE: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    lock.release();
+  }
+}
+
+export function appendCriticalAudit(
+  manifest: SandboxControlManifest,
+  context: SandboxControlAuditContext,
+  fields: Readonly<Record<string, string | number | boolean | null>> = {},
+  now = Date.now()
+): void {
+  appendAuditRecord(manifest, {
+    version: 2,
+    at: now,
+    event: context.phase,
+    ...context,
+    ...safeFields(fields)
+  }, true);
+}
+
+export function appendDiagnosticAudit(
+  manifest: SandboxControlManifest,
+  event: string,
+  fields: Readonly<Record<string, string | number | boolean | null>> = {},
+  now = Date.now()
+): void {
+  try {
+    appendAuditRecord(manifest, {
+      version: 2,
+      at: now,
+      event,
+      generation: manifest.generation,
+      identityDigest: manifestIdentityDigest(manifest),
+      ...safeFields(fields)
+    }, false);
+  } catch {
+    // Diagnostics are deliberately best effort.
+  }
+}
+
+function transitionPath(manifest: SandboxControlManifest, requestId: string, phase: SandboxControlAuditPhase): string {
+  if (!REQUEST_ID.test(requestId)) throw new Error('SANDBOX_CONTROL_TRANSITION_REQUEST_INVALID');
+  return path.join(manifest.processingDir, requestId, 'transitions', `${phase}.json`);
+}
+
+export function writeSandboxControlTransition(
+  manifest: SandboxControlManifest,
+  params: Readonly<{
+    requestId: string;
+    phase: SandboxControlAuditPhase;
+    reference?: string | null;
+    now?: number;
+  }>
+): SandboxControlTransition {
+  const transition: SandboxControlTransition = {
+    version: 1,
+    requestId: params.requestId,
+    generation: manifest.generation,
+    phase: params.phase,
+    at: params.now ?? Date.now(),
+    identityDigest: manifestIdentityDigest(manifest),
+    reference: params.reference ?? null
+  };
+  const target = transitionPath(manifest, params.requestId, params.phase);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  try {
+    writeDurableFile(target, `${JSON.stringify(transition)}\n`, { mode: 0o600, replace: false });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    const existing = readSandboxControlTransition(manifest, params.requestId, params.phase);
+    if (JSON.stringify(existing) !== JSON.stringify(transition)) throw new Error('SANDBOX_CONTROL_TRANSITION_CONFLICT');
+  }
+  return transition;
+}
+
+export function readSandboxControlTransition(
+  manifest: SandboxControlManifest,
+  requestId: string,
+  phase: SandboxControlAuditPhase
+): SandboxControlTransition {
+  const filePath = transitionPath(manifest, requestId, phase);
+  if (!fs.existsSync(filePath)) throw new Error('SANDBOX_CONTROL_TRANSITION_MISSING');
+  let value: unknown;
+  try { value = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { throw new Error('SANDBOX_CONTROL_TRANSITION_INVALID'); }
+  const candidate = value as Partial<SandboxControlTransition> | null;
+  if (!candidate || candidate.version !== 1 || candidate.requestId !== requestId
+    || candidate.generation !== manifest.generation || candidate.phase !== phase
+    || !Number.isSafeInteger(candidate.at) || typeof candidate.identityDigest !== 'string'
+    || (candidate.reference !== null && typeof candidate.reference !== 'string')) {
+    throw new Error('SANDBOX_CONTROL_TRANSITION_INVALID');
+  }
+  return candidate as SandboxControlTransition;
+}

package/lib/sandbox/control/client.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { hasTaskBoundMarker } from '../../internal/task-operation-registry.ts';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import {
@@ -12,7 +13,8 @@ import {
   type SandboxTaskCreateRequest,
   type SandboxTaskCommandRequest,
   type SandboxTaskFinalizationRequest,
-  type SandboxCodexControllerRequest
+  type SandboxCodexControllerRequest,
+  type SandboxTaskWorkflowRequest
 } from './protocol.ts';
 import type {
   CodexControllerLeaseProofV1,
@@ -23,65 +25,13 @@ import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
 import { readSandboxControlPayload, readSandboxControlStatus } from './state.ts';
 import type { TaskCreateCandidateV1 } from '../../task/create.ts';
 import { accessSandboxTaskView, taskViewFromStatus, type TaskViewAccessEffect } from './task-view.ts';
+import { readSandboxControlIdentitySentinel } from './identity-sentinel.ts';
+import type { TaskWorkflowRequest } from './task-workflow.ts';
+import type { LifecycleAuthorityRequestV1 } from '../../task/control-authority.ts';
+import { configuredShortIdLength, resolveShortIdReadOnly } from '../../task/short-id.ts';
 
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
 
-type SandboxControlEnvironmentClassification = Readonly<{
-  kind: 'direct' | 'controlled' | 'invalid';
-  mode?: 'task-bound' | 'branch-only';
-  code?: 'TASK_CONTROL_TRANSPORT_INVALID';
-  message?: string;
-}>;
-
-export function classifySandboxControlEnvironment(
-  env: NodeJS.ProcessEnv = process.env
-): SandboxControlEnvironmentClassification {
-  const controlKeys = [
-    'AGENT_INFRA_CONTROL_TOKEN',
-    'AGENT_INFRA_CONTROL_GENERATION',
-    'AGENT_INFRA_CONTROL_DIR',
-    'AGENT_INFRA_CONTROL_STATUS_DIR'
-  ] as const;
-  const hasControlMarker = controlKeys.some((key) => Boolean(env[key]));
-  const hasTaskIdentity = Boolean(env.AGENT_INFRA_TASK_ID);
-  const hasRuntime = Boolean(env.AGENT_INFRA_RUNTIME_DIR);
-  const hasExecutorMarker = Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST);
-  const hasControllerBinding = Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING);
-  const hasAnyMarker = hasControlMarker || hasTaskIdentity || hasRuntime || hasExecutorMarker || hasControllerBinding;
-  const hasCompleteControl = controlKeys.every((key) => Boolean(env[key]));
-
-  if (!hasAnyMarker) return { kind: 'direct' };
-  if (hasExecutorMarker) {
-    return {
-      kind: 'invalid',
-      code: 'TASK_CONTROL_TRANSPORT_INVALID',
-      message: 'executor context is only valid for sandbox-control execute'
-    };
-  }
-  if (hasControllerBinding) {
-    return {
-      kind: 'invalid',
-      code: 'TASK_CONTROL_TRANSPORT_INVALID',
-      message: 'sandbox client control configuration is incomplete or conflicting'
-    };
-  }
-  if (!hasCompleteControl) {
-    return {
-      kind: 'invalid',
-      code: 'TASK_CONTROL_TRANSPORT_INVALID',
-      message: 'sandbox client control configuration is incomplete or conflicting'
-    };
-  }
-  if (hasTaskIdentity !== hasRuntime) {
-    return {
-      kind: 'invalid',
-      code: 'TASK_CONTROL_TRANSPORT_INVALID',
-      message: 'sandbox task identity and runtime binding must be provided together'
-    };
-  }
-  return { kind: 'controlled', mode: hasTaskIdentity ? 'task-bound' : 'branch-only' };
-}
-
 export class SandboxControlClientError extends Error {
   readonly detail: SandboxControlError;
   readonly accepted: boolean;
@@ -109,12 +59,6 @@ function clientError(
   throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted, requestId);
 }
 
-function hasTaskBoundMarker(env: NodeJS.ProcessEnv = process.env): boolean {
-  return Boolean(env.AGENT_INFRA_TASK_ID)
-    && Boolean(env.AGENT_INFRA_CONTROL_TOKEN || env.AGENT_INFRA_CONTROL_GENERATION
-      || env.AGENT_INFRA_CONTROL_STATUS_DIR || env.AGENT_INFRA_RUNTIME_DIR || env.AGENT_INFRA_CONTROL_DIR);
-}
-
 function preflight(
   statusDir: string,
   generation: string,
@@ -122,6 +66,23 @@ function preflight(
   now = Date.now(),
   env: NodeJS.ProcessEnv = process.env
 ): void {
+  if (fs.existsSync(statusDir)) {
+    let identity;
+    try {
+      identity = readSandboxControlIdentitySentinel(statusDir);
+    } catch (error) {
+      const code = error instanceof Error && error.message.endsWith('MISSING')
+        ? 'SANDBOX_CONTROL_IDENTITY_MISSING'
+        : 'SANDBOX_CONTROL_IDENTITY_MALFORMED';
+      clientError(code, 'sandbox control identity is missing or invalid', false);
+    }
+    if (identity.generation !== generation) {
+      clientError('SANDBOX_CONTROL_IDENTITY_GENERATION_MISMATCH', 'sandbox control identity generation does not match the request', false);
+    }
+    if (env.AGENT_INFRA_CONTROL_ROOT_ID && identity.controlRootId !== env.AGENT_INFRA_CONTROL_ROOT_ID) {
+      clientError('SANDBOX_CONTROL_IDENTITY_ROOT_ID_MISMATCH', 'sandbox control identity root does not match the client configuration', false);
+    }
+  }
   let status;
   try {
     status = readSandboxControlStatus(statusDir);
@@ -159,6 +120,7 @@ function preflight(
 function taskViewEffectForRequest(request: SandboxControlRequest): TaskViewAccessEffect | null {
   if (request.family === 'task-lifecycle' || request.family === 'task-finalization') return 'progress';
   if (request.family === 'task-orchestration') return request.args[1] === 'status' ? 'diagnostic' : 'progress';
+  if (request.family === 'task-workflow') return request.workflow.operation === 'artifact-inspect' || request.workflow.operation === 'decision-next-id' ? 'diagnostic' : 'progress';
   return null;
 }
 
@@ -204,6 +166,44 @@ function cancelPendingRequest(requestPath: string): boolean {
   }
 }
 
+const CONTROL_TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const CONTROL_SHORT_ID_RE = /^\d+$/;
+
+type CanonicalRequestTask =
+  | Readonly<{ kind: 'none' }>
+  | Readonly<{ kind: 'task'; taskId: string }>
+  | Readonly<{ kind: 'unresolved' }>;
+
+// Use the current short-id contract for the first visible active registry.
+export function resolveVisibleActiveShortId(ref: string): string | null {
+  let dir = process.cwd();
+  for (let depth = 0; depth < 64; depth += 1) {
+    const registryPath = path.join(dir, '.agents', 'workspace', 'active', '.short-ids.json');
+    if (fs.existsSync(registryPath)) {
+      const resolved = resolveShortIdReadOnly(ref, dir, { shortIdLength: configuredShortIdLength(dir) });
+      return resolved.ok ? resolved.taskId : null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// A request's leading argument is only a task reference for some families and
+// may be a documented short id. Compare canonical ids so a bound sandbox keeps
+// refusing other tasks without rejecting its own task's short id.
+function canonicalRequestTask(request: SandboxControlRequest): CanonicalRequestTask {
+  const ref = request.family === 'task-workflow'
+    ? request.workflow.taskId
+    : 'args' in request ? request.args[0] ?? null : null;
+  if (!ref) return { kind: 'none' };
+  if (CONTROL_TASK_ID_RE.test(ref)) return { kind: 'task', taskId: ref };
+  if (!CONTROL_SHORT_ID_RE.test(ref)) return { kind: 'none' };
+  const resolved = resolveVisibleActiveShortId(ref);
+  return resolved ? { kind: 'task', taskId: resolved } : { kind: 'unresolved' };
+}
+
 function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly<{
   channelDir?: string;
   statusDir?: string;
@@ -213,6 +213,20 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
   const statusDir = params.statusDir ?? process.env.AGENT_INFRA_CONTROL_STATUS_DIR ?? '/run/agent-infra/control-status';
   const taskViewEffect = taskViewEffectForRequest(request);
   preflight(statusDir, request.generation, taskViewEffect);
+  const identityPath = path.join(statusDir, 'identity.json');
+  if (fs.existsSync(statusDir)) {
+    const identity = readSandboxControlIdentitySentinel(statusDir);
+    const requestTask = canonicalRequestTask(request);
+    if (identity.mode === 'task-bound'
+      && ((process.env.AGENT_INFRA_TASK_ID && process.env.AGENT_INFRA_TASK_ID !== identity.taskId)
+        || requestTask.kind === 'unresolved'
+        || (requestTask.kind === 'task' && requestTask.taskId !== identity.taskId))) {
+      clientError('SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH', 'request task does not match the sandbox identity', false);
+    }
+    if (identity.mode === 'branch-only' && (request.family === 'task-finalization' || request.family === 'task-workflow')) {
+      clientError('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks', false);
+    }
+  }
   const encoded = `${JSON.stringify(request)}\n`;
   if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
     clientError('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit', false, false, request.id);
@@ -370,7 +384,7 @@ export function requestSandboxControl(params: Readonly<{
   token?: string; generation?: string; timeoutMs?: number;
 }>): SandboxControlResponse {
   if (!isSandboxControlFamily(params.family)) clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' is not allowed`, false);
-  if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization') {
+  if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization' || params.family === 'task-workflow') {
     clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' requires a typed request`, false);
   }
   const auth = authority(params);
@@ -389,6 +403,7 @@ export function requestSandboxTaskControl(params: Readonly<{
   family: 'task-lifecycle' | 'task-orchestration';
   args: string[];
   controllerProof: CodexControllerLeaseProofV1 | null;
+  authority?: LifecycleAuthorityRequestV1;
   channelDir?: string;
   statusDir?: string;
   token?: string;
@@ -399,14 +414,15 @@ export function requestSandboxTaskControl(params: Readonly<{
   const issuedAt = Date.now();
   const request: SandboxTaskCommandRequest = {
     version: 3,
-    id: randomUUID(),
+    id: params.authority?.requestId ?? randomUUID(),
     ...auth,
     issuedAt,
     expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
     family: params.family,
     args: params.args,
     controllerProcess: null,
-    controllerProof: params.controllerProof
+    controllerProof: params.authority ? null : params.controllerProof,
+    ...(params.authority ? { authority: params.authority } : {})
   };
   return exchangeSandboxControl(request, params);
 }
@@ -439,6 +455,33 @@ export function requestSandboxTaskFinalization(params: Readonly<{
   return exchangeSandboxControl(request, params);
 }
 
+export function requestSandboxTaskWorkflow(params: Readonly<{
+  workflow: TaskWorkflowRequest;
+  channelDir?: string;
+  statusDir?: string;
+  token?: string;
+  generation?: string;
+  timeoutMs?: number;
+  authority?: LifecycleAuthorityRequestV1;
+}>): SandboxControlResponse {
+  const auth = authority(params);
+  const issuedAt = Date.now();
+  const request: SandboxTaskWorkflowRequest = {
+    version: 3,
+    id: params.workflow.id,
+    ...auth,
+    issuedAt,
+    expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+    family: 'task-workflow',
+    args: [],
+    controllerProcess: null,
+    controllerProof: null,
+    workflow: params.workflow,
+    ...(params.authority ? { authority: params.authority } : {})
+  };
+  return exchangeSandboxControl(request, params);
+}
+
 type CodexControllerClosed = Readonly<{
   version: 1;
   status: 'closed';