@axiom-lattice/cli-a2a 0.1.1

package/src/config/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Unified configuration types for the CLI A2A gateway.
+ *
+ * Each provider (OpenCode, Codex, Claude Code) extends the base config
+ * with its own connection settings. A single config file can declare
+ * multiple providers, and the CLI selects one at startup via --provider.
+ */
+
+// ─── Agent Card ────────────────────────────────────────────────────────────
+
+export interface AgentCardConfig {
+  /** Human-readable agent name */
+  name: string;
+  /** Agent description shown to orchestrators / callers */
+  description: string;
+  /** Protocol version (default: "0.3.0") */
+  protocolVersion?: string;
+  /** Agent version string */
+  version?: string;
+  /** Skills advertised on the agent card */
+  skills?: SkillConfig[];
+  /** Supported input modes */
+  defaultInputModes?: string[];
+  /** Supported output modes */
+  defaultOutputModes?: string[];
+  /** Enable streaming */
+  streaming?: boolean;
+  /** Enable push notifications */
+  pushNotifications?: boolean;
+  /** Provider info */
+  provider?: { organization: string; url?: string };
+}
+
+export interface SkillConfig {
+  id: string;
+  name: string;
+  description: string;
+  tags?: string[];
+  examples?: string[];
+}
+
+// ─── Server ────────────────────────────────────────────────────────────────
+
+export interface ServerConfig {
+  /** A2A server port */
+  port?: number;
+  /** Bind address */
+  hostname?: string;
+  /** Hostname advertised in agent card URLs */
+  advertiseHost?: string;
+  /** Protocol for advertised URLs */
+  advertiseProtocol?: 'http' | 'https';
+}
+
+// ─── Session ───────────────────────────────────────────────────────────────
+
+export interface SessionConfig {
+  /** Session title prefix */
+  titlePrefix?: string;
+  /** Reuse sessions by A2A contextId */
+  reuseByContext?: boolean;
+  /** Session TTL in ms */
+  ttl?: number;
+  /** Cleanup interval in ms */
+  cleanupInterval?: number;
+}
+
+// ─── Features / Timeouts / Logging ─────────────────────────────────────────
+
+export interface FeatureFlags {
+  /** Auto-approve all permission requests */
+  autoApprovePermissions?: boolean;
+  /** Auto-answer question prompts */
+  autoAnswerQuestions?: boolean;
+  /** Stream artifact chunks individually vs buffer */
+  streamArtifactChunks?: boolean;
+  /** Enable polling fallback on SSE failure */
+  enablePollingFallback?: boolean;
+}
+
+export interface TimeoutConfig {
+  /** Timeout for a single prompt in ms */
+  prompt?: number;
+  /** Polling interval in ms */
+  pollingInterval?: number;
+  /** Health check interval in ms */
+  healthCheck?: number;
+}
+
+export interface LoggingConfig {
+  /** Log level */
+  level?: 'debug' | 'info' | 'warn' | 'error';
+}
+
+// ─── Provider Configs ──────────────────────────────────────────────────────
+
+export interface OpenCodeConfig {
+  /** OpenCode server base URL */
+  baseUrl?: string;
+  /** Target project directory */
+  projectDirectory?: string;
+  /** Model identifier (e.g. "anthropic/claude-sonnet-4-20250514") */
+  model?: string;
+  /** Agent preset name */
+  agent?: string;
+  /** System prompt */
+  systemPrompt?: string;
+  /** How system prompt is applied */
+  systemPromptMode?: 'append' | 'replace';
+  /** Context file name */
+  contextFile?: string;
+  /** Prompt for building context */
+  contextPrompt?: string;
+}
+
+export interface CodexConfig {
+  /** Codex CLI path */
+  cliPath?: string;
+  /** Working directory */
+  workdir?: string;
+  /** Model identifier */
+  model?: string;
+  /** API key for OpenAI */
+  apiKey?: string;
+}
+
+export interface ClaudeCodeConfig {
+  /** Claude Code CLI path */
+  cliPath?: string;
+  /** Working directory */
+  workdir?: string;
+  /** Model identifier */
+  model?: string;
+  /** API key for Anthropic */
+  apiKey?: string;
+}
+
+// ─── Root Config ───────────────────────────────────────────────────────────
+
+export type ProviderType = 'opencode' | 'codex' | 'claude';
+
+export interface AgentConfig {
+  /** Active provider to use */
+  provider: ProviderType;
+  /** Agent card identity */
+  agentCard: AgentCardConfig;
+  /** Server settings */
+  server?: ServerConfig;
+  /** Session management */
+  session?: SessionConfig;
+  /** Feature flags */
+  features?: FeatureFlags;
+  /** Timeout settings */
+  timeouts?: TimeoutConfig;
+  /** Logging settings */
+  logging?: LoggingConfig;
+  /** Provider-specific connection configs */
+  opencode?: OpenCodeConfig;
+  codex?: CodexConfig;
+  claude?: ClaudeCodeConfig;
+  /** Directory containing config file (populated at runtime) */
+  configDir?: string;
+}

package/src/executors/claude/client.ts

@@ -0,0 +1,138 @@
+/**
+ * Claude Code CLI client wrapper.
+ *
+ * Spawns the Anthropic Claude Code CLI as a child process in non-interactive
+ * print mode (`-p`). Sends prompts, captures stdout as the response.
+ * Supports configurable CLI path, working directory, model, and timeout.
+ */
+
+import { spawn } from 'node:child_process';
+import { logger } from '../../logger.js';
+
+const log = logger.child('claude:client');
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ClaudeClientConfig {
+  /** Path to the claude binary (default: "claude") */
+  cliPath: string;
+  /** Working directory for the process */
+  workdir: string;
+  /** Model identifier (e.g. "claude-sonnet-4-20250514") — passed via --model */
+  model?: string;
+  /** Anthropic API key — passed as ANTHROPIC_API_KEY env */
+  apiKey?: string;
+  /** Timeout in ms (default: 300_000 = 5 min) */
+  timeout?: number;
+}
+
+// ─── Client ─────────────────────────────────────────────────────────────────
+
+export class ClaudeClient {
+  private currentChild: ReturnType<typeof spawn> | null = null;
+
+  constructor(private config: ClaudeClientConfig) {}
+
+  abort(): void {
+    if (this.currentChild) {
+      this.currentChild.kill('SIGTERM');
+      setTimeout(() => {
+        if (this.currentChild?.exitCode === null) {
+          this.currentChild.kill('SIGKILL');
+        }
+      }, 5000);
+      this.currentChild = null;
+    }
+  }
+
+  /**
+   * Execute a prompt via the Claude Code CLI and return the response text.
+   */
+  async execute(prompt: string): Promise<string> {
+    const cliPath = this.config.cliPath || 'claude';
+    const timeout = this.config.timeout ?? 300_000;
+    const MAX_PROMPT = 100_000;
+
+    if (prompt.length > MAX_PROMPT) {
+      throw new Error(`Prompt too large (${prompt.length} chars, max ${MAX_PROMPT}). Split into smaller messages.`);
+    }
+
+    // Only pass relevant env vars to child process
+    const env: Record<string, string> = {
+      PATH: process.env.PATH ?? '',
+      HOME: process.env.HOME ?? '',
+    };
+    // Forward common proxy/no-proxy settings
+    for (const key of ['HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy']) {
+      if (process.env[key]) env[key] = process.env[key];
+    }
+
+    if (this.config.apiKey) {
+      env['ANTHROPIC_API_KEY'] = this.config.apiKey;
+    }
+
+    const args: string[] = ['-p'];
+    if (this.config.model) {
+      args.push('--model', this.config.model);
+    }
+    args.push(prompt);
+
+    log.info('Spawning claude', { cliPath, workdir: this.config.workdir, model: this.config.model });
+
+    return new Promise<string>((resolve, reject) => {
+      const child = spawn(cliPath, args, {
+        cwd: this.config.workdir || process.cwd(),
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      this.currentChild = child;
+
+      let stdout = '';
+      let stderr = '';
+      const MAX_OUTPUT = 10_000_000;
+
+      const timer = setTimeout(() => {
+        child.kill('SIGTERM');
+        // Force kill after 5s grace period
+        const forceTimer = setTimeout(() => {
+          if (child.exitCode === null) child.kill('SIGKILL');
+        }, 5000);
+        child.on('close', () => clearTimeout(forceTimer));
+        reject(new Error(`Claude Code execution timed out after ${timeout}ms`));
+      }, timeout);
+
+      child.stdout?.on('data', (chunk: Buffer) => {
+        stdout += chunk.toString();
+        if (stdout.length > MAX_OUTPUT) {
+          child.kill('SIGTERM');
+          setTimeout(() => { if (child.exitCode === null) child.kill('SIGKILL'); }, 5000);
+        }
+      });
+
+      child.stderr?.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString();
+        log.debug('Claude stderr', { text: chunk.toString().trim() });
+      });
+
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        this.currentChild = null;
+
+        if (code === 0) {
+          resolve(stdout.trim());
+        } else {
+          const errMsg = stderr.trim() || stdout.trim() || `Claude Code exited with code ${code}`;
+          log.warn('Claude non-zero exit', { code, stderr: errMsg });
+          reject(new Error(errMsg));
+        }
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        log.error('Claude spawn failed', { error: err.message });
+        reject(new Error(`Failed to start claude: ${err.message}. Install: npm i -g @anthropic-ai/claude-code`));
+      });
+    });
+  }
+}

package/src/executors/claude/executor.ts

@@ -0,0 +1,111 @@
+/**
+ * Claude Code A2A Executor
+ *
+ * Bridges the local Claude Code CLI to the A2A protocol. Spawns Claude Code
+ * in non-interactive print mode (`-p`) for each request and captures stdout
+ * as the response.
+ */
+
+import type { A2AExecutor } from '../index.js';
+import type { RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
+import type { Message as A2AMessage } from '@a2a-js/sdk';
+
+import type { AgentConfig } from '../../config/types.js';
+import { logger } from '../../logger.js';
+import { ClaudeClient } from './client.js';
+import {
+  publishTask,
+  publishStatus,
+  publishFinalArtifact,
+} from '../events.js';
+
+const log = logger.child('claude:executor');
+
+// ─── Executor ───────────────────────────────────────────────────────────────
+
+export class ClaudeExecutor implements A2AExecutor {
+  private config: Required<AgentConfig>;
+  private client: ClaudeClient | null = null;
+  private initialized = false;
+
+  constructor(config: Required<AgentConfig>) {
+    this.config = config;
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    const cc = this.config.claude;
+    this.client = new ClaudeClient({
+      cliPath: cc.cliPath!,
+      workdir: cc.workdir!,
+      model: cc.model || undefined,
+      apiKey: cc.apiKey || undefined,
+      timeout: this.config.timeouts.prompt ?? 600_000,
+    });
+
+    this.initialized = true;
+    log.info('Executor initialized', { cliPath: cc.cliPath, workdir: cc.workdir });
+  }
+
+  async shutdown(): Promise<void> {
+    this.client = null;
+    this.initialized = false;
+    log.info('Executor shut down');
+  }
+
+  async execute(ctx: RequestContext, bus: ExecutionEventBus): Promise<void> {
+    const { taskId, contextId, userMessage, task } = ctx;
+    await this.initialize();
+
+    try {
+      if (!task) {
+        publishTask(bus, taskId, contextId);
+        publishStatus(bus, taskId, contextId, 'submitted');
+      }
+
+      publishStatus(bus, taskId, contextId, 'working', 'Processing request...');
+
+      const promptText = this.extractText(userMessage);
+      log.info('Sending prompt to Claude Code', { taskId, len: promptText.length });
+
+      const response = await this.client!.execute(promptText);
+
+      const finalText = response || 'No response from Claude Code.';
+      publishFinalArtifact(bus, taskId, contextId, finalText);
+      publishStatus(bus, taskId, contextId, 'completed', undefined, true);
+      bus.finished();
+      log.info('Task completed', { taskId, len: finalText.length });
+
+    } catch (error) {
+      const msg = (error as Error).message ?? String(error);
+      log.error('Execution failed', { taskId, error: msg });
+      publishStatus(bus, taskId, contextId, 'failed', `Error: ${msg}`, true);
+      bus.finished();
+    }
+  }
+
+  async cancelTask(taskId: string, bus: ExecutionEventBus): Promise<void> {
+    log.info('Cancel requested for Claude Code task', { taskId });
+    this.client?.abort();
+    publishStatus(bus, taskId, '', 'canceled', 'Claude Code task cancelled', true);
+    bus.finished();
+  }
+
+  private extractText(message: A2AMessage): string {
+    return message.parts
+      .filter((p) => {
+        const part = p as unknown as Record<string, unknown>;
+        const text = part.text as string | undefined;
+        return text !== undefined && text !== null;
+      })
+      .map((p) => (p as unknown as { text: string }).text)
+      .join('\n');
+  }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+export function createClaudeExecutor(config: Required<AgentConfig>): A2AExecutor {
+  return new ClaudeExecutor(config);
+}

package/src/executors/codex/client.ts

@@ -0,0 +1,139 @@
+/**
+ * Codex CLI client wrapper.
+ *
+ * Spawns the OpenAI Codex CLI as a child process, sends prompts via stdin,
+ * captures stdout as the response. Supports configurable CLI path, working
+ * directory, model selection, and timeout.
+ */
+
+import { spawn } from 'node:child_process';
+import { logger } from '../../logger.js';
+
+const log = logger.child('codex:client');
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface CodexClientConfig {
+  /** Path to the codex binary (default: "codex") */
+  cliPath: string;
+  /** Working directory for the codex process */
+  workdir: string;
+  /** Model identifier (e.g. "gpt-4o") — passed as CODELLM env or --model flag */
+  model?: string;
+  /** OpenAI API key — passed as OPENAI_API_KEY env */
+  apiKey?: string;
+  /** Timeout in ms (default: 300_000 = 5 min) */
+  timeout?: number;
+}
+
+// ─── Client ─────────────────────────────────────────────────────────────────
+
+export class CodexClient {
+  private currentChild: ReturnType<typeof spawn> | null = null;
+
+  constructor(private config: CodexClientConfig) {}
+
+  abort(): void {
+    if (this.currentChild) {
+      this.currentChild.kill('SIGTERM');
+      setTimeout(() => {
+        if (this.currentChild?.exitCode === null) {
+          this.currentChild.kill('SIGKILL');
+        }
+      }, 5000);
+      this.currentChild = null;
+    }
+  }
+
+  /**
+   * Execute a prompt via the Codex CLI and return the response text.
+   */
+  async execute(prompt: string): Promise<string> {
+    const cliPath = this.config.cliPath || 'codex';
+    const timeout = this.config.timeout ?? 300_000;
+    const MAX_PROMPT = 100_000;
+
+    if (prompt.length > MAX_PROMPT) {
+      throw new Error(`Prompt too large (${prompt.length} chars, max ${MAX_PROMPT}). Split into smaller messages.`);
+    }
+
+    // Only pass relevant env vars to child process
+    const env: Record<string, string> = {
+      PATH: process.env.PATH ?? '',
+      HOME: process.env.HOME ?? '',
+    };
+    // Forward common proxy/no-proxy settings
+    for (const key of ['HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy']) {
+      if (process.env[key]) env[key] = process.env[key];
+    }
+
+    if (this.config.apiKey) {
+      env['OPENAI_API_KEY'] = this.config.apiKey;
+    }
+
+    const args: string[] = [];
+    // Some codex versions support --model flag
+    if (this.config.model) {
+      args.push('--model', this.config.model);
+    }
+    args.push(prompt);
+
+    log.info('Spawning codex', { cliPath, workdir: this.config.workdir, model: this.config.model });
+
+    return new Promise<string>((resolve, reject) => {
+      const child = spawn(cliPath, args, {
+        cwd: this.config.workdir || process.cwd(),
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      this.currentChild = child;
+
+      let stdout = '';
+      let stderr = '';
+      const MAX_OUTPUT = 10_000_000;
+
+      const timer = setTimeout(() => {
+        child.kill('SIGTERM');
+        // Force kill after 5s grace period
+        const forceTimer = setTimeout(() => {
+          if (child.exitCode === null) child.kill('SIGKILL');
+        }, 5000);
+        child.on('close', () => clearTimeout(forceTimer));
+        reject(new Error(`Codex execution timed out after ${timeout}ms`));
+      }, timeout);
+
+      child.stdout?.on('data', (chunk: Buffer) => {
+        stdout += chunk.toString();
+        if (stdout.length > MAX_OUTPUT) {
+          child.kill('SIGTERM');
+          setTimeout(() => { if (child.exitCode === null) child.kill('SIGKILL'); }, 5000);
+        }
+      });
+
+      child.stderr?.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString();
+        log.debug('Codex stderr', { text: chunk.toString().trim() });
+      });
+
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        this.currentChild = null;
+
+        if (code === 0) {
+          resolve(stdout.trim());
+        } else {
+          const errMsg = stderr.trim() || stdout.trim() || `Codex exited with code ${code}`;
+          log.warn('Codex non-zero exit', { code, stderr: errMsg });
+          reject(new Error(errMsg));
+        }
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        log.error('Codex spawn failed', { error: err.message });
+        reject(new Error(`Failed to start codex: ${err.message}. Is it installed? (npm i -g @openai/codex)`));
+      });
+    });
+  }
+}

package/src/executors/codex/executor.ts

@@ -0,0 +1,118 @@
+/**
+ * Codex A2A Executor
+ *
+ * Bridges the local Codex CLI to the A2A protocol. Spawns Codex as a
+ * child process for each request and captures stdout as the response.
+ */
+
+import type { A2AExecutor } from '../index.js';
+import type { RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
+import type { Message as A2AMessage } from '@a2a-js/sdk';
+
+import type { AgentConfig } from '../../config/types.js';
+import { logger } from '../../logger.js';
+import { CodexClient } from './client.js';
+import {
+  publishTask,
+  publishStatus,
+  publishFinalArtifact,
+} from '../events.js';
+
+const log = logger.child('codex:executor');
+
+// ─── Executor ───────────────────────────────────────────────────────────────
+
+export class CodexExecutor implements A2AExecutor {
+  private config: Required<AgentConfig>;
+  private client: CodexClient | null = null;
+  private initialized = false;
+
+  constructor(config: Required<AgentConfig>) {
+    this.config = config;
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    const cx = this.config.codex;
+    this.client = new CodexClient({
+      cliPath: cx.cliPath!,
+      workdir: cx.workdir!,
+      model: cx.model || undefined,
+      apiKey: cx.apiKey || undefined,
+      timeout: this.config.timeouts.prompt ?? 600_000,
+    });
+
+    this.initialized = true;
+    log.info('Executor initialized', { cliPath: cx.cliPath, workdir: cx.workdir });
+  }
+
+  async shutdown(): Promise<void> {
+    this.client = null;
+    this.initialized = false;
+    log.info('Executor shut down');
+  }
+
+  async execute(ctx: RequestContext, bus: ExecutionEventBus): Promise<void> {
+    const { taskId, contextId, userMessage, task } = ctx;
+    await this.initialize();
+
+    try {
+      // 1. Register task
+      if (!task) {
+        publishTask(bus, taskId, contextId);
+        publishStatus(bus, taskId, contextId, 'submitted');
+      }
+
+      // 2. Working
+      publishStatus(bus, taskId, contextId, 'working', 'Processing request...');
+
+      // 3. Extract prompt text
+      const promptText = this.extractText(userMessage);
+
+      log.info('Sending prompt to Codex', { taskId, len: promptText.length });
+
+      // 4. Execute
+      const response = await this.client!.execute(promptText);
+
+      // 5. Finalize
+      const finalText = response || 'No response from Codex.';
+      publishFinalArtifact(bus, taskId, contextId, finalText);
+      publishStatus(bus, taskId, contextId, 'completed', undefined, true);
+      bus.finished();
+      log.info('Task completed', { taskId, len: finalText.length });
+
+    } catch (error) {
+      const msg = (error as Error).message ?? String(error);
+      log.error('Execution failed', { taskId, error: msg });
+      publishStatus(bus, taskId, contextId, 'failed', `Error: ${msg}`, true);
+      bus.finished();
+    }
+  }
+
+  async cancelTask(taskId: string, bus: ExecutionEventBus): Promise<void> {
+    log.info('Cancel requested for Codex task', { taskId });
+    this.client?.abort();
+    publishStatus(bus, taskId, '', 'canceled', 'Codex task cancelled', true);
+    bus.finished();
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────
+
+  private extractText(message: A2AMessage): string {
+    return message.parts
+      .filter((p) => {
+        const part = p as unknown as Record<string, unknown>;
+        const text = part.text as string | undefined;
+        return text !== undefined && text !== null;
+      })
+      .map((p) => (p as unknown as { text: string }).text)
+      .join('\n');
+  }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+export function createCodexExecutor(config: Required<AgentConfig>): A2AExecutor {
+  return new CodexExecutor(config);
+}