@axiom-lattice/cli-a2a 0.1.1

package/src/cli.ts

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+/**
+ * CLI A2A Gateway — Entry Point
+ *
+ * Usage:
+ *   npx @axiom-lattice/cli-a2a --provider opencode --config agents/example.json
+ *   npx @axiom-lattice/cli-a2a --provider opencode --port 3000 --opencode-url http://localhost:4096
+ *
+ * Run with --help for full usage.
+ */
+
+import { parseArgs } from 'node:util';
+import { dirname, resolve } from 'node:path';
+import { resolveConfig } from './config/loader.js';
+import type { AgentConfig, ProviderType } from './config/types.js';
+import { createA2AServer } from './server/index.js';
+import { logger, LogLevel } from './logger.js';
+
+const log = logger.child('cli');
+
+// ─── Version ────────────────────────────────────────────────────────────────
+
+const PKG_VERSION = '0.1.0';
+
+// ─── Usage ──────────────────────────────────────────────────────────────────
+
+function printUsage(): void {
+  console.log(`
+Usage: cli-a2a [options]
+
+Options:
+  --provider <name>            Provider: opencode | codex | claude
+  --config, -c <path>          Path to agent JSON config file
+  --port, -p <number>          A2A server port (default: 3000)
+  --hostname <addr>            Bind address (default: 0.0.0.0)
+  --advertise-host <host>      Hostname for agent card URLs
+  --agent-name <name>          Agent display name
+  --agent-description <desc>   Agent description
+  --log-level <level>          debug | info | warn | error (default: info)
+
+Gateway Registration:
+  --register-url <url>         Gateway URL to register this agent with
+  --register-key <key>         API key for gateway authentication
+  --unregister-on-shutdown     Remove agent from gateway on exit
+
+Bridge (NAT traversal):
+  --bridge-url <url>           Gateway WebSocket bridge (ws://gateway:8080/api/a2a/bridge)
+  --bridge-key <key>           API key for bridge authentication
+
+OpenCode Options:
+  --opencode-url <url>         OpenCode server URL (default: http://localhost:4096)
+  --directory, -d <path>       Project directory
+  --model, -m <provider/model> LLM model (e.g. anthropic/claude-sonnet-4)
+  --agent <name>               OpenCode agent preset
+
+Codex Options:
+  --codex-model <model>        Codex model ID
+  --codex-api-key <key>        OpenAI API key
+
+Claude Options:
+  --claude-model <model>       Claude Code model ID
+  --claude-api-key <key>       Anthropic API key
+
+  --help, -h                   Show this help
+  --version, -v                Show version
+
+Examples:
+  npx @axiom-lattice/cli-a2a --provider opencode
+  npx @axiom-lattice/cli-a2a --provider opencode --port 3001 --opencode-url http://localhost:4096
+  npx @axiom-lattice/cli-a2a --config ./my-agent.json
+  npx @axiom-lattice/cli-a2a --provider opencode --model anthropic/claude-sonnet-4
+  npx @axiom-lattice/cli-a2a --provider opencode --register-url http://gateway:8080 --register-key sk-xxx --unregister-on-shutdown
+  npx @axiom-lattice/cli-a2a --provider opencode --bridge-url ws://gateway:8080/api/a2a/bridge --bridge-key sk-xxx
+`);
+}
+
+// ─── CLI Args ───────────────────────────────────────────────────────────────
+
+function parseCliArgs(): {
+  configPath?: string;
+  overrides: Partial<AgentConfig>;
+  registerUrl?: string;
+  registerKey?: string;
+  unregisterOnShutdown: boolean;
+  bridgeUrl?: string;
+  bridgeKey?: string;
+} {
+  const { values } = parseArgs({
+    options: {
+      provider:           { type: 'string' },
+      config:             { type: 'string', short: 'c' },
+      port:               { type: 'string', short: 'p' },
+      hostname:           { type: 'string' },
+      'advertise-host':   { type: 'string' },
+      'agent-name':       { type: 'string' },
+      'agent-description':{ type: 'string' },
+      'opencode-url':     { type: 'string' },
+      directory:          { type: 'string', short: 'd' },
+      model:              { type: 'string', short: 'm' },
+      agent:              { type: 'string' },
+      'codex-model':      { type: 'string' },
+      'codex-api-key':    { type: 'string' },
+      'claude-model':     { type: 'string' },
+      'claude-api-key':   { type: 'string' },
+      'log-level':        { type: 'string' },
+      'register-url':     { type: 'string' },
+      'register-key':     { type: 'string' },
+      'unregister-on-shutdown': { type: 'boolean' },
+      'bridge-url':       { type: 'string' },
+      'bridge-key':       { type: 'string' },
+      help:               { type: 'boolean', short: 'h' },
+      version:            { type: 'boolean', short: 'v' },
+    },
+    strict: false,
+  });
+
+  if (values.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (values.version) {
+    console.log(PKG_VERSION);
+    process.exit(0);
+  }
+
+  const overrides: Partial<AgentConfig> = {};
+
+  // Provider
+  if (values.provider) {
+    overrides.provider = values.provider as ProviderType;
+  }
+
+  // Server
+  if (values.port || values.hostname || values['advertise-host']) {
+    overrides.server = {};
+    if (values.port) overrides.server.port = parseInt(values.port as string, 10);
+    if (values.hostname) overrides.server.hostname = values.hostname as string;
+    if (values['advertise-host']) overrides.server.advertiseHost = values['advertise-host'] as string;
+  }
+
+  // Agent card
+  const agentCardOverrides: Partial<AgentConfig['agentCard']> = {};
+  if (values['agent-name']) agentCardOverrides.name = values['agent-name'] as string;
+  if (values['agent-description']) agentCardOverrides.description = values['agent-description'] as string;
+  if (Object.keys(agentCardOverrides).length > 0) {
+    overrides.agentCard = agentCardOverrides as AgentConfig['agentCard'];
+  }
+
+  // OpenCode
+  const hasOpenCode = !!(values['opencode-url'] || values.directory || values.model || values.agent);
+  if (hasOpenCode) {
+    overrides.opencode = {};
+    if (values['opencode-url']) overrides.opencode.baseUrl = values['opencode-url'] as string;
+    if (values.directory) overrides.opencode.projectDirectory = values.directory as string;
+    if (values.model) overrides.opencode.model = values.model as string;
+    if (values.agent) overrides.opencode.agent = values.agent as string;
+  }
+
+  // Codex
+  const hasCodex = !!(values['codex-model'] || values['codex-api-key']);
+  if (hasCodex) {
+    overrides.codex = {};
+    if (values['codex-model']) overrides.codex.model = values['codex-model'] as string;
+    if (values['codex-api-key']) overrides.codex.apiKey = values['codex-api-key'] as string;
+  }
+
+  // Claude
+  const hasClaude = !!(values['claude-model'] || values['claude-api-key']);
+  if (hasClaude) {
+    overrides.claude = {};
+    if (values['claude-model']) overrides.claude.model = values['claude-model'] as string;
+    if (values['claude-api-key']) overrides.claude.apiKey = values['claude-api-key'] as string;
+  }
+
+  // Logging
+  if (values['log-level']) {
+    overrides.logging = { level: values['log-level'] as 'debug' | 'info' | 'warn' | 'error' };
+  }
+
+  const configPath = (values.config) as string | undefined;
+  const registerUrl = values['register-url'] as string | undefined;
+  const registerKey = values['register-key'] as string | undefined;
+  const unregisterOnShutdown = (values['unregister-on-shutdown'] as boolean) ?? false;
+  const bridgeUrl = values['bridge-url'] as string | undefined;
+  const bridgeKey = values['bridge-key'] as string | undefined;
+  return { configPath, overrides, registerUrl, registerKey, unregisterOnShutdown, bridgeUrl, bridgeKey };
+}
+
+// ─── Gateway Registration ───────────────────────────────────────────────────
+
+async function registerWithGateway(
+  registerUrl: string,
+  registerKey: string,
+  config: Required<AgentConfig>,
+  agentCardUrl: string,
+): Promise<{ assistantId: string; agentCardUrl: string } | null> {
+  const body = {
+    name: config.agentCard.name,
+    description: config.agentCard.description,
+    graphDefinition: {
+      type: 'a2a_remote',
+      key: `a2a-${config.provider}-${config.agentCard.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+      name: config.agentCard.name,
+      description: config.agentCard.description,
+      prompt: config.agentCard.description,
+      agentCardUrl,
+      timeout: config.timeouts.prompt,
+    },
+  };
+
+  try {
+    const url = registerUrl.replace(/\/$/, '') + '/api/assistants';
+    log.info('Registering with gateway', { url, agentCardUrl });
+
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${registerKey}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '');
+      log.error('Gateway registration failed', { status: resp.status, body: text });
+      return null;
+    }
+
+    const result = await resp.json() as { data?: { id: string } };
+    const assistantId = result.data?.id ?? body.graphDefinition.key;
+
+    log.info('Registered with gateway', { assistantId, agentCardUrl });
+    console.log(`Registered as agent: ${assistantId}`);
+    console.log(`Agent card:        ${agentCardUrl}`);
+
+    return { assistantId, agentCardUrl };
+  } catch (err) {
+    log.error('Gateway registration error', { error: (err as Error).message });
+    return null;
+  }
+}
+
+async function unregisterFromGateway(
+  registerUrl: string,
+  registerKey: string,
+  assistantId: string,
+): Promise<void> {
+  try {
+    const url = `${registerUrl.replace(/\/$/, '')}/api/assistants/${assistantId}`;
+    log.info('Unregistering from gateway', { assistantId });
+
+    const resp = await fetch(url, {
+      method: 'DELETE',
+      headers: {
+        'Authorization': `Bearer ${registerKey}`,
+      },
+    });
+
+    if (!resp.ok && resp.status !== 404) {
+      log.warn('Gateway unregistration failed', { status: resp.status });
+    } else {
+      log.info('Unregistered from gateway', { assistantId });
+    }
+  } catch (err) {
+    log.warn('Gateway unregistration error', { error: (err as Error).message });
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const { configPath, overrides, registerUrl, registerKey, unregisterOnShutdown, bridgeUrl, bridgeKey } = parseCliArgs();
+
+  // Resolve config
+  const config = resolveConfig(configPath, overrides);
+
+  // Set configDir for relative path resolution
+  if (configPath) {
+    config.configDir = dirname(resolve(configPath));
+  }
+
+  // Apply log level
+  const levelStr = config.logging.level ?? 'info';
+  const levelMap: Record<string, LogLevel> = {
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+  };
+  logger.setLevel(levelMap[levelStr] ?? LogLevel.INFO);
+
+  if (!configPath) {
+    log.info('No --config provided — running with defaults + CLI args.');
+  }
+
+  log.info('Starting CLI A2A Gateway', {
+    provider: config.provider,
+    config: configPath ?? '(defaults)',
+    agent: config.agentCard.name,
+    port: config.server?.port,
+  });
+
+  // Register executors
+  const { registerExecutor } = await import('./executors/index.js');
+  const { createOpenCodeExecutor } = await import('./executors/opencode/executor.js');
+  const { createCodexExecutor } = await import('./executors/codex/executor.js');
+  const { createClaudeExecutor } = await import('./executors/claude/executor.js');
+  registerExecutor('opencode', createOpenCodeExecutor);
+  registerExecutor('codex', createCodexExecutor);
+  registerExecutor('claude', createClaudeExecutor);
+
+  // Start server
+  const server = await createA2AServer(config);
+
+  const listenPort = config.server?.port ?? 3000;
+  const agentId = `a2a-${config.provider}-${listenPort}`;
+
+  // Connect bridge to gateway (NAT traversal)
+  let bridgeClient: { start(): Promise<void>; stop(): void } | null = null;
+  if (bridgeUrl && bridgeKey) {
+    const { BridgeClient } = await import('./bridge.js');
+    const agentCardUrl = `${config.server?.advertiseProtocol ?? 'http'}://${config.server?.advertiseHost ?? 'localhost'}:${listenPort}/.well-known/agent-card.json`;
+
+    bridgeClient = new BridgeClient({
+      bridgeUrl: bridgeUrl.replace(/^http/, 'ws'),
+      apiKey: bridgeKey,
+      agentId,
+      agentCard: {
+        name: config.agentCard.name,
+        description: config.agentCard.description,
+        url: agentCardUrl,
+      },
+      localBaseUrl: `http://localhost:${listenPort}`,
+    });
+
+    bridgeClient.start().then(() => {
+      log.info('Bridge connected — agent reachable via gateway proxy');
+      console.log(`Bridge: ws://gateway → localhost:${listenPort}`);
+    }).catch((err: Error) => {
+      log.error('Bridge connection failed', { error: err.message });
+    });
+  }
+
+  // Register with gateway (HTTP-based self-registration)
+  let registeredAssistantId: string | null = null;
+  if (registerUrl && registerKey) {
+    // When bridge is active, the agent card URL must point to the gateway proxy
+    // so the orchestrator reaches the agent through the WebSocket bridge, not directly.
+    const agentCardUrl = bridgeUrl
+      ? `${registerUrl.replace(/\/$/, '')}/api/a2a/bridge/proxy/${agentId}/.well-known/agent-card.json`
+      : `${config.server?.advertiseProtocol ?? 'http'}://${config.server?.advertiseHost ?? 'localhost'}:${listenPort}/.well-known/agent-card.json`;
+
+    const reg = await registerWithGateway(
+      registerUrl,
+      registerKey,
+      config,
+      agentCardUrl,
+    );
+    if (reg) {
+      registeredAssistantId = reg.assistantId;
+    }
+  }
+
+  // Graceful shutdown
+  const shutdown = async (signal: string) => {
+    log.info(`${signal} received, shutting down...`);
+    bridgeClient?.stop();
+    if (registeredAssistantId && registerUrl && registerKey && unregisterOnShutdown) {
+      await unregisterFromGateway(registerUrl, registerKey, registeredAssistantId);
+    }
+    await server.shutdown();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+main().catch((err) => {
+  log.error('Fatal error', { error: (err as Error).message, stack: (err as Error).stack });
+  process.exit(1);
+});

package/src/config/defaults.ts

@@ -0,0 +1,109 @@
+/**
+ * Default configuration values.
+ *
+ * Every field has a sensible default so the agent runs without a config file.
+ */
+
+import type { AgentConfig } from './types.js';
+
+function withDefaults<T extends Record<string, unknown>>(
+  partial: Partial<T>,
+  defaults: Required<T>,
+): Required<T> {
+  const result = { ...defaults } as Record<string, unknown>;
+  for (const key of Object.keys(partial) as Array<keyof T>) {
+    const val = partial[key] as unknown;
+    if (val !== undefined && val !== null) {
+      if (
+        typeof val === 'object' &&
+        !Array.isArray(val) &&
+        typeof defaults[key] === 'object' &&
+        !Array.isArray(defaults[key])
+      ) {
+        result[key as string] = {
+          ...(defaults[key] as Record<string, unknown>),
+          ...(val as Record<string, unknown>),
+        };
+      } else {
+        result[key as string] = val;
+      }
+    }
+  }
+  return result as unknown as Required<T>;
+}
+
+type ResolvedConfig = Omit<Required<AgentConfig>, 'opencode' | 'codex' | 'claude' | 'configDir'> & {
+  opencode: Required<Required<AgentConfig>['opencode']>;
+  codex: Required<Required<AgentConfig>['codex']>;
+  claude: Required<Required<AgentConfig>['claude']>;
+  configDir: string | undefined;
+};
+
+const DEFAULTS: Readonly<ResolvedConfig> = Object.freeze({
+  provider: 'opencode' as const,
+  agentCard: {
+    name: 'CLI A2A Agent',
+    description: 'A multi-provider A2A agent driven by local CLI coding tools.',
+    protocolVersion: '0.3.0',
+    version: '0.1.0',
+    skills: [],
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+    streaming: true,
+    pushNotifications: false,
+  },
+  server: {
+    port: 3000,
+    hostname: '0.0.0.0',
+    advertiseHost: 'localhost',
+    advertiseProtocol: 'http',
+  },
+  session: {
+    titlePrefix: 'A2A Session',
+    reuseByContext: true,
+    ttl: 3_600_000,
+    cleanupInterval: 300_000,
+  },
+  features: {
+    autoApprovePermissions: true,
+    autoAnswerQuestions: true,
+    streamArtifactChunks: false,
+    enablePollingFallback: true,
+  },
+  timeouts: {
+    prompt: 600_000,
+    pollingInterval: 2_000,
+    healthCheck: 30_000,
+  },
+  logging: {
+    level: 'info',
+  },
+  opencode: {
+    baseUrl: 'http://localhost:4096',
+    projectDirectory: '',
+    model: '',
+    agent: '',
+    systemPrompt: '',
+    systemPromptMode: 'append',
+    contextFile: 'context.md',
+    contextPrompt: '',
+  },
+  codex: {
+    cliPath: 'codex',
+    workdir: process.cwd(),
+    model: '',
+    apiKey: '',
+  },
+  claude: {
+    cliPath: 'claude',
+    workdir: process.cwd(),
+    model: '',
+    apiKey: '',
+  },
+  configDir: undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+} as any);
+
+export function resolveDefaults(overrides: Partial<AgentConfig>): Required<AgentConfig> {
+  return withDefaults(overrides, DEFAULTS) as unknown as Required<AgentConfig>;
+}

package/src/config/index.ts

@@ -0,0 +1,16 @@
+export { resolveConfig, loadConfigFile } from './loader.js';
+export { resolveDefaults } from './defaults.js';
+export type {
+  AgentConfig,
+  ProviderType,
+  AgentCardConfig,
+  SkillConfig,
+  ServerConfig,
+  SessionConfig,
+  FeatureFlags,
+  TimeoutConfig,
+  LoggingConfig,
+  OpenCodeConfig,
+  CodexConfig,
+  ClaudeCodeConfig,
+} from './types.js';

package/src/config/loader.ts

@@ -0,0 +1,121 @@
+/**
+ * Config loader — reads JSON config files and resolves the final config
+ * by merging layers: defaults ← config file ← env overrides ← CLI args.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { resolveDefaults } from './defaults.js';
+import type { AgentConfig } from './types.js';
+import { logger } from '../logger.js';
+
+const log = logger.child('config');
+
+/**
+ * Read and parse a JSON config file.
+ */
+export function loadConfigFile(filePath: string): Partial<AgentConfig> {
+  const absPath = resolve(filePath);
+  if (!existsSync(absPath)) {
+    throw new Error(`Config file not found: ${absPath}`);
+  }
+  try {
+    const raw = readFileSync(absPath, 'utf-8');
+    return JSON.parse(raw) as Partial<AgentConfig>;
+  } catch (err) {
+    const msg = err instanceof SyntaxError
+      ? `Invalid JSON in config file: ${err.message}`
+      : `Failed to read config file: ${(err as Error).message}`;
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Load env overrides for provider configs.
+ */
+function loadEnvOverrides(): Partial<AgentConfig> {
+  const overrides: Partial<AgentConfig> = {
+    opencode: {},
+    codex: {},
+    claude: {},
+  };
+
+  // OpenCode
+  if (process.env.OPENCODE_URL) overrides.opencode!.baseUrl = process.env.OPENCODE_URL;
+  if (process.env.OPENCODE_DIRECTORY) overrides.opencode!.projectDirectory = process.env.OPENCODE_DIRECTORY;
+  if (process.env.OPENCODE_MODEL) overrides.opencode!.model = process.env.OPENCODE_MODEL;
+  if (process.env.OPENCODE_AGENT) overrides.opencode!.agent = process.env.OPENCODE_AGENT;
+  if (process.env.OPENCODE_SYSTEM_PROMPT) overrides.opencode!.systemPrompt = process.env.OPENCODE_SYSTEM_PROMPT;
+
+  // Codex
+  if (process.env.OPENAI_API_KEY) overrides.codex!.apiKey = process.env.OPENAI_API_KEY;
+  if (process.env.CODEX_MODEL) overrides.codex!.model = process.env.CODEX_MODEL;
+
+  // Claude Code
+  if (process.env.ANTHROPIC_API_KEY) overrides.claude!.apiKey = process.env.ANTHROPIC_API_KEY;
+  if (process.env.CLAUDE_MODEL) overrides.claude!.model = process.env.CLAUDE_MODEL;
+
+  return overrides;
+}
+
+/**
+ * Resolve full config from defaults + file + env.
+ */
+export function resolveConfig(
+  configPath?: string,
+  cliOverrides?: Partial<AgentConfig>,
+): Required<AgentConfig> {
+  // Layer 1: File
+  let fileConfig: Partial<AgentConfig> = {};
+  if (configPath) {
+    fileConfig = loadConfigFile(configPath);
+    log.info('Loaded config file', { path: configPath });
+  }
+
+    // Layer 2: Env
+    const envOverrides = loadEnvOverrides();
+
+    // Layer 3: CLI
+    const cliConfig = cliOverrides ?? {};
+
+    // Deep merge: defaults ← file ← env ← CLI
+    // Start with a proper deep copy of merged defaults+file to avoid mutating the frozen defaults
+    const cloned = structuredClone(resolveDefaults(fileConfig)) as Required<AgentConfig>;
+    const base = cloned;
+
+  // Then merge env overrides
+  mergeOverrides(base, envOverrides);
+
+  // Then merge CLI overrides
+  mergeOverrides(base, cliConfig);
+
+  // Populate configDir
+  if (configPath) {
+    base.configDir = dirname(resolve(configPath));
+  }
+
+  return base;
+}
+
+function mergeOverrides(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = target[key];
+    if (
+      srcVal !== undefined &&
+      srcVal !== null &&
+      typeof srcVal === 'object' &&
+      !Array.isArray(srcVal) &&
+      tgtVal !== undefined &&
+      typeof tgtVal === 'object' &&
+      !Array.isArray(tgtVal)
+    ) {
+      // Do not merge empty override objects
+      if (Object.keys(srcVal as Record<string, unknown>).length > 0) {
+        mergeOverrides(tgtVal as Record<string, unknown>, srcVal as Record<string, unknown>);
+      }
+    } else if (srcVal !== undefined && srcVal !== null) {
+      target[key] = srcVal;
+    }
+  }
+}