@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/host-control/server.ts

@@ -0,0 +1,180 @@
+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.ts';
+import {
+  HOST_CONTROL_MAX_REQUEST_BYTES,
+  validateHostControlRequest,
+  type HostControlRequest,
+  type HostControlResponse
+} from './client.ts';
+import { acquireFileLock } from '../fs/file-lock.ts';
+import { appendHostControlAudit } from './audit.ts';
+
+export type HostControlDispatch = (request: HostControlRequest) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+
+export type HostControlAudit = Readonly<{
+  requestId: string;
+  taskId: string | null;
+  operation: string;
+  scope: string;
+  phase: 'accepted' | 'completed' | 'rejected';
+  outcome: string;
+  authorityKind: 'host-broker';
+  transportKind: 'host-fixed-transport';
+  identityDigest: string;
+}>;
+
+export type HostControlServerOptions = Readonly<{
+  endpoint?: string;
+  dispatch: HostControlDispatch;
+  audit?: (entry: HostControlAudit) => void;
+}>;
+
+function auditFor(request: HostControlRequest, phase: HostControlAudit['phase'], outcome: string): HostControlAudit {
+  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: string, status: 'rejected' | 'unknown', code: string, message: string): HostControlResponse {
+  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: net.Socket, options: HostControlServerOptions): Promise<void> {
+  await new Promise<void>((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: HostControlResponse): void => {
+      if (completed || socket.destroyed) return;
+      completed = true;
+      socket.end(`${JSON.stringify(value)}\n`);
+    };
+    socket.on('data', async (chunk: string) => {
+      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: HostControlRequest;
+      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 type RunningHostControlServer = Readonly<{
+  endpoint: string;
+  server: net.Server;
+  close: () => Promise<void>;
+}>;
+
+export async function startHostControlServer(options: HostControlServerOptions): Promise<RunningHostControlServer> {
+  const endpoint = options.endpoint ?? resolveHostControlEndpoint();
+  const audit = options.audit ?? ((entry: HostControlAudit) => appendHostControlAudit(endpoint, entry));
+  prepareHostControlDirectory(endpoint);
+  const lock = acquireFileLock(`${endpoint}.lock`);
+  let server: net.Server | undefined;
+  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 as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    const connections = new Set<Promise<void>>();
+    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<void>((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<void>((resolve) => listeningServer.close(() => resolve()));
+      removeHostControlWorkerToken(endpoint);
+      throw new Error(inspection.code ?? 'HOST_CONTROL_ENDPOINT_INVALID');
+    }
+    let closing: Promise<void> | undefined;
+    return {
+      endpoint,
+      server,
+      close: () => closing ??= (async () => {
+        try {
+          await new Promise<void>((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<void>((resolve) => server!.close(() => resolve()));
+    lock.release();
+    throw error;
+  }
+}
+
+export async function serveHostControl(options: HostControlServerOptions, signal?: AbortSignal): Promise<void> {
+  const running = await startHostControlServer(options);
+  if (!signal) return;
+  if (signal.aborted) { await running.close(); return; }
+  await new Promise<void>((resolve) => signal.addEventListener('abort', () => { void running.close().then(resolve); }, { once: true }));
+}

package/lib/host-control/service.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  inspectHostControlEndpoint,
+  resolveHostControlEndpoint,
+  type HostControlPlatform
+} from './path.ts';
+import { serveHostControl, startHostControlServer, type HostControlDispatch, type RunningHostControlServer } from './server.ts';
+
+export type HostControlServiceOptions = Readonly<{
+  platform?: HostControlPlatform;
+  uid?: number;
+  username?: string;
+  endpoint?: string;
+  dispatch: HostControlDispatch;
+  audit?: Parameters<typeof startHostControlServer>[0]['audit'];
+}>;
+
+export type HostControlServicePlatform = 'linux' | 'darwin' | 'unsupported';
+
+function servicePlatform(): HostControlServicePlatform {
+  if (process.platform === 'linux' || process.platform === 'darwin') return process.platform;
+  return 'unsupported';
+}
+
+function serviceEntryPoint(): string {
+  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: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+
+function systemdArgument(value: string): string {
+  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: HostControlServicePlatform = servicePlatform()): Readonly<{ unit?: string; plist?: string }> {
+  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: HostControlServicePlatform = servicePlatform()): string {
+  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: HostControlServicePlatform = servicePlatform()): string {
+  const paths = servicePaths(platform);
+  const target = paths.unit ?? paths.plist!;
+  fs.rmSync(target, { force: true });
+  return target;
+}
+
+export function hostControlServiceEndpoint(options: Pick<HostControlServiceOptions, 'platform' | 'uid' | 'username' | 'endpoint'> = {}): string {
+  return options.endpoint ?? resolveHostControlEndpoint(options);
+}
+
+export async function startHostControlService(options: HostControlServiceOptions): Promise<RunningHostControlServer> {
+  return startHostControlServer({ endpoint: hostControlServiceEndpoint(options), dispatch: options.dispatch, ...(options.audit ? { audit: options.audit } : {}) });
+}
+
+export async function serveHostControlService(options: HostControlServiceOptions, signal?: AbortSignal): Promise<void> {
+  await serveHostControl({ endpoint: hostControlServiceEndpoint(options), dispatch: options.dispatch, ...(options.audit ? { audit: options.audit } : {}) }, signal);
+}
+
+export function hostControlServiceStatus(options: Pick<HostControlServiceOptions, 'platform' | 'uid' | 'username' | 'endpoint'> = {}): Readonly<{ endpoint: string; available: boolean; code: string | null }> {
+  const endpoint = hostControlServiceEndpoint(options);
+  const result = inspectHostControlEndpoint(endpoint, { uid: options.uid ?? process.getuid?.() });
+  return { endpoint, available: result.ok, code: result.code };
+}

package/lib/init.ts

@@ -61,6 +61,7 @@ const PLATFORM_DEFAULT_ENGINES = Object.freeze({
   darwin: 'colima',
   win32: 'wsl2'
 });
+const DEMO_PLATFORM_ENV = 'AGENT_INFRA_DEMO_PLATFORM';
 
 function detectProjectName(): string {
   try {
@@ -88,6 +89,12 @@ function detectOrgName(): string {
   return '';
 }
 
+function resolveInitPlatform(): NodeJS.Platform {
+  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: string): SourceEntry[] {
@@ -160,7 +167,7 @@ async function cmdInit(): Promise<void> {
     return;
   }
 
-  const currentPlatform = platform();
+  const currentPlatform = resolveInitPlatform();
   const defaultEngine = PLATFORM_DEFAULT_ENGINES[currentPlatform as keyof typeof PLATFORM_DEFAULT_ENGINES];
   const engineChoices = enginesForPlatform(currentPlatform).sort((left, right) => {
     if (left === defaultEngine) return -1;
@@ -288,6 +295,12 @@ async function cmdInit(): Promise<void> {
     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}`);
@@ -317,4 +330,4 @@ async function cmdInit(): Promise<void> {
   }
 }
 
-export { cmdInit };
+export { cmdInit, resolveInitPlatform };

package/lib/internal/cli-route-inventory.ts

@@ -36,6 +36,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'],
@@ -67,7 +68,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']
 } as const);
 
 export const INTERNAL_CLI_ROUTE_SELECTORS = INTERNAL_HANDLER_ROUTE_SELECTORS;

package/lib/internal/codex-lifecycle.ts

@@ -203,7 +203,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       output({
         status: 'armed',
         changed: true,
-        capabilityToken: armed.token,
+        capabilityRef: armed.capabilityRef,
         marker: armed.marker,
         expiresAt: armed.expiresAt,
         buildIdentity: armed.buildIdentity,
@@ -223,12 +223,12 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       }
       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'),