plumb-bridge 0.1.0

package/src/core/server.ts

@@ -0,0 +1,83 @@
+// PLUMB — Server
+// Express + @a2a-js/sdk. Agent Card. JSON-RPC. REST. Health.
+// Stolen from fangai's createFangServer, adapted: Plumb naming, ledger injection, no Cursor.
+
+import type { Request, Response, NextFunction } from 'express';
+import express from 'express';
+import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
+import {
+  agentCardHandler,
+  jsonRpcHandler,
+  restHandler,
+  UserBuilder,
+} from '@a2a-js/sdk/server/express';
+import type { AgentAdapter, PlumbConfig } from '../types.ts';
+import { Ledger } from './ledger.ts';
+import { PlumbExecutor } from './executor.ts';
+
+export function createPlumbServer(config: PlumbConfig & { adapter: AgentAdapter }) {
+  const { adapter, port } = config;
+  const name = config.name ?? `${adapter.displayName}-plumb`;
+  const ledger = new Ledger();
+
+  const agentCard = {
+    name,
+    description: `${adapter.displayName} via plumb — A2A bridge`,
+    protocolVersion: '0.3.0',
+    version: '0.1.0',
+    url: process.env.PLUMB_PUBLIC_URL ?? `http://localhost:${port}`,
+    capabilities: { streaming: true },
+    skills: adapter.skills.map(s => ({ ...s, description: s.name })),
+    defaultInputModes: ['text/plain'],
+    defaultOutputModes: ['text/plain'],
+    metadata: {
+      bridge: 'plumb',
+      tier: adapter.tier,
+      mode: adapter.mode,
+      ledger: ledger.getPath(),
+    },
+  };
+
+  const executor = new PlumbExecutor(adapter, config, ledger);
+  const taskStore = new InMemoryTaskStore();
+  const requestHandler = new DefaultRequestHandler(agentCard, taskStore, executor);
+
+  return {
+    executor,
+    agentCard,
+    ledger,
+    setupApp: (app: express.Express) => {
+      app.use(express.json({ limit: '10mb' }));
+
+      // Public — Agent Card and health MUST be unauthenticated (A2A spec)
+      app.use('/.well-known/agent-card.json', agentCardHandler({ agentCardProvider: requestHandler }));
+      app.get('/.well-known/agent.json', (_req: Request, res: Response) => {
+        res.redirect('/.well-known/agent-card.json');
+      });
+      app.get('/health', (_req: Request, res: Response) => {
+        res.json({
+          status: 'ok',
+          agent: name,
+          adapter: adapter.id,
+          mode: adapter.mode,
+          tier: adapter.tier,
+          ledger: ledger.getPath(),
+        });
+      });
+
+      // Auth gate — protects A2A endpoints if apiKey is configured
+      if (config.apiKey) {
+        app.use((req: Request, res: Response, next: NextFunction) => {
+          if (req.headers.authorization !== `Bearer ${config.apiKey}`) {
+            return res.status(401).json({ error: { message: 'Unauthorized' } });
+          }
+          next();
+        });
+      }
+
+      // A2A endpoints
+      app.use('/a2a/jsonrpc', jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+      app.use('/a2a/rest', restHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+    },
+  };
+}

package/src/main.ts

@@ -0,0 +1,3 @@
+// PLUMB — Entry Point
+import { program } from './cli.ts';
+program.parse(process.argv);

package/src/types.ts

@@ -0,0 +1,61 @@
+// PLUMB — Core Types
+// The bridge contract. stdin/stdout to A2A. Nothing else.
+
+export interface AgentTask {
+  id: string;
+  message: string;
+  context?: {
+    workdir?: string;
+    metadata?: Record<string, unknown>;
+  };
+}
+
+export type AdapterEvent =
+  | { type: 'text-delta'; text: string }
+  | { type: 'tool-call'; tool: string; input?: Record<string, unknown> }
+  | { type: 'tool-result'; tool: string; output: string; isError?: boolean }
+  | { type: 'status'; state: 'working' | 'completed' | 'failed' }
+  | { type: 'error'; message: string; code?: string };
+
+export interface PlumbConfig {
+  cli: string;
+  port: number;
+  name?: string;
+  workdir?: string;
+  env?: Record<string, string>;
+  maxConcurrent?: number;
+  taskTimeout?: number;
+  killTimeout?: number;
+  apiKey?: string;
+}
+
+export interface DetectionResult {
+  binary: string;
+  version: string;
+  path: string;
+  tier: 1 | 2 | 3;
+  protocol: string;
+}
+
+export interface AgentAdapter {
+  readonly id: string;
+  readonly binary: string;
+  readonly tier: 1 | 2 | 3;
+  readonly displayName: string;
+  readonly mode: 'oneshot' | 'persistent';
+  skills: Array<{ id: string; name: string; tags: string[] }>;
+
+  buildArgs(task: AgentTask, config: PlumbConfig): string[];
+  formatInput(task: AgentTask): string;
+  parseLine(line: string): AdapterEvent[];
+  detect(): Promise<DetectionResult | null>;
+}
+
+export type LedgerEvent =
+  | { type: 'task_submitted'; taskId: string; cli: string; message: string; timestamp: string }
+  | { type: 'task_running'; taskId: string; timestamp: string }
+  | { type: 'progress'; taskId: string; text: string; timestamp: string }
+  | { type: 'log'; taskId: string; level: string; text: string; timestamp: string }
+  | { type: 'task_completed'; taskId: string; timestamp: string }
+  | { type: 'task_failed'; taskId: string; error: string; timestamp: string }
+  | { type: 'task_cancelled'; taskId: string; timestamp: string };

package/test/conformance.test.ts

@@ -0,0 +1,142 @@
+// PLUMB — Conformance Test Suite
+// Phase 0 gates as automated tests. Run with `bun test`.
+
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync, rmSync, readFileSync } from 'node:fs';
+
+const PORT = 9100;
+const BASE_URL = `http://localhost:${PORT}`;
+let server: ChildProcess;
+
+function waitForServer(url: string, timeout = 10000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = async () => {
+      try {
+        const res = await fetch(url);
+        if (res.ok) return resolve();
+      } catch {}
+      if (Date.now() - start > timeout) return reject(new Error('Server timeout'));
+      setTimeout(check, 100);
+    };
+    check();
+  });
+}
+
+describe('Phase 0 Conformance', () => {
+  beforeAll(async () => {
+    // Clean ledger
+    const ledgerPath = '.plumb/ledger';
+    if (existsSync(ledgerPath)) {
+      rmSync(ledgerPath, { recursive: true });
+    }
+
+    // Start server
+    server = spawn('bun', ['run', 'src/main.ts', 'wrap', 'cat', '--port', String(PORT)], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    await waitForServer(`${BASE_URL}/health`);
+  }, 20_000);
+
+  afterAll(() => {
+    if (server) {
+      server.kill('SIGTERM');
+    }
+  });
+
+  it('Gate 2: Server starts and responds to health check', async () => {
+    const res = await fetch(`${BASE_URL}/health`);
+    expect(res.ok).toBe(true);
+    const data = (await res.json()) as { status: string; adapter: string };
+    expect(data.status).toBe('ok');
+    expect(data.adapter).toBe('echo');
+  });
+
+  it('Gate 3: Agent Card is valid', async () => {
+    const res = await fetch(`${BASE_URL}/.well-known/agent-card.json`);
+    expect(res.ok).toBe(true);
+    const card = (await res.json()) as {
+      name: string;
+      url: string;
+      capabilities: { streaming: boolean };
+    };
+    expect(card.name).toBeDefined();
+    expect(card.url).toBe(BASE_URL);
+    expect(card.capabilities).toBeDefined();
+    expect(card.capabilities.streaming).toBe(true);
+  });
+
+  it('Gate 4: Task accepted via JSON-RPC', async () => {
+    const res = await fetch(`${BASE_URL}/a2a/jsonrpc`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'message/send',
+        params: {
+          message: {
+            messageId: 'test-msg-001',
+            role: 'user',
+            parts: [{ kind: 'text', text: 'hello plumb' }],
+          },
+        },
+        id: 'test-1',
+      }),
+    });
+
+    expect(res.ok).toBe(true);
+    const data = (await res.json()) as {
+      error?: unknown;
+      result?: { kind: string };
+    };
+    expect(data.error).toBeUndefined();
+    expect(data.result).toBeDefined();
+    expect(data.result!.kind).toBe('message');
+  });
+
+  it('Gate 5: Echo adapter returns input text', async () => {
+    const testMessage = 'conformance test input';
+    const res = await fetch(`${BASE_URL}/a2a/jsonrpc`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'message/send',
+        params: {
+          message: {
+            messageId: 'test-msg-002',
+            role: 'user',
+            parts: [{ kind: 'text', text: testMessage }],
+          },
+        },
+        id: 'test-2',
+      }),
+    });
+
+    const data = (await res.json()) as {
+      result?: { parts?: Array<{ text?: string }> };
+    };
+    const resultText = data.result?.parts?.[0]?.text ?? '';
+    expect(resultText.trim()).toBe(testMessage);
+  });
+
+  it('Gate 6: Ledger contains lifecycle events', async () => {
+    // Give ledger time to flush
+    await new Promise(r => setTimeout(r, 500));
+
+    const today = new Date().toISOString().slice(0, 10);
+    const ledgerPath = `.plumb/ledger/${today}.jsonl`;
+
+    expect(existsSync(ledgerPath)).toBe(true);
+
+    const content = readFileSync(ledgerPath, 'utf-8');
+    const lines = content.trim().split('\n').map(l => JSON.parse(l));
+    const types = lines.map(e => e.type);
+
+    expect(types).toContain('task_submitted');
+    expect(types).toContain('task_running');
+    expect(types).toContain('task_completed');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "playgorund"]
+}