plumb-bridge 0.1.0

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+root = "."

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "plumb-bridge",
+  "version": "0.1.0",
+  "description": "A2A bridge for CLI coding agents. Bun runtime. Example: plumb wrap cat --port 3001. Use plumb wrap opencode (not opencode run — the adapter adds run --format json).",
+  "type": "module",
+  "module": "src/main.ts",
+  "bin": {
+    "plumb": "src/main.ts"
+  },
+  "files": [
+    "src",
+    "test",
+    "tsconfig.json",
+    "bunfig.toml"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "start": "bun run src/main.ts",
+    "wrap": "bun run src/main.ts wrap",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test test/conformance.test.ts",
+    "prepack": "npm run typecheck",
+    "prepublishOnly": "npm run test && npm run typecheck"
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "^0.3.13",
+    "commander": "^14.0.3",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/express": "^5.0.6",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/adapters/claude.ts

@@ -0,0 +1,109 @@
+// PLUMB — Claude Adapter
+// Wraps `claude --print --output-format stream-json --verbose`. Streaming JSONL.
+// Filters system/rate-limit events. Captures assistant messages and results.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AgentAdapter, AgentTask, AdapterEvent, DetectionResult, PlumbConfig } from '../types.ts';
+
+const execFileAsync = promisify(execFile);
+
+interface ClaudeStreamEvent {
+  type: string;
+  subtype?: string;
+  message?: {
+    content?: Array<{ type: string; text?: string }>;
+  };
+  result?: string;
+  is_error?: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+export class ClaudeAdapter implements AgentAdapter {
+  readonly id = 'claude';
+  readonly binary = 'claude';
+  readonly tier = 1 as const;
+  readonly displayName = 'Claude';
+  readonly mode = 'oneshot' as const;
+
+  skills = [
+    { id: 'code', name: 'Code generation and editing', tags: ['code', 'edit', 'write'] },
+    { id: 'bash', name: 'Execute shell commands', tags: ['bash', 'shell', 'terminal'] },
+    { id: 'read', name: 'Read files', tags: ['read', 'file'] },
+    { id: 'web', name: 'Web search and fetch', tags: ['web', 'search', 'fetch'] },
+  ];
+
+  buildArgs(_task: AgentTask, _config: PlumbConfig): string[] {
+    return ['--print', '--output-format', 'stream-json', '--verbose'];
+  }
+
+  formatInput(task: AgentTask): string {
+    return task.message + '\n';
+  }
+
+  parseLine(line: string): AdapterEvent[] {
+    if (!line.trim()) return [];
+
+    let event: ClaudeStreamEvent;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      // Non-JSON line — treat as raw text
+      return [{ type: 'text-delta', text: line + '\n' }];
+    }
+
+    // Filter non-content events
+    if (event.type === 'rate_limit_event') return [];
+    if (event.type === 'system') return [];
+
+    // Assistant message — extract text content
+    if (event.type === 'assistant' && event.message?.content) {
+      const texts = event.message.content
+        .filter(c => c.type === 'text' && c.text)
+        .map(c => c.text!);
+      if (texts.length > 0) {
+        return [{ type: 'text-delta', text: texts.join('\n') }];
+      }
+      return [];
+    }
+
+    // Result event — final output
+    if (event.type === 'result') {
+      if (event.is_error || event.error) {
+        return [{ type: 'error', message: event.error ?? 'Unknown error' }];
+      }
+      // Result text is already captured from assistant message, signal completion
+      return [{ type: 'status', state: 'completed' }];
+    }
+
+    // Error event
+    if (event.type === 'error') {
+      return [{ type: 'error', message: String(event.error ?? event.message ?? 'Unknown error') }];
+    }
+
+    return [];
+  }
+
+  async detect(): Promise<DetectionResult | null> {
+    try {
+      const { stdout } = await execFileAsync('which', ['claude'], { timeout: 5000 });
+      let version = 'unknown';
+      try {
+        const { stdout: vOut } = await execFileAsync('claude', ['--version'], { timeout: 5000 });
+        version = vOut.trim().split('\n')[0] ?? 'unknown';
+      } catch {
+        // Version check failed
+      }
+      return {
+        binary: 'claude',
+        version,
+        path: stdout.trim(),
+        tier: 1,
+        protocol: 'stream-json',
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/adapters/echo.ts

@@ -0,0 +1,50 @@
+// PLUMB — Echo Adapter
+// Wraps `cat`. Proves the bridge works. Emits a real A2A task lifecycle.
+// Every line cat echoes becomes a progress event. Exit 0 → completed.
+// Stolen from fangai's Echo First pattern, implemented as a real CLI wrapper.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AgentAdapter, AgentTask, AdapterEvent, DetectionResult, PlumbConfig } from '../types.ts';
+
+const execFileAsync = promisify(execFile);
+
+export class EchoAdapter implements AgentAdapter {
+  readonly id = 'echo';
+  readonly binary = 'cat';
+  readonly tier = 1 as const;
+  readonly displayName = 'Echo';
+  readonly mode = 'oneshot' as const;
+
+  skills = [
+    { id: 'echo', name: 'Echo task input', tags: ['echo', 'test', 'conformance'] },
+  ];
+
+  buildArgs(_task: AgentTask, _config: PlumbConfig): string[] {
+    return [];
+  }
+
+  formatInput(task: AgentTask): string {
+    return task.message + '\n';
+  }
+
+  parseLine(line: string): AdapterEvent[] {
+    if (!line.trim()) return [];
+    return [{ type: 'text-delta', text: line + '\n' }];
+  }
+
+  async detect(): Promise<DetectionResult | null> {
+    try {
+      const { stdout } = await execFileAsync('which', ['cat'], { timeout: 5000 });
+      return {
+        binary: 'cat',
+        version: '1.0.0',
+        path: stdout.trim(),
+        tier: 1,
+        protocol: 'text',
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/adapters/generic.ts

@@ -0,0 +1,45 @@
+// PLUMB — Generic Adapter
+// Text passthrough. Wraps any CLI that reads stdin and writes to stdout.
+// Every non-empty line becomes a progress event. Exit 0 = complete.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AgentAdapter, AgentTask, AdapterEvent, DetectionResult, PlumbConfig } from '../types.ts';
+
+const execFileAsync = promisify(execFile);
+
+export class GenericAdapter implements AgentAdapter {
+  readonly id = 'generic';
+  readonly binary = '';
+  readonly tier = 3 as const;
+  readonly displayName = 'Generic CLI';
+  readonly mode = 'oneshot' as const;
+  private cliCommand: string;
+
+  skills = [{ id: 'generic', name: 'CLI task', tags: ['code'] }];
+
+  constructor(cliCommand = '') {
+    this.cliCommand = cliCommand;
+  }
+
+  buildArgs(_task: AgentTask, _config: PlumbConfig): string[] { return []; }
+
+  formatInput(task: AgentTask): string { return task.message + '\n'; }
+
+  parseLine(line: string): AdapterEvent[] {
+    if (!line.trim()) return [];
+    return [{ type: 'text-delta', text: line.trim() + '\n' }];
+  }
+
+  async detect(): Promise<DetectionResult | null> {
+    if (!this.cliCommand) return null;
+    try {
+      const [cmd] = this.cliCommand.trim().split(/\s+/);
+      if (!cmd) return null;
+      const { stdout } = await execFileAsync('which', [cmd], { timeout: 5000 });
+      return { binary: cmd, version: 'unknown', path: stdout.trim(), tier: 3, protocol: 'text' };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/adapters/opencode.ts

@@ -0,0 +1,117 @@
+// PLUMB — OpenCode Adapter
+// Wraps `opencode run --format json`. JSON event stream.
+// Filters log/status events. Captures text content and results.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AgentAdapter, AgentTask, AdapterEvent, DetectionResult, PlumbConfig } from '../types.ts';
+
+const execFileAsync = promisify(execFile);
+
+interface OpenCodePart {
+  type?: string;
+  text?: string;
+  reason?: string;
+  [key: string]: unknown;
+}
+
+interface OpenCodeEvent {
+  type: string;
+  content?: string;
+  text?: string;
+  part?: OpenCodePart;
+  delta?: string;
+  error?: string;
+  message?: string;
+  result?: string;
+  [key: string]: unknown;
+}
+
+export class OpenCodeAdapter implements AgentAdapter {
+  readonly id = 'opencode';
+  readonly binary = 'opencode';
+  readonly tier = 2 as const;
+  readonly displayName = 'OpenCode';
+  readonly mode = 'oneshot' as const;
+
+  skills = [
+    { id: 'code', name: 'Code generation and editing', tags: ['code', 'edit', 'write'] },
+    { id: 'bash', name: 'Execute shell commands', tags: ['bash', 'shell', 'terminal'] },
+    { id: 'read', name: 'Read files', tags: ['read', 'file'] },
+  ];
+
+  buildArgs(_task: AgentTask, _config: PlumbConfig): string[] {
+    return ['run', '--format', 'json'];
+  }
+
+  formatInput(task: AgentTask): string {
+    // OpenCode reads one JSON line per stdin message with `prompt` (see fangai OpenCodeAdapter).
+    return JSON.stringify({ prompt: task.message }) + '\n';
+  }
+
+  parseLine(line: string): AdapterEvent[] {
+    if (!line.trim()) return [];
+
+    let event: OpenCodeEvent;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      // Non-JSON line — treat as raw text
+      return [{ type: 'text-delta', text: line + '\n' }];
+    }
+
+    // Text content — OpenCode JSON uses part.text for assistant output
+    if (event.type === 'text' || event.type === 'content' || event.type === 'text-delta') {
+      const fromPart = typeof event.part?.text === 'string' ? event.part.text : '';
+      const text = fromPart || (event.text ?? event.content ?? event.delta ?? '');
+      if (text) return [{ type: 'text-delta', text }];
+      return [];
+    }
+
+    // Message part updated — streaming content
+    if (event.type === 'message.part.updated') {
+      const text = event.content ?? event.text ?? '';
+      if (text) return [{ type: 'text-delta', text }];
+      return [];
+    }
+
+    // End of agent step — primary completion signal for `opencode run --format json`
+    if (event.type === 'step_finish' && event.part?.reason === 'stop') {
+      return [{ type: 'status', state: 'completed' }];
+    }
+
+    // Session / run completed (alternate event names)
+    if (event.type === 'session.completed' || event.type === 'done' || event.type === 'complete') {
+      return [{ type: 'status', state: 'completed' }];
+    }
+
+    // Error events
+    if (event.type === 'error') {
+      return [{ type: 'error', message: event.error ?? event.message ?? 'Unknown error' }];
+    }
+
+    return [];
+  }
+
+  async detect(): Promise<DetectionResult | null> {
+    try {
+      const { stdout } = await execFileAsync('which', ['opencode'], { timeout: 5000 });
+      let version = 'unknown';
+      try {
+        const { stdout: vOut } = await execFileAsync('opencode', ['--version'], { timeout: 5000 });
+        version = vOut.trim().split('\n')[0] ?? 'unknown';
+      } catch {
+        // Version check failed
+      }
+      return {
+        binary: 'opencode',
+        version,
+        path: stdout.trim(),
+        tier: 2,
+        protocol: 'json-stream',
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/adapters/pi.ts

@@ -0,0 +1,138 @@
+// PLUMB — Pi Adapter
+// Wraps `pi --mode rpc --print`. JSONL protocol. Highest value adapter.
+// Extension UI requests are filtered. Text deltas and responses are captured.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { AgentAdapter, AgentTask, AdapterEvent, DetectionResult, PlumbConfig } from '../types.ts';
+
+const execFileAsync = promisify(execFile);
+
+interface PiRpcEvent {
+  type: string;
+  text?: string;
+  content?: string;
+  success?: boolean;
+  error?: string;
+  delta?: string;
+  assistantMessageEvent?: { type?: string; delta?: string };
+  [key: string]: unknown;
+}
+
+export class PiAdapter implements AgentAdapter {
+  readonly id = 'pi';
+  readonly binary = 'pi';
+  readonly tier = 1 as const;
+  readonly displayName = 'Pi';
+  readonly mode = 'persistent' as const;
+
+  skills = [
+    { id: 'code', name: 'Code generation and editing', tags: ['code', 'edit', 'write'] },
+    { id: 'bash', name: 'Execute shell commands', tags: ['bash', 'shell', 'terminal'] },
+    { id: 'read', name: 'Read files', tags: ['read', 'file'] },
+  ];
+
+  buildArgs(_task: AgentTask, _config: PlumbConfig): string[] {
+    return ['--mode', 'rpc', '--print', '--no-session'];
+  }
+
+  formatInput(task: AgentTask): string {
+    // Pi RPC mode expects JSONL input. Send prompt command.
+    const cmd = {
+      type: 'prompt',
+      message: task.message,
+    };
+    return JSON.stringify(cmd) + '\n';
+  }
+
+  parseLine(line: string): AdapterEvent[] {
+    if (!line.trim()) return [];
+
+    let event: PiRpcEvent;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      // Non-JSON line — treat as raw text
+      return [{ type: 'text-delta', text: line + '\n' }];
+    }
+
+    // Filter extension UI requests — these are status updates, not task output
+    if (event.type === 'extension_ui_request') {
+      return [];
+    }
+
+    // Text delta events — streaming output
+    if (event.type === 'text-delta' || event.type === 'delta') {
+      const text = event.text ?? event.delta ?? event.content ?? '';
+      if (text) return [{ type: 'text-delta', text }];
+      return [];
+    }
+
+    // Pi message_update — streaming text from assistant
+    // Format: { type: 'message_update', assistantMessageEvent: { type: 'text_delta', delta: 'text' } }
+    if (event.type === 'message_update') {
+      const ame = event.assistantMessageEvent as { type?: string; delta?: string } | undefined;
+      if (ame?.type === 'text_delta' && typeof ame.delta === 'string') {
+        return [{ type: 'text-delta', text: ame.delta }];
+      }
+      const text = event.text ?? event.delta ?? event.content ?? '';
+      if (text) return [{ type: 'text-delta', text }];
+      return [];
+    }
+
+    // Content block — full text
+    if (event.type === 'content' || event.type === 'text') {
+      const text = event.text ?? event.content ?? '';
+      if (text) return [{ type: 'text-delta', text }];
+      return [];
+    }
+
+    // Response event — task result
+    if (event.type === 'response') {
+      if (event.success === false && event.error) {
+        return [{ type: 'error', message: event.error }];
+      }
+      // Successful response with content
+      const text = event.text ?? event.content ?? '';
+      if (text) return [{ type: 'text-delta', text }];
+      return [];
+    }
+
+    // Error event
+    if (event.type === 'error') {
+      return [{ type: 'error', message: event.error ?? 'Unknown error' }];
+    }
+
+    // Done/complete signals (Pi uses agent_end and turn_end)
+    if (event.type === 'done' || event.type === 'complete' || event.type === 'finished' ||
+        event.type === 'agent_end' || event.type === 'turn_end') {
+      return [{ type: 'status', state: 'completed' }];
+    }
+
+    // Unknown event type — log but don't emit
+    return [];
+  }
+
+  async detect(): Promise<DetectionResult | null> {
+    try {
+      const { stdout } = await execFileAsync('which', ['pi'], { timeout: 5000 });
+      // Get version
+      let version = 'unknown';
+      try {
+        const { stdout: vOut } = await execFileAsync('pi', ['--version'], { timeout: 5000 });
+        version = vOut.trim().split('\n')[0] ?? 'unknown';
+      } catch {
+        // Version check failed, continue with unknown
+      }
+      return {
+        binary: 'pi',
+        version,
+        path: stdout.trim(),
+        tier: 1,
+        protocol: 'jsonl-rpc',
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/adapters/registry.ts

@@ -0,0 +1,35 @@
+// PLUMB — Adapter Registry
+// detectAdapter: returns the first adapter whose binary matches the CLI command.
+// EchoAdapter for 'cat'. GenericAdapter for everything else.
+// Add real adapters here as they are built (Pi, Claude, Cursor...).
+
+import { EchoAdapter } from './echo.ts';
+import { PiAdapter } from './pi.ts';
+import { ClaudeAdapter } from './claude.ts';
+import { OpenCodeAdapter } from './opencode.ts';
+import { GenericAdapter } from './generic.ts';
+import type { AgentAdapter } from '../types.ts';
+
+// Priority order: first match wins. GenericAdapter always last.
+const KNOWN_ADAPTERS: AgentAdapter[] = [
+  new EchoAdapter(),
+  new PiAdapter(),
+  new ClaudeAdapter(),
+  new OpenCodeAdapter(),
+];
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function detectAdapter(cli: string): AgentAdapter {
+  for (const adapter of KNOWN_ADAPTERS) {
+    if (!adapter.binary) continue;
+    // Match binary name at word boundaries — /usr/bin/cat matches 'cat', some-cat-wrapper does not.
+    const re = new RegExp('(?:^|[/\\s])' + escapeRegex(adapter.binary) + '(?:$|[/\\s])');
+    if (re.test(cli)) return adapter;
+    // Also match exact
+    if (cli.trim() === adapter.binary) return adapter;
+  }
+  return new GenericAdapter(cli);
+}

package/src/cli.ts

@@ -0,0 +1,85 @@
+// PLUMB — CLI
+// plumb wrap <cli> --port <n>
+// That's the interface. Nothing else.
+
+import { Command } from 'commander';
+import express from 'express';
+import { createPlumbServer } from './core/server.ts';
+import { detectAdapter } from './adapters/registry.ts';
+
+function log(level: string, msg: string, data?: Record<string, unknown>): void {
+  process.stderr.write(JSON.stringify({
+    ts: new Date().toISOString(),
+    l: level,
+    m: msg,
+    ...(data ?? {}),
+  }) + '\n');
+}
+
+const program = new Command()
+  .name('plumb')
+  .description('Quiet pipes for noisy agents. A2A bridge for any CLI coding agent.')
+  .version('0.1.0');
+
+program
+  .command('wrap <cli>')
+  .description('Wrap a CLI agent as an A2A server')
+  .option('-p, --port <number>', 'Port to listen on', '3001')
+  .option('--name <name>', 'Agent name override')
+  .option('--workdir <dir>', 'Working directory for the CLI agent')
+  .option('--timeout <seconds>', 'Task timeout in seconds', '300')
+  .option('--key <apiKey>', 'Bearer token for /a2a endpoints')
+  .action((cli: string, opts: {
+    port: string;
+    name?: string;
+    workdir?: string;
+    timeout: string;
+    key?: string;
+  }) => {
+    const port = parseInt(opts.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      log('error', 'invalid_port', { port: opts.port });
+      process.exit(1);
+    }
+
+    const adapter = detectAdapter(cli);
+    log('info', 'adapter_detected', { cli, adapter: adapter.id, mode: adapter.mode, tier: adapter.tier });
+
+    const { executor, setupApp } = createPlumbServer({
+      adapter,
+      cli,
+      port,
+      name: opts.name,
+      workdir: opts.workdir,
+      taskTimeout: parseInt(opts.timeout, 10),
+      apiKey: opts.key,
+    });
+
+    const app = express();
+    setupApp(app);
+
+    const server = app.listen(port, () => {
+      log('info', 'plumb_listening', {
+        port,
+        adapter: adapter.id,
+        mode: adapter.mode,
+        endpoints: {
+          agentCard: `http://localhost:${port}/.well-known/agent-card.json`,
+          jsonrpc: `http://localhost:${port}/a2a/jsonrpc`,
+          rest: `http://localhost:${port}/a2a/rest`,
+          health: `http://localhost:${port}/health`,
+        },
+      });
+    });
+
+    const shutdown = async () => {
+      log('info', 'plumb_shutdown', {});
+      await executor.shutdown();
+      server.close(() => process.exit(0));
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+
+export { program };