@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/host-control/path.js

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+export const HOST_CONTROL_DIRECTORY_MODE = 0o700;
+export const HOST_CONTROL_SOCKET_MODE = 0o600;
+export const HOST_CONTROL_WORKER_TOKEN_MODE = 0o600;
+function currentPlatform() {
+    if (process.platform === 'linux' || process.platform === 'darwin')
+        return process.platform;
+    return 'unsupported';
+}
+function validUid(uid) {
+    const resolved = uid ?? process.getuid?.();
+    if (!Number.isInteger(resolved) || resolved === undefined || resolved < 0) {
+        throw new Error('HOST_CONTROL_ENDPOINT_INVALID: uid is unavailable');
+    }
+    return resolved;
+}
+function validUsername(username) {
+    const resolved = username ?? os.userInfo({ encoding: 'utf8' }).username;
+    if (!/^[A-Za-z0-9._-]+$/u.test(resolved)) {
+        throw new Error('HOST_CONTROL_ENDPOINT_INVALID: username is invalid');
+    }
+    return resolved;
+}
+export function resolveHostControlEndpoint(options = {}) {
+    const platform = options.platform ?? currentPlatform();
+    if (platform === 'linux')
+        return `/run/user/${validUid(options.uid)}/agent-infra/host-control.sock`;
+    if (platform === 'darwin')
+        return path.posix.join('/Users', validUsername(options.username), 'Library', 'Application Support', 'agent-infra', 'run', 'host-control.sock');
+    throw new Error('HOST_CONTROL_UNSUPPORTED_PLATFORM');
+}
+export function hostControlWorkerTokenPath(endpoint) {
+    return `${endpoint}.worker-token`;
+}
+function assertWorkerTokenFile(tokenPath, uid = process.getuid?.()) {
+    const stat = fs.lstatSync(tokenPath);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error('HOST_CONTROL_WORKER_TOKEN_INVALID');
+    if ((stat.mode & 0o777) !== HOST_CONTROL_WORKER_TOKEN_MODE)
+        throw new Error('HOST_CONTROL_WORKER_TOKEN_MODE_INVALID');
+    if (uid !== undefined && stat.uid !== uid)
+        throw new Error('HOST_CONTROL_WORKER_TOKEN_OWNER_INVALID');
+    const token = fs.readFileSync(tokenPath, 'utf8').trim();
+    if (!/^[a-f0-9]{64}$/u.test(token))
+        throw new Error('HOST_CONTROL_WORKER_TOKEN_INVALID');
+    return token;
+}
+export function ensureHostControlWorkerToken(endpoint, uid = process.getuid?.()) {
+    const tokenPath = hostControlWorkerTokenPath(endpoint);
+    try {
+        return assertWorkerTokenFile(tokenPath, uid);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const token = randomBytes(32).toString('hex');
+    try {
+        const fd = fs.openSync(tokenPath, 'wx', HOST_CONTROL_WORKER_TOKEN_MODE);
+        try {
+            fs.writeFileSync(fd, `${token}\n`, 'utf8');
+            fs.fchmodSync(fd, HOST_CONTROL_WORKER_TOKEN_MODE);
+            if (uid !== undefined && process.getuid?.() === uid)
+                fs.fchownSync(fd, uid, process.getgid?.() ?? -1);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return assertWorkerTokenFile(tokenPath, uid);
+}
+export function readHostControlWorkerToken(endpoint, uid = process.getuid?.()) {
+    return assertWorkerTokenFile(hostControlWorkerTokenPath(endpoint), uid);
+}
+export function removeHostControlWorkerToken(endpoint) {
+    try {
+        fs.unlinkSync(hostControlWorkerTokenPath(endpoint));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+export function inspectHostControlEndpoint(endpoint, expected = {}) {
+    let endpointStat;
+    let parentStat;
+    try {
+        endpointStat = fs.lstatSync(endpoint);
+        parentStat = fs.lstatSync(path.dirname(endpoint));
+    }
+    catch {
+        return { ok: false, code: 'HOST_CONTROL_ENDPOINT_MISSING' };
+    }
+    if (endpointStat.isSymbolicLink())
+        return { ok: false, code: 'HOST_CONTROL_ENDPOINT_SYMLINK' };
+    if (!endpointStat.isSocket())
+        return { ok: false, code: 'HOST_CONTROL_ENDPOINT_NOT_SOCKET' };
+    if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) {
+        return { ok: false, code: 'HOST_CONTROL_PARENT_INVALID' };
+    }
+    let ancestor = path.dirname(endpoint);
+    while (true) {
+        let stat;
+        try {
+            stat = fs.lstatSync(ancestor);
+        }
+        catch {
+            return { ok: false, code: 'HOST_CONTROL_PARENT_INVALID' };
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return { ok: false, code: 'HOST_CONTROL_PARENT_INVALID' };
+        const next = path.dirname(ancestor);
+        if (next === ancestor)
+            break;
+        ancestor = next;
+    }
+    const mode = endpointStat.mode & 0o777;
+    const parentMode = parentStat.mode & 0o777;
+    if (mode !== HOST_CONTROL_SOCKET_MODE)
+        return { ok: false, code: 'HOST_CONTROL_ENDPOINT_MODE_INVALID', ownerUid: endpointStat.uid, mode, parentMode };
+    if (parentMode !== HOST_CONTROL_DIRECTORY_MODE)
+        return { ok: false, code: 'HOST_CONTROL_PARENT_MODE_INVALID', ownerUid: endpointStat.uid, mode, parentMode };
+    if (expected.uid !== undefined && endpointStat.uid !== expected.uid) {
+        return { ok: false, code: 'HOST_CONTROL_ENDPOINT_OWNER_INVALID', ownerUid: endpointStat.uid, mode, parentMode };
+    }
+    if (expected.uid !== undefined && parentStat.uid !== expected.uid) {
+        return { ok: false, code: 'HOST_CONTROL_PARENT_OWNER_INVALID', ownerUid: parentStat.uid, mode, parentMode };
+    }
+    return { ok: true, code: null, ownerUid: endpointStat.uid, mode, parentMode };
+}
+export function prepareHostControlDirectory(endpoint, uid = process.getuid?.()) {
+    const directory = path.dirname(endpoint);
+    const segments = path.resolve(directory).split(path.sep);
+    let current = path.isAbsolute(directory) ? path.sep : '';
+    for (const segment of segments.filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = fs.lstatSync(current);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error('HOST_CONTROL_PARENT_INVALID');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    fs.mkdirSync(directory, { recursive: true, mode: HOST_CONTROL_DIRECTORY_MODE });
+    fs.chmodSync(directory, HOST_CONTROL_DIRECTORY_MODE);
+    if (uid !== undefined && process.getuid?.() === uid)
+        fs.chownSync(directory, uid, process.getgid?.() ?? -1);
+    return directory;
+}
+//# sourceMappingURL=path.js.map

package/dist/lib/host-control/secure-fs.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+const NO_FOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
+export class SecureFileError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = 'SecureFileError';
+        this.code = code;
+    }
+}
+function conflict(message) {
+    throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', message);
+}
+function sameStat(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+function assertNoSymlinkAncestors(candidate) {
+    let current = path.dirname(candidate);
+    while (true) {
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            conflict('candidate parent is not a real directory');
+        const parent = path.dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+export async function readStableFile(candidate, options) {
+    return readStableFileSync(candidate, options);
+}
+/** Shared bounded reader for synchronous domain commands and async workflow callers. */
+export function readStableFileSync(candidate, options) {
+    if (!path.isAbsolute(candidate)) {
+        conflict('candidate path must be absolute and terminal');
+    }
+    assertNoSymlinkAncestors(candidate);
+    let descriptor;
+    try {
+        // O_NONBLOCK lets fstat reject a FIFO even when it has no writer.
+        descriptor = fs.openSync(candidate, fs.constants.O_RDONLY | NO_FOLLOW | (fs.constants.O_NONBLOCK ?? 0));
+        const before = fs.fstatSync(descriptor, { bigint: true });
+        if (!before.isFile())
+            conflict('candidate is not a regular file');
+        if (before.size > BigInt(options.maxBytes))
+            conflict('candidate exceeds the bounded read limit');
+        const bytes = Buffer.alloc(Number(before.size));
+        let offset = 0;
+        while (offset < bytes.length) {
+            const bytesRead = fs.readSync(descriptor, bytes, offset, bytes.length - offset, offset);
+            if (bytesRead === 0)
+                conflict('candidate reached EOF before the bounded read completed');
+            offset += bytesRead;
+        }
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (!sameStat(before, after))
+            conflict('candidate identity or metadata changed during read');
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256) {
+            conflict('candidate digest does not match the expected digest');
+        }
+        return { bytes, sha256, stat: after };
+    }
+    catch (error) {
+        if (error instanceof SecureFileError)
+            throw error;
+        const code = error.code;
+        if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL') {
+            conflict('candidate terminal is not a stable non-symlink file');
+        }
+        throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha256) {
+    const parent = path.dirname(target);
+    let current = path.resolve(parent);
+    while (true) {
+        let stat;
+        try {
+            stat = await fs.promises.lstat(current);
+        }
+        catch {
+            throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is missing');
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is not a real directory');
+        }
+        const next = path.dirname(current);
+        if (next === current)
+            break;
+        current = next;
+    }
+    try {
+        const existing = await fs.promises.lstat(target);
+        if (existing.isSymbolicLink() || !existing.isFile()) {
+            throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const temporary = path.join(parent, `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    let handle;
+    try {
+        handle = await fs.promises.open(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, mode);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.chmod(mode);
+        await handle.close();
+        handle = undefined;
+        // Check after all asynchronous preparation; keep the final check/rename adjacent.
+        if (expectedSha256 !== undefined)
+            readStableFileSync(target, { maxBytes: 1024 * 1024, expectedSha256 });
+        fs.renameSync(temporary, target);
+        const directory = await fs.promises.open(parent, fs.constants.O_RDONLY | DIRECTORY);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await fs.promises.rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=secure-fs.js.map

package/dist/lib/host-control/server.js

@@ -0,0 +1,159 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import { createHash } from 'node:crypto';
+import { HOST_CONTROL_DIRECTORY_MODE, HOST_CONTROL_SOCKET_MODE, ensureHostControlWorkerToken, inspectHostControlEndpoint, prepareHostControlDirectory, removeHostControlWorkerToken, resolveHostControlEndpoint } from './path.js';
+import { HOST_CONTROL_MAX_REQUEST_BYTES, validateHostControlRequest } from './client.js';
+import { acquireFileLock } from '../fs/file-lock.js';
+import { appendHostControlAudit } from './audit.js';
+function auditFor(request, phase, outcome) {
+    return {
+        requestId: request.id,
+        taskId: request.taskId,
+        operation: request.operation,
+        scope: request.scope,
+        phase,
+        outcome,
+        authorityKind: 'host-broker',
+        transportKind: 'host-fixed-transport',
+        identityDigest: createHash('sha256').update(`${request.taskId ?? '-'}\0${request.generation ?? '-'}`, 'utf8').digest('hex')
+    };
+}
+function failedResponse(id, status, code, message) {
+    const error = { code, message };
+    const stdout = `${JSON.stringify({ status: 'failed', changed: status === 'rejected' ? false : null, error })}\n`;
+    return { version: 1, id, status, exitCode: 1, stdout, stderr: '', error };
+}
+async function handleConnection(socket, options) {
+    await new Promise((resolve) => {
+        let input = '';
+        let completed = false;
+        let processing = false;
+        socket.setEncoding('utf8');
+        // A disconnected caller does not cancel an already dispatched domain operation.
+        socket.on('error', () => socket.destroy());
+        socket.on('close', () => { if (!processing)
+            resolve(); });
+        socket.on('end', () => { if (!processing)
+            socket.end(); });
+        const finish = (value) => {
+            if (completed || socket.destroyed)
+                return;
+            completed = true;
+            socket.end(`${JSON.stringify(value)}\n`);
+        };
+        socket.on('data', async (chunk) => {
+            if (completed || processing)
+                return;
+            input += chunk;
+            if (Buffer.byteLength(input, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES) {
+                finish(failedResponse('invalid', 'rejected', 'HOST_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit'));
+                return;
+            }
+            const newline = input.indexOf('\n');
+            if (newline < 0)
+                return;
+            const raw = input.slice(0, newline);
+            let request;
+            try {
+                request = validateHostControlRequest(JSON.parse(raw));
+            }
+            catch (error) {
+                finish(failedResponse('invalid', 'rejected', 'HOST_CONTROL_REQUEST_INVALID', error instanceof Error ? error.message : String(error)));
+                return;
+            }
+            processing = true;
+            let started = false;
+            try {
+                options.audit?.(auditFor(request, 'accepted', 'in-progress'));
+                started = true;
+                const result = await options.dispatch(request);
+                options.audit?.(auditFor(request, 'completed', result.exitCode === 0 ? 'success' : 'failure'));
+                finish({ version: 1, id: request.id, status: 'completed', ...result, error: null });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'HOST_CONTROL_DISPATCH_FAILED';
+                const status = started ? 'unknown' : 'rejected';
+                try {
+                    options.audit?.(auditFor(request, started ? 'completed' : 'rejected', status));
+                }
+                catch { /* Return the uncertainty even when the audit sink is unavailable. */ }
+                finish(failedResponse(request.id, status, code, message));
+            }
+            finally {
+                resolve();
+            }
+        });
+    });
+}
+export async function startHostControlServer(options) {
+    const endpoint = options.endpoint ?? resolveHostControlEndpoint();
+    const audit = options.audit ?? ((entry) => appendHostControlAudit(endpoint, entry));
+    prepareHostControlDirectory(endpoint);
+    const lock = acquireFileLock(`${endpoint}.lock`);
+    let server;
+    try {
+        ensureHostControlWorkerToken(endpoint);
+        try {
+            const existing = fs.lstatSync(endpoint);
+            if (existing.isSymbolicLink() || !existing.isSocket())
+                throw new Error('HOST_CONTROL_ENDPOINT_INVALID');
+            fs.unlinkSync(endpoint);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const connections = new Set();
+        server = net.createServer({ allowHalfOpen: true }, (socket) => {
+            const connection = handleConnection(socket, { ...options, audit });
+            connections.add(connection);
+            void connection.finally(() => connections.delete(connection));
+        });
+        const listeningServer = server;
+        await new Promise((resolve, reject) => {
+            listeningServer.once('error', reject);
+            listeningServer.listen(endpoint, () => { listeningServer.off('error', reject); resolve(); });
+        });
+        fs.chmodSync(endpoint, HOST_CONTROL_SOCKET_MODE);
+        const inspection = inspectHostControlEndpoint(endpoint, { uid: process.getuid?.() });
+        if (!inspection.ok) {
+            await new Promise((resolve) => listeningServer.close(() => resolve()));
+            removeHostControlWorkerToken(endpoint);
+            throw new Error(inspection.code ?? 'HOST_CONTROL_ENDPOINT_INVALID');
+        }
+        let closing;
+        return {
+            endpoint,
+            server,
+            close: () => closing ??= (async () => {
+                try {
+                    await new Promise((resolve) => listeningServer.close(() => resolve()));
+                    await Promise.all(connections);
+                    await fs.promises.rm(endpoint, { force: true });
+                    removeHostControlWorkerToken(endpoint);
+                }
+                finally {
+                    lock.release();
+                }
+            })()
+        };
+    }
+    catch (error) {
+        if (server?.listening)
+            await new Promise((resolve) => server.close(() => resolve()));
+        lock.release();
+        throw error;
+    }
+}
+export async function serveHostControl(options, signal) {
+    const running = await startHostControlServer(options);
+    if (!signal)
+        return;
+    if (signal.aborted) {
+        await running.close();
+        return;
+    }
+    await new Promise((resolve) => signal.addEventListener('abort', () => { void running.close().then(resolve); }, { once: true }));
+}
+//# sourceMappingURL=server.js.map

package/dist/lib/host-control/service.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inspectHostControlEndpoint, resolveHostControlEndpoint } from './path.js';
+import { serveHostControl, startHostControlServer } from './server.js';
+function servicePlatform() {
+    if (process.platform === 'linux' || process.platform === 'darwin')
+        return process.platform;
+    return 'unsupported';
+}
+function serviceEntryPoint() {
+    const compiled = fileURLToPath(new URL('../../bin/internal-cli.js', import.meta.url));
+    if (fs.existsSync(compiled))
+        return fs.realpathSync.native(compiled);
+    const candidate = process.argv[1];
+    if (candidate && fs.existsSync(candidate))
+        return fs.realpathSync.native(candidate);
+    return fs.realpathSync.native(fileURLToPath(new URL('../../bin/internal-cli.ts', import.meta.url)));
+}
+function xml(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+function systemdArgument(value) {
+    const escaped = value.replace(/[\\"]/g, '\\$&')
+        .replace(/[\x00-\x1f\x7f]/g, (character) => `\\x${character.charCodeAt(0).toString(16).padStart(2, '0')}`)
+        .replaceAll('%', '%%');
+    return `"${escaped}"`;
+}
+function servicePaths(platform = servicePlatform()) {
+    if (platform === 'linux')
+        return { unit: path.join(os.homedir(), '.config', 'systemd', 'user', 'agent-infra-host-control.service') };
+    if (platform === 'darwin')
+        return { plist: path.join(os.homedir(), 'Library', 'LaunchAgents', 'com.fitlab-ai.agent-infra.host-control.plist') };
+    throw new Error('HOST_CONTROL_UNSUPPORTED_PLATFORM');
+}
+export function installHostControlService(platform = servicePlatform()) {
+    const paths = servicePaths(platform);
+    const entry = serviceEntryPoint();
+    if (paths.unit) {
+        // mkdir only applies mode to directories it creates, and this one usually
+        // already exists, so restate the intended mode explicitly.
+        fs.mkdirSync(path.dirname(paths.unit), { recursive: true, mode: 0o700 });
+        fs.chmodSync(path.dirname(paths.unit), 0o700);
+        fs.writeFileSync(paths.unit, [
+            '[Unit]',
+            'Description=agent-infra host-control service',
+            '',
+            '[Service]',
+            // The ':' executable prefix disables environment expansion for literal paths.
+            `ExecStart=${systemdArgument(`:${process.execPath}`)} ${systemdArgument(entry)} host-control serve`,
+            'Restart=on-failure',
+            'NoNewPrivileges=true',
+            // Workers receive host paths, including working directories and inputs under /tmp.
+            'PrivateTmp=false',
+            '',
+            '[Install]',
+            'WantedBy=default.target',
+            ''
+        ].join('\n'), { mode: 0o600 });
+        fs.chmodSync(paths.unit, 0o600);
+        return paths.unit;
+    }
+    const plist = paths.plist;
+    fs.mkdirSync(path.dirname(plist), { recursive: true, mode: 0o700 });
+    fs.chmodSync(path.dirname(plist), 0o700);
+    const argumentsXml = [process.execPath, entry, 'host-control', 'serve']
+        .map((argument) => `    <string>${xml(argument)}</string>`)
+        .join('\n');
+    fs.writeFileSync(plist, [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        '  <key>Label</key>',
+        '  <string>com.fitlab-ai.agent-infra.host-control</string>',
+        '  <key>ProgramArguments</key>',
+        '  <array>',
+        argumentsXml,
+        '  </array>',
+        '  <key>RunAtLoad</key>',
+        '  <true/>',
+        '  <key>KeepAlive</key>',
+        '  <true/>',
+        '</dict>',
+        '</plist>',
+        ''
+    ].join('\n'), { mode: 0o600 });
+    fs.chmodSync(plist, 0o600);
+    return plist;
+}
+export function uninstallHostControlService(platform = servicePlatform()) {
+    const paths = servicePaths(platform);
+    const target = paths.unit ?? paths.plist;
+    fs.rmSync(target, { force: true });
+    return target;
+}
+export function hostControlServiceEndpoint(options = {}) {
+    return options.endpoint ?? resolveHostControlEndpoint(options);
+}
+export async function startHostControlService(options) {
+    return startHostControlServer({ endpoint: hostControlServiceEndpoint(options), dispatch: options.dispatch, ...(options.audit ? { audit: options.audit } : {}) });
+}
+export async function serveHostControlService(options, signal) {
+    await serveHostControl({ endpoint: hostControlServiceEndpoint(options), dispatch: options.dispatch, ...(options.audit ? { audit: options.audit } : {}) }, signal);
+}
+export function hostControlServiceStatus(options = {}) {
+    const endpoint = hostControlServiceEndpoint(options);
+    const result = inspectHostControlEndpoint(endpoint, { uid: options.uid ?? process.getuid?.() });
+    return { endpoint, available: result.ok, code: result.code };
+}
+//# sourceMappingURL=service.js.map

package/dist/lib/init.js

@@ -17,6 +17,7 @@ const PLATFORM_DEFAULT_ENGINES = Object.freeze({
     darwin: 'colima',
     win32: 'wsl2'
 });
+const DEMO_PLATFORM_ENV = 'AGENT_INFRA_DEMO_PLATFORM';
 function detectProjectName() {
     try {
         const url = execSync('git remote get-url origin', { stdio: ['pipe', 'pipe', 'pipe'] })
@@ -45,6 +46,12 @@ function detectOrgName() {
     }
     return '';
 }
+function resolveInitPlatform() {
+    const override = process.env[DEMO_PLATFORM_ENV];
+    if (override === 'linux' || override === 'darwin' || override === 'win32')
+        return override;
+    return platform();
+}
 const VALID_NAME_RE = /^[a-zA-Z0-9_.@-]+$/;
 function parseLocalSources(input) {
     return input
@@ -109,7 +116,7 @@ async function cmdInit() {
         process.exitCode = 1;
         return;
     }
-    const currentPlatform = platform();
+    const currentPlatform = resolveInitPlatform();
     const defaultEngine = PLATFORM_DEFAULT_ENGINES[currentPlatform];
     const engineChoices = enginesForPlatform(currentPlatform).sort((left, right) => {
         if (left === defaultEngine)
@@ -207,6 +214,8 @@ async function cmdInit() {
     ok('Installed .agents/skills/update-agent-infra/');
     renderFile(path.join(templateDir, '.agents', 'scripts', 'lib', 'agent-infra-package.js'), path.join('.agents', 'scripts', 'lib', 'agent-infra-package.js'), replacements);
     ok('Installed .agents/scripts/lib/agent-infra-package.js');
+    renderFile(path.join(templateDir, '.agents', 'scripts', 'package.json'), path.join('.agents', 'scripts', 'package.json'), replacements);
+    ok('Installed .agents/scripts/package.json');
     const reconcileResult = applyAgentClientReconciliation(workflowPlan);
     for (const target of reconcileResult.applied)
         ok(`Installed ${target}`);
@@ -235,5 +244,5 @@ async function cmdInit() {
         console.log('');
     }
 }
-export { cmdInit };
+export { cmdInit, resolveInitPlatform };
 //# sourceMappingURL=init.js.map

package/dist/lib/internal/cli-route-inventory.js

@@ -33,6 +33,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'task-create': ['input'],
     'task-qualification': ['proposal', 'confirm', 'supersede', 'revoke'],
     'sandbox-control': ['serve', 'execute', 'recover', 'client'],
+    'host-control': ['serve', 'status', 'install', 'uninstall'],
     'agent-client': ['next-steps', 'model-selection'],
     'codex-lifecycle': ['preflight', 'capability-arm', 'hook-event', 'resolve-start', 'resolve-stop', 'consume'],
     'codex-sandbox-controller': ['verify-context', 'run'],
@@ -53,7 +54,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert'],
     'task-warning': ['list', 'add', 'set-status'],
     'task-activity': ['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate'],
-    'task-artifact': ['inspect', 'init', 'repair', 'finalize-local'],
+    'task-artifact': ['inspect', 'init', 'finalize-local'],
     'task-orchestration': ['status', 'progress'],
     'task-review': ['finalize-summary'],
     'task-event': ['event'],
@@ -64,7 +65,8 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'task-short-id': ['list', 'list-verify', 'alloc', 'release', 'resolve'],
     'task-snapshot': ['snapshot'],
     'task-verify': ['event'],
-    'task-validate': ['snapshot', 'inplace']
+    'task-validate': ['snapshot', 'inplace'],
+    'manual-validation': ['transaction']
 });
 export const INTERNAL_CLI_ROUTE_SELECTORS = INTERNAL_HANDLER_ROUTE_SELECTORS;
 function first(args) {

package/dist/lib/internal/codex-lifecycle.js

@@ -191,7 +191,7 @@ async function codexLifecycle(args = []) {
             output({
                 status: 'armed',
                 changed: true,
-                capabilityToken: armed.token,
+                capabilityRef: armed.capabilityRef,
                 marker: armed.marker,
                 expiresAt: armed.expiresAt,
                 buildIdentity: armed.buildIdentity,
@@ -210,12 +210,12 @@ async function codexLifecycle(args = []) {
             }
             const payload = await readStdin();
             if (phase === 'post-tool') {
-                const capabilityToken = payloadText(payload, 'capabilityToken');
-                if (capabilityToken) {
+                const capabilityRef = payloadText(payload, 'capabilityRef');
+                if (capabilityRef) {
                     const capabilityStore = createCodexCapabilityStore();
-                    const armed = capabilityStore.inspect(capabilityToken);
-                    const capability = createCodexCapabilityStore().attest({
-                        token: capabilityToken,
+                    const armed = capabilityStore.inspectReference(capabilityRef);
+                    const capability = capabilityStore.attestByReference({
+                        capabilityRef,
                         sessionId: payloadText(payload, 'sessionId'),
                         turnId: payloadText(payload, 'turnId'),
                         toolUseId: payloadText(payload, 'toolUseId'),