@axiom-lattice/cli-a2a 0.1.1

package/src/executors/events.ts

@@ -0,0 +1,117 @@
+/**
+ * A2A event publishing helpers.
+ *
+ * Thin wrappers around ExecutionEventBus.publish() that construct
+ * spec-compliant A2A task status and artifact update events.
+ */
+
+import { TaskState } from '@a2a-js/sdk';
+import type { TaskStatusUpdateEvent, TaskArtifactUpdateEvent } from '@a2a-js/sdk';
+import type { ExecutionEventBus } from '@a2a-js/sdk/server';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Register a task with the execution event bus before publishing any events.
+ */
+export function publishTask(bus: ExecutionEventBus, taskId: string, contextId: string): void {
+  bus.publish({
+    kind: 'task',
+    taskId,
+    contextId,
+  } as unknown as TaskStatusUpdateEvent);
+}
+
+/**
+ * Publish a task status update.
+ */
+export function publishStatus(
+  bus: ExecutionEventBus,
+  taskId: string,
+  contextId: string,
+  state: TaskState | string,
+  messageText?: string,
+  final?: boolean,
+): void {
+  const event: TaskStatusUpdateEvent = {
+    kind: 'task-status-update',
+    taskId,
+    contextId,
+    status: {
+      state: state as TaskState,
+      message: messageText
+        ? { role: 'agent', parts: [{ kind: 'text', text: messageText }] }
+        : undefined,
+    },
+    final: final ?? false,
+  } as unknown as TaskStatusUpdateEvent;
+  bus.publish(event);
+}
+
+/**
+ * Publish a complete artifact (non-streaming).
+ */
+export function publishFinalArtifact(
+  bus: ExecutionEventBus,
+  taskId: string,
+  contextId: string,
+  text: string,
+): void {
+  const artifactId = uuidv4();
+  const event: TaskArtifactUpdateEvent = {
+    kind: 'task-artifact-update',
+    taskId,
+    contextId,
+    artifact: {
+      artifactId,
+      parts: [{ kind: 'text', text }],
+    },
+    lastChunk: true,
+  } as unknown as TaskArtifactUpdateEvent;
+  bus.publish(event);
+}
+
+/**
+ * Publish a streaming artifact chunk.
+ */
+export function publishStreamingChunk(
+  bus: ExecutionEventBus,
+  taskId: string,
+  contextId: string,
+  artifactId: string,
+  chunkText: string,
+): void {
+  const event: TaskArtifactUpdateEvent = {
+    kind: 'task-artifact-update',
+    taskId,
+    contextId,
+    artifact: {
+      artifactId,
+      parts: [{ kind: 'text', text: chunkText }],
+    },
+    lastChunk: false,
+  } as unknown as TaskArtifactUpdateEvent;
+  bus.publish(event);
+}
+
+/**
+ * Publish the final streaming chunk with full accumulated text.
+ */
+export function publishLastChunkMarker(
+  bus: ExecutionEventBus,
+  taskId: string,
+  contextId: string,
+  artifactId: string,
+  fullText: string,
+): void {
+  const event: TaskArtifactUpdateEvent = {
+    kind: 'task-artifact-update',
+    taskId,
+    contextId,
+    artifact: {
+      artifactId,
+      parts: [{ kind: 'text', text: fullText }],
+    },
+    lastChunk: true,
+  } as unknown as TaskArtifactUpdateEvent;
+  bus.publish(event);
+}

package/src/executors/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Executor types and common interfaces for CLI A2A providers.
+ *
+ * Each provider (OpenCode, Codex, Claude) implements its own executor
+ * conforming to the A2AExecutor interface which extends the SDK's
+ * AgentExecutor with lifecycle methods (initialize, shutdown).
+ */
+
+import type { AgentExecutor } from '@a2a-js/sdk/server';
+
+/**
+ * Extended executor interface with lifecycle methods.
+ *
+ * The base AgentExecutor from @a2a-js/sdk only defines execute() and
+ * cancelTask(). We add initialize() for server setup and shutdown()
+ * for graceful cleanup.
+ */
+export interface A2AExecutor extends AgentExecutor {
+  initialize(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export type { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
+export { TaskState } from '@a2a-js/sdk';
+export { v4 as uuidv4 } from 'uuid';
+
+import type { AgentConfig, ProviderType } from '../config/types.js';
+
+/**
+ * Factory function type: given resolved config, produce an executor.
+ */
+export type ExecutorFactory = (config: Required<AgentConfig>) => A2AExecutor;
+
+/**
+ * Map provider type to executor factory.
+ */
+const registry = new Map<ProviderType, ExecutorFactory>();
+
+export function registerExecutor(provider: ProviderType, factory: ExecutorFactory): void {
+  registry.set(provider, factory);
+}
+
+export function getExecutor(provider: ProviderType): ExecutorFactory | undefined {
+  return registry.get(provider);
+}
+
+export function createExecutor(config: Required<AgentConfig>): A2AExecutor {
+  const factory = registry.get(config.provider);
+  if (!factory) {
+    const available = Array.from(registry.keys()).join(', ');
+    throw new Error(`Unknown provider: ${config.provider}. Available: ${available}`);
+  }
+  return factory(config);
+}

package/src/executors/opencode/client.ts

@@ -0,0 +1,149 @@
+/**
+ * OpenCode CLI client wrapper.
+ *
+ * Spawns the OpenCode CLI as a child process. Uses `opencode run` with
+ * optional `--attach` to connect to an existing server. Captures stdout
+ * as the response. Same pattern as Codex and Claude Code clients.
+ */
+
+import { spawn } from 'node:child_process';
+import { logger } from '../../logger.js';
+
+const log = logger.child('opencode:client');
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface OpenCodeClientConfig {
+  /** Path to the opencode binary (default: "opencode") */
+  cliPath: string;
+  /** Working directory for the process */
+  workdir: string;
+  /** Model identifier (e.g. "anthropic/claude-sonnet-4") */
+  model?: string;
+  /** Agent preset name */
+  agent?: string;
+  /** Optional URL of a running OpenCode server to attach to */
+  attachUrl?: string;
+  /** Timeout in ms (default: 600_000 = 10 min) */
+  timeout?: number;
+}
+
+// ─── Client ─────────────────────────────────────────────────────────────────
+
+export class OpenCodeClient {
+  private currentChild: ReturnType<typeof spawn> | null = null;
+
+  constructor(private config: OpenCodeClientConfig) {}
+
+  /** Abort the currently running child process (if any). */
+  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 OpenCode CLI and return the response text.
+   */
+  async execute(prompt: string): Promise<string> {
+    const cliPath = this.config.cliPath || 'opencode';
+    const timeout = this.config.timeout ?? 600_000;
+    const MAX_PROMPT = 100_000; // safe below typical ARG_MAX
+
+    if (prompt.length > MAX_PROMPT) {
+      throw new Error(`Prompt too large (${prompt.length} chars, max ${MAX_PROMPT}). Split into smaller messages or use a provider with HTTP API transport.`);
+    }
+
+    // Only pass essential env vars
+    const env: Record<string, string> = {
+      PATH: process.env.PATH ?? '',
+      HOME: process.env.HOME ?? '',
+    };
+    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];
+    }
+    // Forward auth env vars if present
+    for (const key of ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENCODE_SERVER_PASSWORD', 'OPENCODE_SERVER_USERNAME']) {
+      if (process.env[key]) env[key] = process.env[key];
+    }
+
+    const args: string[] = ['run', prompt];
+
+    if (this.config.model) {
+      args.push('--model', this.config.model);
+    }
+    if (this.config.agent) {
+      args.push('--agent', this.config.agent);
+    }
+    if (this.config.attachUrl) {
+      args.push('--attach', this.config.attachUrl);
+    }
+    // Default format captures plain text output
+    args.push('--format', 'default');
+    // Never go interactive
+    args.push('--dangerously-skip-permissions');
+
+    log.info('Spawning opencode', { 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; // 10MB
+
+      const timer = setTimeout(() => {
+        child.kill('SIGTERM');
+        const forceTimer = setTimeout(() => {
+          if (child.exitCode === null) child.kill('SIGKILL');
+        }, 5000);
+        child.on('close', () => clearTimeout(forceTimer));
+        reject(new Error(`OpenCode 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('OpenCode 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() || `OpenCode exited with code ${code}`;
+          log.warn('OpenCode non-zero exit', { code, stderr: errMsg });
+          reject(new Error(errMsg));
+        }
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        log.error('OpenCode spawn failed', { error: err.message });
+        reject(new Error(`Failed to start opencode: ${err.message}. Is it installed?`));
+      });
+    });
+  }
+}

package/src/executors/opencode/executor.ts

@@ -0,0 +1,112 @@
+/**
+ * OpenCode A2A Executor
+ *
+ * Bridges the local OpenCode CLI to the A2A protocol. Spawns `opencode run`
+ * as a child process for each request and captures stdout as the response.
+ * Same spawn pattern as Codex and Claude Code executors.
+ */
+
+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 { OpenCodeClient } from './client.js';
+import {
+  publishTask,
+  publishStatus,
+  publishFinalArtifact,
+} from '../events.js';
+
+const log = logger.child('opencode:executor');
+
+// ─── Executor ───────────────────────────────────────────────────────────────
+
+export class OpenCodeExecutor implements A2AExecutor {
+  private config: Required<AgentConfig>;
+  private client: OpenCodeClient | null = null;
+  private initialized = false;
+
+  constructor(config: Required<AgentConfig>) {
+    this.config = config;
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    const oc = this.config.opencode;
+    this.client = new OpenCodeClient({
+      cliPath: 'opencode',
+      workdir: oc.projectDirectory || process.cwd(),
+      model: oc.model || undefined,
+      agent: oc.agent || undefined,
+      attachUrl: oc.baseUrl || undefined,
+      timeout: this.config.timeouts.prompt ?? 600_000,
+    });
+
+    this.initialized = true;
+    log.info('Executor initialized', { workdir: oc.projectDirectory, model: oc.model });
+  }
+
+  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 OpenCode', { taskId, len: promptText.length });
+
+      const response = await this.client!.execute(promptText);
+
+      const finalText = response || 'No response from OpenCode.';
+      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 OpenCode task', { taskId });
+    this.client?.abort();
+    publishStatus(bus, taskId, '', 'canceled', 'OpenCode 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 createOpenCodeExecutor(config: Required<AgentConfig>): A2AExecutor {
+  return new OpenCodeExecutor(config);
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @axiom-lattice/cli-a2a
+ *
+ * Multi-provider A2A (Agent-to-Agent) CLI gateway.
+ * Wraps local coding agents as spec-compliant A2A servers.
+ *
+ * @example
+ * ```bash
+ * npx @axiom-lattice/cli-a2a --provider opencode --config agents/example.json
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createA2AServer, resolveConfig } from '@axiom-lattice/cli-a2a';
+ * const config = resolveConfig('path/to/config.json');
+ * const server = await createA2AServer(config);
+ * ```
+ */
+
+// Config
+export { resolveConfig, loadConfigFile } from './config/index.js';
+export type {
+  AgentConfig,
+  ProviderType,
+  AgentCardConfig,
+  SkillConfig,
+  ServerConfig,
+  SessionConfig,
+  FeatureFlags,
+  TimeoutConfig,
+  LoggingConfig,
+  OpenCodeConfig,
+  CodexConfig,
+  ClaudeCodeConfig,
+} from './config/index.js';
+
+// Server
+export { createA2AServer } from './server/index.js';
+export type { ServerHandle } from './server/index.js';
+
+// Executors
+export {
+  registerExecutor,
+  getExecutor,
+  createExecutor,
+} from './executors/index.js';
+export type { A2AExecutor, ExecutorFactory } from './executors/index.js';
+export { createOpenCodeExecutor, OpenCodeExecutor } from './executors/opencode/executor.js';
+export { createCodexExecutor, CodexExecutor } from './executors/codex/executor.js';
+export { createClaudeExecutor, ClaudeExecutor } from './executors/claude/executor.js';
+export type { AgentExecutor, RequestContext, ExecutionEventBus } from './executors/index.js';
+
+// Logger
+export { logger, LogLevel } from './logger.js';

package/src/logger.ts

@@ -0,0 +1,78 @@
+/**
+ * Lightweight structured logger for the CLI A2A gateway.
+ *
+ * Uses pino-compatible structured logging. In production mode the output is
+ * JSON; in dev mode it is pretty-printed via pino-pretty.
+ */
+
+export enum LogLevel {
+  DEBUG = 10,
+  INFO = 20,
+  WARN = 30,
+  ERROR = 40,
+}
+
+interface LogEntry {
+  level: LogLevel;
+  msg: string;
+  ctx: Record<string, unknown>;
+  ts: string;
+}
+
+class Logger {
+  private level: LogLevel = LogLevel.INFO;
+  private name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  child(name: string): Logger {
+    const childLogger = new Logger(`${this.name}:${name}`);
+    childLogger.level = this.level;
+    return childLogger;
+  }
+
+  debug(msg: string, ctx?: Record<string, unknown>): void {
+    this.log(LogLevel.DEBUG, msg, ctx);
+  }
+
+  info(msg: string, ctx?: Record<string, unknown>): void {
+    this.log(LogLevel.INFO, msg, ctx);
+  }
+
+  warn(msg: string, ctx?: Record<string, unknown>): void {
+    this.log(LogLevel.WARN, msg, ctx);
+  }
+
+  error(msg: string, ctx?: Record<string, unknown>): void {
+    this.log(LogLevel.ERROR, msg, ctx);
+  }
+
+  private log(level: LogLevel, msg: string, ctx?: Record<string, unknown>): void {
+    if (level < this.level) return;
+
+    const entry: LogEntry = {
+      level,
+      msg,
+      ctx: { name: this.name, ...ctx },
+      ts: new Date().toISOString(),
+    };
+
+    const output = process.env.NODE_ENV === 'production'
+      ? JSON.stringify(entry)
+      : `${entry.ts} [${LogLevel[entry.level]}] ${entry.ctx.name}: ${msg}${ctx && Object.keys(ctx).length > 1 ? ' ' + JSON.stringify(ctx) : ''}`;
+
+    if (level >= LogLevel.WARN) {
+      process.stderr.write(output + '\n');
+    } else {
+      process.stdout.write(output + '\n');
+    }
+  }
+}
+
+export const logger = new Logger('cli-a2a');

package/src/server/agent-card.ts

@@ -0,0 +1,51 @@
+/**
+ * Agent Card builder.
+ *
+ * Builds an A2A-compliant AgentCard from the resolved config.
+ */
+
+import type { AgentCard, AgentSkill } from '@a2a-js/sdk';
+import type { AgentConfig } from '../config/types.js';
+import { logger } from '../logger.js';
+
+const log = logger.child('agent-card');
+
+export function buildAgentCard(config: Required<AgentConfig>): AgentCard {
+  const { agentCard, server } = config;
+  const proto = server.advertiseProtocol ?? 'http';
+  const host = server.advertiseHost ?? 'localhost';
+  const port = server.port ?? 3000;
+  const baseUrl = `${proto}://${host}:${port}`;
+
+  const skills: AgentSkill[] = (agentCard.skills ?? []).map((s) => ({
+    id: s.id,
+    name: s.name,
+    description: s.description,
+    tags: s.tags ?? [],
+    examples: s.examples ?? [],
+  }));
+
+  const card: AgentCard = {
+    name: agentCard.name,
+    description: agentCard.description,
+    protocolVersion: agentCard.protocolVersion ?? '0.3.0',
+    version: agentCard.version ?? '1.0.0',
+    url: `${baseUrl}/a2a/jsonrpc`,
+    // Default input/output modes (A2A v1.0 normalized names)
+    defaultInputModes: (agentCard.defaultInputModes as Array<'text' | 'file' | 'image' | 'audio'>) ?? ['text'],
+    defaultOutputModes: (agentCard.defaultOutputModes as Array<'text' | 'file' | 'image' | 'audio'>) ?? ['text'],
+    skills,
+    capabilities: {
+      streaming: agentCard.streaming ?? true,
+      pushNotifications: agentCard.pushNotifications ?? false,
+    },
+    // Additional interfaces advertised to orchestrators
+    additionalInterfaces: [
+      { transport: 'JSONRPC', url: `${baseUrl}/a2a/jsonrpc` },
+      { transport: 'REST', url: `${baseUrl}/a2a/rest` },
+    ],
+  };
+
+  log.info('Agent card built', { name: card.name, url: card.url, skills: card.skills?.length ?? 0 });
+  return card;
+}