@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/dist/lib/sandbox/control/protocol.js

@@ -1,54 +1,97 @@
 import { validateTaskCreateCandidate } from '../../task/create.js';
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 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;
+export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
 export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'];
+export const DEFAULT_SANDBOX_CONTROL_TIMING = Object.freeze({
+    controlTickMs: 250,
+    parkedBindingInitialMs: 1_000,
+    slowCheckMs: 5_000,
+    containerHeartbeatMs: 5_000,
+    quiesceDeadlineMs: 7_000
+});
+export class SandboxControlProtocolError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(`${code}: ${message}`);
+        this.name = 'SandboxControlProtocolError';
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+function fail(code, message, retryable = false) {
+    throw new SandboxControlProtocolError(code, message, retryable);
+}
 export function isSandboxControlFamily(value) {
     return SANDBOX_CONTROL_FAMILIES.includes(value);
 }
-export function validateSandboxControlRequest(value, manifest) {
+export function validateSandboxControlRequest(value, manifest, options = {}) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request must be an object');
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request must be an object');
     }
     const request = value;
-    if (request.version !== 1
-        || typeof request.id !== 'string'
-        || !/^[a-f0-9-]{16,64}$/.test(request.id)
-        || request.token !== manifest.token
-        || typeof request.family !== 'string'
-        || !isSandboxControlFamily(request.family)) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+    if (request.version !== 2 || typeof request.id !== 'string'
+        || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
+        || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
+        || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt))
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+    if (request.generation !== manifest.generation) {
+        fail('SANDBOX_CONTROL_GENERATION_INVALID', 'request generation does not match the broker');
     }
+    const issuedAt = request.issuedAt;
+    const expiresAt = request.expiresAt;
+    const now = options.now ?? Date.now();
+    if (expiresAt <= issuedAt || expiresAt - issuedAt > SANDBOX_CONTROL_ADMISSION_WINDOW_MS || issuedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
+        fail('SANDBOX_CONTROL_REQUEST_DEADLINE_INVALID', 'request admission deadline is invalid');
+    }
+    if (now > expiresAt)
+        fail('SANDBOX_CONTROL_REQUEST_EXPIRED', 'request admission deadline has passed', true);
     if (Buffer.byteLength(JSON.stringify(request), 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_TOO_LARGE: request exceeds the control limit');
+        fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
     }
     if (request.family === 'task-create') {
-        const keys = Object.keys(request).sort().join(',');
-        if (keys !== ['candidate', 'family', 'id', 'token', 'version'].sort().join(',')) {
-            throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+        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');
         }
         return { ...request, candidate: validateTaskCreateCandidate(request.candidate) };
     }
-    const keys = Object.keys(request).sort().join(',');
-    if (keys !== ['args', 'family', 'id', 'token', 'version'].sort().join(',')
-        || !Array.isArray(request.args)
-        || !request.args.every((arg) => typeof arg === 'string')) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+    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 (manifest.mode !== 'task-bound' || !manifest.taskId) {
-        throw new Error('SANDBOX_CONTROL_BRANCH_ONLY: branch-only sandboxes cannot coordinate tasks');
+        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.family === 'task-orchestration'
         && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: worktree binding is reserved for the control broker');
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'worktree binding is reserved for the control broker');
     }
     return request;
 }
 export function bindSandboxControlTask(request, taskId) {
-    if (request.family === 'task-create') {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: task-create requests do not bind a current task');
-    }
-    if (request.args.length === 0) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: command arguments are required');
-    }
+    if (request.family === 'task-create')
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create 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)];
 }
+export function controlError(error) {
+    if (error instanceof SandboxControlProtocolError) {
+        return { code: error.code, message: error.message, retryable: error.retryable };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'SANDBOX_CONTROL_INTERNAL_ERROR';
+    const retryable = new Set([
+        'SANDBOX_CONTROL_BUSY',
+        'SANDBOX_CONTROL_HANDOFF_ACTIVE',
+        'SANDBOX_CONTROL_REQUEST_EXPIRED',
+        'SANDBOX_WORKTREE_BINDING_LOST'
+    ]).has(code);
+    return { code, message, retryable };
+}
 //# sourceMappingURL=protocol.js.map