@fitlab-ai/agent-infra 0.9.5 → 0.9.6

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

@@ -1,54 +1,90 @@
 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 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

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

@@ -1,28 +1,12 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getProcessStartTime } from '../../server/process-state.js';
-import { createTask } from '../../task/create-service.js';
 import { assertGitWorktreeBinding } from '../../git/worktree-identity.js';
-import { bindSandboxControlTask, validateSandboxControlRequest } from './protocol.js';
-function readManifest(manifestPath) {
-    const stat = fs.lstatSync(manifestPath);
-    if (!stat.isFile() || stat.isSymbolicLink())
-        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    if (manifest.version !== 2) {
-        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 2; recreate the sandbox');
-    }
-    if (typeof manifest.repoRoot !== 'string'
-        || typeof manifest.worktreeRoot !== 'string'
-        || typeof manifest.channelDir !== 'string'
-        || typeof manifest.token !== 'string')
-        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-    if (path.resolve(manifest.channelDir) !== path.join(path.dirname(path.resolve(manifestPath)), 'channel')) {
-        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-    }
-    return manifest;
-}
+import { controlError, SANDBOX_CONTROL_STATUS_INTERVAL_MS } from './protocol.js';
+import { prepareSandboxControlExecution } from './executor.js';
+import { appendSandboxControlAudit, atomicWriteJson, cleanupStaleSandboxControlLease, executionPath, readActiveLease, readExecution, terminateSandboxControlExecution, writeSandboxControlStatus } from './state.js';
+import { validateSandboxControlRequest } from './protocol.js';
+import { acquireSandboxControlBrokerStartup, isSandboxControlRootQuiescing, readSandboxControlManifest } from './lifecycle.js';
 function assertRealDirectory(directory, parent) {
     const stat = fs.lstatSync(directory);
     if (!stat.isDirectory() || stat.isSymbolicLink())
@@ -31,114 +15,250 @@ function assertRealDirectory(directory, parent) {
         throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     }
 }
-function writeResponse(directory, response) {
-    const temporary = path.join(directory, `.${response.id}.tmp`);
-    fs.writeFileSync(temporary, `${JSON.stringify(response)}\n`, { mode: 0o600, flag: 'wx' });
-    fs.renameSync(temporary, path.join(directory, `${response.id}.json`));
+function responsePath(manifest, id) {
+    return path.join(manifest.channelDir, 'responses', `${id}.json`);
 }
-export function sandboxControlSafeEnv(env = process.env) {
-    return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
+function writeResponse(manifest, response) {
+    atomicWriteJson(responsePath(manifest, response.id), response);
+}
+function rejected(id, error) {
+    const detail = controlError(error);
+    return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${detail.message}\n`, error: detail };
+}
+function unknown(id) {
+    const error = {
+        code: 'SANDBOX_CONTROL_RESULT_UNKNOWN',
+        message: 'SANDBOX_CONTROL_RESULT_UNKNOWN: accepted execution ended without a provable result; inspect domain state before retrying',
+        retryable: false
+    };
+    return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${error.message}\n`, error };
+}
+function notExecuted(id) {
+    const error = {
+        code: 'SANDBOX_CONTROL_NOT_EXECUTED',
+        message: 'SANDBOX_CONTROL_NOT_EXECUTED: request was claimed but never accepted; retry with a new request id',
+        retryable: true
+    };
+    return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${error.message}\n`, error };
 }
 function consumeRequest(directory, id) {
     try {
         fs.writeFileSync(path.join(directory, id), '', { flag: 'wx', mode: 0o600 });
     }
     catch (error) {
-        if (error.code === 'EEXIST') {
+        if (error.code === 'EEXIST')
             throw new Error('SANDBOX_CONTROL_REQUEST_REPLAYED');
-        }
         throw error;
     }
 }
-export function serveSandboxControl(manifestPath, signal = new AbortController().signal) {
-    const manifest = readManifest(manifestPath);
-    assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
-    const brokerPath = path.join(path.dirname(manifestPath), 'broker.json');
+function claimRequest(manifest, requestPath, id) {
+    const directory = path.join(manifest.processingDir, id);
+    fs.mkdirSync(directory, { mode: 0o700 });
+    const claimed = path.join(directory, 'request.json');
+    try {
+        fs.renameSync(requestPath, claimed);
+        return claimed;
+    }
+    catch (error) {
+        fs.rmSync(directory, { recursive: true, force: true });
+        throw error;
+    }
+}
+function bindingReason(manifest) {
+    try {
+        assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
+        return null;
+    }
+    catch {
+        return 'SANDBOX_WORKTREE_BINDING_LOST';
+    }
+}
+function recoverProcessing(manifest) {
+    for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^[a-f0-9-]{16,64}$/.test(entry.name))
+            continue;
+        const descriptor = executionPath(manifest, entry.name);
+        const existingResponse = responsePath(manifest, entry.name);
+        if (fs.existsSync(descriptor)) {
+            const execution = readExecution(descriptor);
+            if (!terminateSandboxControlExecution(execution)) {
+                throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+            }
+            appendSandboxControlAudit(manifest, 'orphan-tree-terminated', { requestId: entry.name });
+            let terminal = false;
+            if (fs.existsSync(existingResponse)) {
+                try {
+                    const response = JSON.parse(fs.readFileSync(existingResponse, 'utf8'));
+                    terminal = response.version === 2 && response.id === entry.name
+                        && (response.phase === 'completed' || response.phase === 'rejected');
+                }
+                catch {
+                    terminal = false;
+                }
+            }
+            if (!terminal)
+                writeResponse(manifest, unknown(entry.name));
+        }
+        else {
+            writeResponse(manifest, notExecuted(entry.name));
+        }
+        fs.rmSync(path.join(manifest.processingDir, entry.name), { recursive: true, force: true });
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function sandboxControlSafeEnv(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
+}
+export async function serveSandboxControl(manifestPath, signal = new AbortController().signal) {
+    const manifest = readSandboxControlManifest(manifestPath);
+    const root = path.dirname(manifestPath);
     const startTime = getProcessStartTime(process.pid);
     if (!startTime)
         throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
-    fs.writeFileSync(brokerPath, `${JSON.stringify({
-        version: 1,
-        pid: process.pid,
-        startTime,
-        token: manifest.token
-    })}\n`, { mode: 0o600, flag: 'wx' });
+    const releaseStartup = await acquireSandboxControlBrokerStartup(root, { pid: process.pid, startTime });
     const requestsDir = path.join(manifest.channelDir, 'requests');
     const responsesDir = path.join(manifest.channelDir, 'responses');
-    const consumedDir = path.join(path.dirname(manifestPath), 'consumed');
-    assertRealDirectory(manifest.channelDir);
-    fs.mkdirSync(requestsDir, { recursive: true, mode: 0o700 });
-    fs.mkdirSync(responsesDir, { recursive: true, mode: 0o700 });
-    fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
-    assertRealDirectory(requestsDir, manifest.channelDir);
-    assertRealDirectory(responsesDir, manifest.channelDir);
-    assertRealDirectory(consumedDir, path.dirname(manifestPath));
-    while (!signal.aborted) {
-        const current = readManifest(manifestPath);
-        if (current.token !== manifest.token)
-            return;
-        assertGitWorktreeBinding(current.repoRoot, current.worktreeRoot, current.branch);
+    const consumedDir = path.join(root, 'consumed');
+    const broker = { pid: process.pid, startTime };
+    const brokerPath = path.join(root, 'broker.json');
+    const brokerRecord = `${JSON.stringify({ version: 2, ...broker, token: manifest.token, generation: manifest.generation })}\n`;
+    try {
+        for (const directory of [manifest.channelDir, requestsDir, responsesDir, consumedDir, manifest.publicStatusDir, manifest.processingDir]) {
+            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        }
+        assertRealDirectory(manifest.channelDir);
         assertRealDirectory(requestsDir, manifest.channelDir);
         assertRealDirectory(responsesDir, manifest.channelDir);
-        for (const name of fs.readdirSync(requestsDir).sort()) {
-            if (!/^[a-f0-9-]{16,64}\.json$/.test(name))
-                continue;
-            const requestPath = path.join(requestsDir, name);
-            let id = name.slice(0, -5);
-            let response;
+        assertRealDirectory(consumedDir, root);
+        assertRealDirectory(manifest.publicStatusDir, root);
+        assertRealDirectory(manifest.processingDir, root);
+        fs.writeFileSync(brokerPath, brokerRecord, { mode: 0o600, flag: 'wx' });
+        if (isSandboxControlRootQuiescing(root)) {
+            if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord)
+                fs.unlinkSync(brokerPath);
+            return;
+        }
+    }
+    finally {
+        releaseStartup();
+    }
+    let active = null;
+    let lastState = '';
+    let lastStatusAt = 0;
+    try {
+        writeSandboxControlStatus(manifest, broker, 'starting', null, null);
+        appendSandboxControlAudit(manifest, 'broker-start', { pid: broker.pid });
+        recoverProcessing(manifest);
+        while (!signal.aborted) {
+            let current;
             try {
-                const stat = fs.lstatSync(requestPath);
-                if (!stat.isFile() || stat.isSymbolicLink())
-                    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID');
-                const request = validateSandboxControlRequest(JSON.parse(fs.readFileSync(requestPath, 'utf8')), manifest);
-                id = request.id;
-                consumeRequest(consumedDir, id);
-                if (request.family === 'task-create') {
-                    const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
-                    response = {
-                        version: 1, id,
-                        exitCode: result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0,
-                        stdout: `${JSON.stringify(result)}\n`, stderr: ''
-                    };
+                current = readSandboxControlManifest(manifestPath);
+            }
+            catch {
+                break;
+            }
+            if (current.token !== manifest.token || current.generation !== manifest.generation)
+                break;
+            if (active?.settled) {
+                if (active.result) {
+                    writeResponse(manifest, {
+                        version: 2, id: active.request.id, phase: 'completed', exitCode: active.result.exitCode,
+                        stdout: active.result.stdout, stderr: active.result.stderr, error: null
+                    });
                 }
                 else {
-                    const boundArgs = bindSandboxControlTask(request, manifest.taskId);
-                    if (request.family === 'task-orchestration') {
-                        boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
-                    }
-                    const result = spawnSync(process.execPath, ['--experimental-strip-types', '--no-warnings', process.argv[1], request.family, ...boundArgs], {
-                        cwd: manifest.repoRoot,
-                        encoding: 'utf8',
-                        env: sandboxControlSafeEnv()
-                    });
-                    response = {
-                        version: 1,
-                        id,
-                        exitCode: result.status ?? 1,
-                        stdout: result.stdout ?? '',
-                        stderr: result.stderr ?? ''
-                    };
+                    writeResponse(manifest, unknown(active.request.id));
                 }
+                fs.rmSync(path.join(manifest.processingDir, active.request.id), { recursive: true, force: true });
+                active = null;
             }
-            catch (error) {
-                response = {
-                    version: 1,
-                    id,
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `${error instanceof Error ? error.message : String(error)}\n`
-                };
-            }
+            let reasonCode = null;
             try {
-                fs.unlinkSync(requestPath);
-                writeResponse(responsesDir, response);
+                if (cleanupStaleSandboxControlLease(manifest)) {
+                    appendSandboxControlAudit(manifest, 'lease-stale-cleanup');
+                }
+                if (readActiveLease(manifest))
+                    reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
+            }
+            catch {
+                reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
+            }
+            reasonCode ??= bindingReason(manifest);
+            const state = reasonCode ? 'parked' : active ? 'busy' : 'healthy';
+            const stateKey = `${state}:${reasonCode ?? ''}:${active?.request.id ?? ''}`;
+            const now = Date.now();
+            if (stateKey !== lastState || now - lastStatusAt >= SANDBOX_CONTROL_STATUS_INTERVAL_MS) {
+                writeSandboxControlStatus(manifest, broker, state, reasonCode, active?.request.id ?? null, now);
+                lastStatusAt = now;
+            }
+            if (stateKey !== lastState) {
+                appendSandboxControlAudit(manifest, 'broker-state', { state, reasonCode, requestId: active?.request.id ?? null });
+                lastState = stateKey;
             }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
+            for (const name of fs.readdirSync(requestsDir).sort()) {
+                if (!/^[a-f0-9-]{16,64}\.json$/.test(name))
+                    continue;
+                const id = name.slice(0, -5);
+                const source = path.join(requestsDir, name);
+                let claimed = null;
+                try {
+                    claimed = claimRequest(manifest, source, id);
+                    consumeRequest(consumedDir, id);
+                    if (reasonCode)
+                        throw new Error(reasonCode);
+                    if (active)
+                        throw new Error('SANDBOX_CONTROL_BUSY');
+                    const request = validateSandboxControlRequest(JSON.parse(fs.readFileSync(claimed, 'utf8')), manifest);
+                    if (bindingReason(manifest))
+                        throw new Error('SANDBOX_WORKTREE_BINDING_LOST');
+                    if (readActiveLease(manifest))
+                        throw new Error('SANDBOX_CONTROL_HANDOFF_ACTIVE');
+                    const prepared = await prepareSandboxControlExecution({
+                        manifest, manifestPath, request, requestPath: claimed, internalCliPath: process.argv[1]
+                    });
+                    const execution = { request, prepared, result: null, failure: null, settled: false };
+                    active = execution;
+                    prepared.completion.then((result) => { execution.result = result; execution.settled = true; }, (error) => { execution.failure = error; execution.settled = true; });
+                    writeResponse(manifest, {
+                        version: 2, id, phase: 'accepted', exitCode: null, stdout: '', stderr: '', error: null
+                    });
+                    try {
+                        prepared.start();
+                    }
+                    catch (error) {
+                        prepared.terminate();
+                        writeResponse(manifest, unknown(id));
+                        fs.rmSync(path.join(manifest.processingDir, id), { recursive: true, force: true });
+                        active = null;
+                        claimed = null;
+                        appendSandboxControlAudit(manifest, 'executor-gate-failed', { requestId: id });
+                        continue;
+                    }
+                }
+                catch (error) {
+                    writeResponse(manifest, rejected(id, error));
+                    if (claimed)
+                        fs.rmSync(path.dirname(claimed), { recursive: true, force: true });
+                }
             }
+            await delay(25);
+        }
+    }
+    finally {
+        if (active) {
+            active.prepared.terminate();
+            writeResponse(manifest, unknown(active.request.id));
+        }
+        appendSandboxControlAudit(manifest, 'broker-stop', { pid: broker.pid });
+        try {
+            if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord)
+                fs.unlinkSync(brokerPath);
+        }
+        catch {
+            // A newer owner or recovery path owns the record.
         }
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
     }
 }
 //# sourceMappingURL=server.js.map