@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/agent-client.ts

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { AgentClientConfigError, normalizeAgentClients } from './agent-clients/config.ts';
+import {
+  applyAgentClientReconciliation,
+  planAgentClientReconciliation
+} from './agent-clients/reconcile.ts';
+import { listAgentClientAdapters } from './agent-clients/registry.ts';
+import { AGENT_CLIENT_IDS, isAgentClientId } from './agent-clients/types.ts';
+import type { AgentClientState } from './agent-clients/types.ts';
+import { closePrompt, multiSelect } from './prompt.ts';
+import { resolveTemplateDir } from './paths.ts';
+
+const USAGE = `Usage: ai agent-client <operation>
+
+Operations:
+  list                 List built-in Agent Clients
+  status               Show project integration and sandbox state
+  enable <client-id>   Enable project integration only
+  disable <client-id>  Disable project integration only
+  configure            Configure integration and sandbox state interactively
+`;
+
+class AgentClientCommandError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'AgentClientCommandError';
+    this.code = code;
+  }
+}
+
+function readConfig(projectRoot: string): Record<string, unknown> {
+  const configPath = path.join(projectRoot, '.agents', '.airc.json');
+  if (!fs.existsSync(configPath)) {
+    throw new AgentClientCommandError(
+      'AGENT_CLIENT_CONFIG_NOT_FOUND',
+      'No .agents/.airc.json found. Run "ai init" first.'
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    throw new AgentClientCommandError(
+      'AGENT_CLIENT_CONFIG_INVALID',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new AgentClientCommandError(
+      'AGENT_CLIENT_CONFIG_INVALID',
+      'configuration root must be an object'
+    );
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function choices() {
+  return listAgentClientAdapters().map((adapter) => ({
+    id: adapter.id,
+    label: adapter.displayName
+  }));
+}
+
+function selected(state: AgentClientState, field: 'enabled' | 'installInSandbox'): string[] {
+  return AGENT_CLIENT_IDS.filter((id) => state[id][field]);
+}
+
+function workflowPlan(
+  projectRoot: string,
+  config: Record<string, unknown>,
+  mutation: Parameters<typeof planAgentClientReconciliation>[0]['mutation']
+) {
+  const templateRoot = resolveTemplateDir();
+  if (!templateRoot) {
+    throw new AgentClientCommandError('AGENT_CLIENT_TEMPLATE_NOT_FOUND', 'Template directory not found');
+  }
+  const platform = config.platform;
+  const platformType = typeof platform === 'object' && platform !== null && 'type' in platform
+    ? String(platform.type ?? 'github')
+    : 'github';
+  return planAgentClientReconciliation({
+    config,
+    mutation,
+    projectRoot,
+    templateRoot,
+    platformType,
+    language: String(config.language ?? 'en')
+  });
+}
+
+function printState(state: AgentClientState): void {
+  for (const adapter of listAgentClientAdapters()) {
+    const value = state[adapter.id];
+    process.stdout.write(
+      `  ${adapter.id}: enabled=${String(value.enabled)} installInSandbox=${String(value.installInSandbox)}\n`
+    );
+  }
+}
+
+async function cmdAgentClient(args: string[]): Promise<number> {
+  const operation = args[0];
+  if (!operation || operation === '--help' || operation === '-h' || operation === 'help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  if (operation === 'list') {
+    if (args.length !== 1) {
+      throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', 'list accepts no arguments');
+    }
+    for (const adapter of listAgentClientAdapters()) {
+      process.stdout.write(
+        `${adapter.id}\t${adapter.displayName}\t${adapter.invocation}\tcommands=${adapter.capabilities.commands.level}\tsandbox=${adapter.capabilities.sandbox.level}\n`
+      );
+    }
+    return 0;
+  }
+
+  const projectRoot = process.cwd();
+  const config = readConfig(projectRoot);
+  try {
+    if (operation === 'status') {
+      if (args.length !== 1) {
+        throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', 'status accepts no arguments');
+      }
+      const plan = workflowPlan(projectRoot, config, { type: 'none' });
+      process.stdout.write(`source: ${plan.source}\n`);
+      printState(plan.desired);
+      for (const seed of plan.seedOperations) {
+        process.stdout.write(`  seed ${seed.target}: ${seed.kind}\n`);
+      }
+      for (const diagnostic of plan.diagnostics) {
+        process.stdout.write(`  diagnostic ${diagnostic.code} at ${diagnostic.path}\n`);
+      }
+      return 0;
+    }
+
+    if (operation === 'enable' || operation === 'disable') {
+      if (args.length !== 2) {
+        throw new AgentClientCommandError(
+          'AGENT_CLIENT_ARGUMENT_INVALID',
+          `${operation} requires exactly one client id`
+        );
+      }
+      const id = args[1];
+      if (!isAgentClientId(id)) {
+        throw new AgentClientCommandError('UNKNOWN_AGENT_CLIENT', `Unknown Agent Client '${String(id)}'`);
+      }
+      const plan = workflowPlan(projectRoot, config, {
+        type: 'set-enabled',
+        id,
+        value: operation === 'enable'
+      });
+      process.stdout.write('Before:\n');
+      printState(plan.before);
+      const result = applyAgentClientReconciliation(plan);
+      process.stdout.write('After:\n');
+      printState(plan.desired);
+      process.stdout.write(
+        `Result: ${result.status}; applied=${result.applied.length}; protected=${result.protected.length}\n`
+      );
+      return 0;
+    }
+
+    if (operation === 'configure') {
+      if (args.length !== 1) {
+        throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', 'configure accepts no arguments');
+      }
+      const normalized = normalizeAgentClients(config);
+      let enabled: string[];
+      let installed: string[];
+      try {
+        enabled = await multiSelect(
+          'Agent Client project integrations',
+          choices(),
+          selected(normalized.state, 'enabled')
+        );
+        installed = await multiSelect(
+          'Agent Clients installed in sandbox',
+          choices(),
+          selected(normalized.state, 'installInSandbox')
+        );
+      } finally {
+        closePrompt();
+      }
+      const state = Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [id, {
+        enabled: enabled.includes(id),
+        installInSandbox: installed.includes(id)
+      }])) as AgentClientState;
+      const plan = workflowPlan(projectRoot, config, { type: 'replace-state', state });
+      const result = applyAgentClientReconciliation(plan);
+      process.stdout.write(
+        `Result: ${result.status}; applied=${result.applied.length}; protected=${result.protected.length}\n`
+      );
+      return 0;
+    }
+
+    throw new AgentClientCommandError(
+      'AGENT_CLIENT_OPERATION_INVALID',
+      `Unknown operation '${operation}'`
+    );
+  } catch (error) {
+    if (error instanceof AgentClientConfigError) {
+      throw new AgentClientCommandError(error.code, error.message);
+    }
+    throw error;
+  }
+}
+
+export { AgentClientCommandError, cmdAgentClient };

package/lib/agent-clients/adapter.ts

@@ -0,0 +1,461 @@
+import {
+  AGENT_CLIENT_CAPABILITY_IDS,
+  AGENT_CLIENT_SUPPORT_LEVELS,
+  isAgentClientId
+} from './types.ts';
+import type {
+  AgentClientCapabilityMap,
+  AgentClientId
+} from './types.ts';
+import {
+  SANDBOX_HOOK_PHASES
+} from '../sandbox/tool-types.ts';
+import type {
+  AgentClientSandboxRecoveryCheck,
+  AgentClientSandboxDescriptor,
+  SandboxAlias,
+  SandboxTool,
+  SandboxToolContext
+} from '../sandbox/tool-types.ts';
+
+type AgentClientCapabilities = AgentClientCapabilityMap;
+
+type AgentClientSeedCommand = Readonly<{
+  templates: Readonly<{
+    en: string;
+    'zh-CN': string;
+  }>;
+  target: string;
+}>;
+
+type AgentClientProjectDescriptor = Readonly<{
+  ownedPathPrefixes: readonly string[];
+  managed: readonly string[];
+  merged: readonly string[];
+  ejected: readonly string[];
+  seedCommands: readonly AgentClientSeedCommand[];
+}>;
+
+type AgentClientAdapter = Readonly<{
+  id: AgentClientId;
+  displayName: string;
+  invocation: string;
+  capabilities: AgentClientCapabilities;
+  project: AgentClientProjectDescriptor;
+  sandbox: AgentClientSandboxDescriptor;
+}>;
+
+type AgentClientRegistry = Readonly<
+  Record<AgentClientId, AgentClientAdapter>
+>;
+
+type AgentClientManifestEntry = Readonly<{
+  id: AgentClientId;
+  displayName: string;
+  invocation: string;
+  ownedPathPrefixes: readonly string[];
+  managed: readonly string[];
+  merged: readonly string[];
+  ejected: readonly string[];
+}>;
+
+const PROJECT_ASSET_CATEGORIES = ['managed', 'merged', 'ejected'] as const;
+const MAX_SANDBOX_HOOK_TIMEOUT_MS = 300_000;
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+function freezeRecoveryProbe(
+  id: AgentClientId,
+  checkId: string,
+  value: AgentClientSandboxRecoveryCheck['probe']
+): AgentClientSandboxRecoveryCheck['probe'] {
+  if (
+    !value
+    || typeof value.script !== 'string'
+    || value.script.trim() === ''
+    || !Array.isArray(value.args)
+    || value.args.some((arg) => typeof arg !== 'string')
+    || (value.user !== undefined && (typeof value.user !== 'string' || value.user === ''))
+  ) {
+    throw new Error(`Agent Client '${id}' recovery check '${checkId}' has an invalid probe`);
+  }
+  return Object.freeze({
+    script: value.script,
+    args: Object.freeze([...value.args]),
+    ...(value.user === undefined ? {} : { user: value.user })
+  });
+}
+
+function freezeTool(tool: SandboxTool): SandboxTool {
+  if (typeof tool.id !== 'string' || !TOOL_ID_PATTERN.test(tool.id)) {
+    throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
+  }
+  if (!tool.install?.cmd || !['npm', 'shell'].includes(tool.install.type)) {
+    throw new Error(`Sandbox tool '${tool.id}' has invalid install`);
+  }
+  if (!tool.containerMount.startsWith('/')) {
+    throw new Error(`Sandbox tool '${tool.id}' containerMount must be absolute`);
+  }
+  if (!tool.versionCmd) {
+    throw new Error(`Sandbox tool '${tool.id}' requires versionCmd`);
+  }
+  return Object.freeze({
+    ...tool,
+    install: Object.freeze({ ...tool.install }),
+    ...(tool.envVars ? { envVars: Object.freeze({ ...tool.envVars }) } : {}),
+    ...(tool.hostPreSeedFiles ? {
+      hostPreSeedFiles: Object.freeze(tool.hostPreSeedFiles.map((entry) => Object.freeze({ ...entry })))
+    } : {}),
+    ...(tool.hostPreSeedDirs ? {
+      hostPreSeedDirs: Object.freeze(tool.hostPreSeedDirs.map((entry) => Object.freeze({ ...entry })))
+    } : {}),
+    ...(tool.pathRewriteFiles ? { pathRewriteFiles: Object.freeze([...tool.pathRewriteFiles]) } : {}),
+    ...(tool.hostLiveMounts ? {
+      hostLiveMounts: Object.freeze(tool.hostLiveMounts.map((entry) => Object.freeze({ ...entry })))
+    } : {}),
+    ...(tool.postSetupCmds ? { postSetupCmds: Object.freeze([...tool.postSetupCmds]) } : {}),
+    ...(tool.tmpfs ? {
+      tmpfs: Object.freeze({
+        ...tool.tmpfs,
+        ...(tool.tmpfs.seed ? { seed: Object.freeze([...tool.tmpfs.seed]) } : {})
+      })
+    } : {})
+  }) as SandboxTool;
+}
+
+function freezeAliases(id: AgentClientId, aliases: readonly SandboxAlias[]): readonly SandboxAlias[] {
+  const names = new Set<string>();
+  return Object.freeze(aliases.map((alias) => {
+    if (!alias.name || !alias.command || names.has(alias.name)) {
+      throw new Error(`Agent Client '${id}' has invalid or duplicate sandbox alias '${alias.name}'`);
+    }
+    names.add(alias.name);
+    return Object.freeze({ ...alias });
+  }));
+}
+
+function isProjectRelativeLiteral(value: string): boolean {
+  if (
+    value.length === 0
+    || value.startsWith('/')
+    || /^[a-zA-Z]:/.test(value)
+    || value.includes('\\')
+    || /[*?[\]{}]/.test(value)
+  ) {
+    return false;
+  }
+  return !value.split('/').some((segment) => segment === '..');
+}
+
+function defineAgentClientAdapter(
+  candidate: AgentClientAdapter
+): AgentClientAdapter {
+  if (!isAgentClientId(candidate.id)) {
+    throw new Error(`Unknown Agent Client ID '${String(candidate.id)}'`);
+  }
+  if (typeof candidate.displayName !== 'string' || candidate.displayName.trim() === '') {
+    throw new Error(`Agent Client '${candidate.id}' requires a display name`);
+  }
+  if (
+    typeof candidate.invocation !== 'string'
+    || candidate.invocation.trim() === ''
+    || /[\r\n]/.test(candidate.invocation)
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' requires a single-line invocation`);
+  }
+  const invocationPlaceholders = [
+    ...candidate.invocation.matchAll(/\$\{([^}]+)\}/g)
+  ].map((match) => match[1]);
+  if (
+    !invocationPlaceholders.includes('skillName')
+    || invocationPlaceholders.some((placeholder) =>
+      placeholder !== 'skillName' && placeholder !== 'projectName'
+    )
+    || candidate.invocation
+      .replaceAll('${skillName}', '')
+      .replaceAll('${projectName}', '')
+      .includes('${')
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' has an invalid invocation`);
+  }
+
+  if (
+    typeof candidate.capabilities !== 'object'
+    || candidate.capabilities === null
+    || Array.isArray(candidate.capabilities)
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' has an invalid capability map`);
+  }
+  const capabilityKeys = Object.keys(candidate.capabilities);
+  if (
+    capabilityKeys.length !== AGENT_CLIENT_CAPABILITY_IDS.length
+    || AGENT_CLIENT_CAPABILITY_IDS.some((capability) =>
+      !Object.prototype.hasOwnProperty.call(candidate.capabilities, capability)
+    )
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' has an invalid capability map`);
+  }
+
+  const capabilities = Object.fromEntries(
+    AGENT_CLIENT_CAPABILITY_IDS.map((capability) => {
+      const support = candidate.capabilities[capability];
+      if (
+        typeof support !== 'object'
+        || support === null
+        || !AGENT_CLIENT_SUPPORT_LEVELS.includes(support.level)
+      ) {
+        throw new Error(
+          `Agent Client '${candidate.id}' has invalid support for '${capability}'`
+        );
+      }
+      return [capability, Object.freeze({ level: support.level })];
+    })
+  ) as AgentClientCapabilities;
+
+  if (
+    typeof candidate.project !== 'object'
+    || candidate.project === null
+    || Array.isArray(candidate.project)
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' has an invalid project descriptor`);
+  }
+  const ownedPathPrefixes = candidate.project.ownedPathPrefixes;
+  if (!Array.isArray(ownedPathPrefixes) || ownedPathPrefixes.length === 0) {
+    throw new Error(`Agent Client '${candidate.id}' requires owned path prefixes`);
+  }
+
+  const paths = ownedPathPrefixes.map((prefix) => {
+    if (
+      typeof prefix !== 'string'
+      || !isProjectRelativeLiteral(prefix)
+      || !prefix.endsWith('/')
+    ) {
+      throw new Error(
+        `Agent Client '${candidate.id}' has invalid owned path prefix '${String(prefix)}'`
+      );
+    }
+    return prefix;
+  });
+  if (new Set(paths).size !== paths.length) {
+    throw new Error(`Agent Client '${candidate.id}' has duplicate owned path prefixes`);
+  }
+
+  const projectAssets = Object.fromEntries(
+    PROJECT_ASSET_CATEGORIES.map((category) => {
+      const values = candidate.project[category];
+      if (!Array.isArray(values)) {
+        throw new Error(
+          `Agent Client '${candidate.id}' has invalid '${category}' project assets`
+        );
+      }
+      const assets = values.map((asset) => {
+        if (
+          typeof asset !== 'string'
+          || !isProjectRelativeLiteral(asset)
+          || !paths.some((prefix) =>
+            asset === prefix.slice(0, -1) || asset.startsWith(prefix)
+          )
+        ) {
+          throw new Error(
+            `Agent Client '${candidate.id}' has invalid '${category}' project asset '${String(asset)}'`
+          );
+        }
+        return asset;
+      });
+      if (new Set(assets).size !== assets.length) {
+        throw new Error(
+          `Agent Client '${candidate.id}' has duplicate '${category}' project assets`
+        );
+      }
+      return [category, Object.freeze(assets)];
+    })
+  ) as Pick<AgentClientProjectDescriptor, 'managed' | 'merged' | 'ejected'>;
+
+  const categorizedAssets = PROJECT_ASSET_CATEGORIES.flatMap((category) =>
+    projectAssets[category].map((asset) => ({ asset, category }))
+  );
+  const seenAssets = new Map<string, string>();
+  for (const { asset, category } of categorizedAssets) {
+    const previous = seenAssets.get(asset);
+    if (previous) {
+      throw new Error(
+        `Agent Client '${candidate.id}' project asset '${asset}' overlaps '${previous}' and '${category}'`
+      );
+    }
+    seenAssets.set(asset, category);
+  }
+
+  if (!Array.isArray(candidate.project.seedCommands)) {
+    throw new Error(`Agent Client '${candidate.id}' has invalid seed commands`);
+  }
+  const seedTargets = new Set<string>();
+  const seedCommands = candidate.project.seedCommands.map((seed) => {
+    if (!seed || typeof seed !== 'object') {
+      throw new Error(`Agent Client '${candidate.id}' has an invalid seed command`);
+    }
+    const placeholders = [
+      ...seed.target.matchAll(/\$\{([^}]+)\}/g)
+    ].map((match) => match[1]);
+    const targetProbe = seed.target.replaceAll('${projectName}', 'project');
+    if (
+      placeholders.some((placeholder) => placeholder !== 'projectName')
+      || targetProbe.includes('${')
+      || !isProjectRelativeLiteral(targetProbe)
+      || !paths.some((prefix) =>
+        targetProbe === prefix.slice(0, -1) || targetProbe.startsWith(prefix)
+      )
+      || seedTargets.has(seed.target)
+    ) {
+      throw new Error(
+        `Agent Client '${candidate.id}' has invalid seed target '${String(seed.target)}'`
+      );
+    }
+    if (
+      !seed.templates
+      || typeof seed.templates.en !== 'string'
+      || typeof seed.templates['zh-CN'] !== 'string'
+      || !isProjectRelativeLiteral(seed.templates.en)
+      || !isProjectRelativeLiteral(seed.templates['zh-CN'])
+    ) {
+      throw new Error(`Agent Client '${candidate.id}' has invalid seed templates`);
+    }
+    seedTargets.add(seed.target);
+    return Object.freeze({
+      templates: Object.freeze({ ...seed.templates }),
+      target: seed.target
+    });
+  });
+
+  if (!candidate.sandbox || typeof candidate.sandbox.createTool !== 'function') {
+    throw new Error(`Agent Client '${candidate.id}' requires a sandbox descriptor`);
+  }
+  const hookIds = new Set<string>();
+  const hooks = Object.freeze(candidate.sandbox.hooks.map((hook) => {
+    if (
+      !hook.id
+      || hookIds.has(hook.id)
+      || !SANDBOX_HOOK_PHASES.includes(hook.phase)
+      || typeof hook.run !== 'function'
+    ) {
+      throw new Error(`Agent Client '${candidate.id}' has an invalid sandbox hook`);
+    }
+    if (
+      hook.timeoutMs !== undefined
+      && (
+        !Number.isInteger(hook.timeoutMs)
+        || hook.timeoutMs <= 0
+        || hook.timeoutMs > MAX_SANDBOX_HOOK_TIMEOUT_MS
+      )
+    ) {
+      throw new Error(`Agent Client '${candidate.id}' hook '${hook.id}' has invalid timeoutMs`);
+    }
+    hookIds.add(hook.id);
+    return Object.freeze({ ...hook });
+  }));
+  const recoveryCheckIds = new Set<string>();
+  if (
+    candidate.sandbox.recoveryChecks !== undefined
+    && !Array.isArray(candidate.sandbox.recoveryChecks)
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' has invalid recovery checks`);
+  }
+  const recoveryChecks = Object.freeze(
+    (candidate.sandbox.recoveryChecks ?? []).map((check) => {
+      if (
+        !check
+        || typeof check.id !== 'string'
+        || !TOOL_ID_PATTERN.test(check.id)
+        || recoveryCheckIds.has(check.id)
+      ) {
+        throw new Error(`Agent Client '${candidate.id}' has an invalid recovery check`);
+      }
+      const probe = freezeRecoveryProbe(candidate.id, check.id, check.probe);
+      const when = check.when === undefined
+        ? undefined
+        : freezeRecoveryProbe(candidate.id, check.id, check.when);
+      if (
+        !check.finding
+        || !['permissions', 'builtin-link', 'hard-failure'].includes(check.finding.repairKind)
+        || typeof check.finding.message !== 'string'
+        || check.finding.message.trim() === ''
+        || (
+          check.finding.path !== undefined
+          && (typeof check.finding.path !== 'string' || !check.finding.path.startsWith('/'))
+        )
+        || (
+          check.finding.repairKind === 'permissions'
+          && check.finding.path === undefined
+        )
+      ) {
+        throw new Error(
+          `Agent Client '${candidate.id}' recovery check '${check.id}' has an invalid finding`
+        );
+      }
+      let repair: AgentClientSandboxRecoveryCheck['repair'];
+      if (check.repair !== undefined) {
+        if (
+          typeof check.repair.user !== 'string'
+          || check.repair.user === ''
+          || typeof check.repair.command !== 'string'
+          || check.repair.command === ''
+          || !Array.isArray(check.repair.args)
+          || check.repair.args.some((arg: unknown) => typeof arg !== 'string')
+        ) {
+          throw new Error(
+            `Agent Client '${candidate.id}' recovery check '${check.id}' has an invalid repair`
+          );
+        }
+        repair = Object.freeze({
+          user: check.repair.user,
+          command: check.repair.command,
+          args: Object.freeze([...check.repair.args])
+        });
+      }
+      if (check.finding.repairKind === 'builtin-link' && repair === undefined) {
+        throw new Error(
+          `Agent Client '${candidate.id}' recovery check '${check.id}' requires a repair`
+        );
+      }
+      recoveryCheckIds.add(check.id);
+      return Object.freeze({
+        id: check.id,
+        ...(when === undefined ? {} : { when }),
+        probe,
+        finding: Object.freeze({ ...check.finding }),
+        ...(repair === undefined ? {} : { repair })
+      });
+    })
+  );
+  const aliases = freezeAliases(candidate.id, candidate.sandbox.aliases);
+  const createTool = (context: SandboxToolContext): SandboxTool => {
+    const tool = freezeTool(candidate.sandbox.createTool(context));
+    if (tool.id !== candidate.id) {
+      throw new Error(
+        `Agent Client '${candidate.id}' sandbox tool id must match the adapter id`
+      );
+    }
+    return tool;
+  };
+
+  return Object.freeze({
+    id: candidate.id,
+    displayName: candidate.displayName,
+    invocation: candidate.invocation,
+    capabilities: Object.freeze(capabilities),
+    project: Object.freeze({
+      ownedPathPrefixes: Object.freeze(paths),
+      ...projectAssets,
+      seedCommands: Object.freeze(seedCommands)
+    }),
+    sandbox: Object.freeze({ createTool, aliases, hooks, recoveryChecks })
+  });
+}
+
+export { defineAgentClientAdapter };
+export type {
+  AgentClientAdapter,
+  AgentClientCapabilities,
+  AgentClientManifestEntry,
+  AgentClientProjectDescriptor,
+  AgentClientSeedCommand,
+  AgentClientRegistry
+};