plumb-bridge 0.1.0

package/src/core/executor.ts

@@ -0,0 +1,307 @@
+// PLUMB — Executor
+// Bridges A2A tasks to CLI processes. Writes every lifecycle event to the ledger.
+// Supports oneshot (process-per-task) and persistent (single long-running process) modes.
+
+import { randomUUID } from 'node:crypto';
+import type { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
+import type { AgentAdapter, AgentTask, PlumbConfig } from '../types.ts';
+import { ProcessManager, PersistentProcess } from './process.ts';
+import { Ledger } from './ledger.ts';
+
+export class PlumbExecutor implements AgentExecutor {
+  private pm = new ProcessManager();
+  private persistent: PersistentProcess | null = null;
+  private adapter: AgentAdapter;
+  private config: PlumbConfig;
+  private ledger: Ledger;
+  private contextByTaskId = new Map<string, string>();
+
+  constructor(adapter: AgentAdapter, config: PlumbConfig, ledger: Ledger) {
+    this.adapter = adapter;
+    this.config = config;
+    this.ledger = ledger;
+  }
+
+  async execute(ctx: RequestContext, bus: ExecutionEventBus): Promise<void> {
+    const { taskId, contextId } = ctx;
+
+    const parts = (ctx.userMessage.parts ?? []) as Array<{ kind?: string; text?: string }>;
+    const text = parts
+      .filter(p => p.kind === 'text' && typeof p.text === 'string')
+      .map(p => p.text!)
+      .join('\n').trim();
+
+    if (!text) {
+      this.fail(bus, taskId, contextId, 'No message text provided.', 'rejected');
+      bus.finished();
+      return;
+    }
+
+    this.ledger.append({
+      type: 'task_submitted',
+      taskId,
+      cli: this.config.cli,
+      message: text,
+      timestamp: new Date().toISOString(),
+    });
+
+    this.contextByTaskId.set(taskId, contextId);
+    const task: AgentTask = { id: taskId, message: text, context: { workdir: this.config.workdir } };
+
+    if (this.adapter.mode === 'persistent') {
+      await this.executePersistent(ctx, bus, task);
+    } else {
+      await this.executeOneshot(ctx, bus, task);
+    }
+  }
+
+  private async executeOneshot(
+    ctx: RequestContext,
+    bus: ExecutionEventBus,
+    task: AgentTask,
+  ): Promise<void> {
+    const { taskId, contextId } = ctx;
+    const { adapter, config, ledger } = this;
+    const timeout = config.taskTimeout ?? 300;
+
+    bus.publish({
+      kind: 'task',
+      id: taskId,
+      contextId,
+      status: { state: 'working', timestamp: new Date().toISOString() },
+      history: [],
+    });
+
+    ledger.append({ type: 'task_running', taskId, timestamp: new Date().toISOString() });
+
+    const [cmd, ...cliArgs] = this.splitCli(config.cli);
+    const extraArgs = adapter.buildArgs(task, config);
+    let accumulated = '';
+    let settled = false;
+
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.pm.kill(taskId);
+        ledger.append({ type: 'task_failed', taskId, error: `timed out after ${timeout}s`, timestamp: new Date().toISOString() });
+        this.fail(bus, taskId, contextId, `Task timed out after ${timeout}s`);
+        bus.finished();
+        resolve();
+      }, timeout * 1000);
+
+      this.pm.spawn(
+        taskId, cmd!, [...cliArgs, ...extraArgs],
+        { cwd: config.workdir, env: config.env },
+        {
+          onLine: (line) => {
+            if (settled) return;
+            const events = adapter.parseLine(line);
+            for (const ev of events) {
+              if (ev.type === 'text-delta' && ev.text) {
+                accumulated += ev.text;
+                ledger.append({ type: 'progress', taskId, text: ev.text, timestamp: new Date().toISOString() });
+                bus.publish({
+                  kind: 'artifact-update', taskId, contextId,
+                  artifact: { artifactId: 'stdout', name: 'output', parts: [{ kind: 'text', text: ev.text }] },
+                  append: true, lastChunk: false,
+                });
+              }
+              if (ev.type === 'status' && ev.state === 'completed') {
+                settled = true;
+                clearTimeout(timer);
+                this.contextByTaskId.delete(taskId);
+                ledger.append({ type: 'task_completed', taskId, timestamp: new Date().toISOString() });
+                bus.publish({ kind: 'message', messageId: randomUUID(), role: 'agent', parts: [{ kind: 'text', text: accumulated || 'Done' }] });
+                bus.finished();
+                resolve();
+              }
+              if (ev.type === 'error') {
+                settled = true;
+                clearTimeout(timer);
+                this.contextByTaskId.delete(taskId);
+                ledger.append({ type: 'task_failed', taskId, error: ev.message, timestamp: new Date().toISOString() });
+                this.fail(bus, taskId, contextId, ev.message);
+                bus.finished();
+                resolve();
+              }
+            }
+          },
+          onError: (text) => {
+            ledger.append({ type: 'log', taskId, level: 'error', text, timestamp: new Date().toISOString() });
+            bus.publish({
+              kind: 'artifact-update', taskId, contextId,
+              artifact: { artifactId: 'stderr', name: 'errors', parts: [{ kind: 'text', text }] },
+            });
+          },
+          onExit: (code) => {
+            clearTimeout(timer);
+            if (settled) { resolve(); return; }
+            settled = true;
+            this.contextByTaskId.delete(taskId);
+            if (code === 0) {
+              ledger.append({ type: 'task_completed', taskId, timestamp: new Date().toISOString() });
+              bus.publish({ kind: 'message', messageId: randomUUID(), role: 'agent', parts: [{ kind: 'text', text: accumulated || '(no output)' }] });
+            } else {
+              const errMsg = `Process exited with code ${code}`;
+              ledger.append({ type: 'task_failed', taskId, error: errMsg, timestamp: new Date().toISOString() });
+              bus.publish({ kind: 'message', messageId: randomUUID(), role: 'agent', parts: [{ kind: 'text', text: errMsg }] });
+            }
+            bus.finished();
+            resolve();
+          },
+        },
+      );
+
+      this.pm.stdin(taskId, adapter.formatInput(task), true);
+    });
+  }
+
+  private async executePersistent(
+    ctx: RequestContext,
+    bus: ExecutionEventBus,
+    task: AgentTask,
+  ): Promise<void> {
+    const { taskId, contextId } = ctx;
+    const { adapter, config, ledger } = this;
+    const timeout = config.taskTimeout ?? 300;
+
+    // Ensure persistent process is running
+    if (!this.persistent) {
+      const [cmd, ...cliArgs] = this.splitCli(config.cli);
+      const extraArgs = adapter.buildArgs(task, config);
+      this.persistent = new PersistentProcess(cmd!, [...cliArgs, ...extraArgs], {
+        cwd: config.workdir,
+        env: config.env,
+      });
+    }
+    await this.persistent.ensure();
+
+    bus.publish({
+      kind: 'task',
+      id: taskId,
+      contextId,
+      status: { state: 'working', timestamp: new Date().toISOString() },
+      history: [],
+    });
+
+    ledger.append({ type: 'task_running', taskId, timestamp: new Date().toISOString() });
+
+    let accumulated = '';
+    let settled = false;
+
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.persistent?.removeLineHandler(taskId);
+        ledger.append({ type: 'task_failed', taskId, error: `timed out after ${timeout}s`, timestamp: new Date().toISOString() });
+        this.fail(bus, taskId, contextId, `Task timed out after ${timeout}s`);
+        bus.finished();
+        resolve();
+      }, timeout * 1000);
+
+      this.persistent!.setLineHandler(taskId, (line) => {
+        if (settled) return;
+        const events = adapter.parseLine(line);
+        for (const ev of events) {
+          if (ev.type === 'text-delta' && ev.text) {
+            accumulated += ev.text;
+            ledger.append({ type: 'progress', taskId, text: ev.text, timestamp: new Date().toISOString() });
+            bus.publish({
+              kind: 'artifact-update', taskId, contextId,
+              artifact: { artifactId: 'stdout', name: 'output', parts: [{ kind: 'text', text: ev.text }] },
+              append: true, lastChunk: false,
+            });
+          }
+          if (ev.type === 'status' && ev.state === 'completed') {
+            settled = true;
+            clearTimeout(timer);
+            this.contextByTaskId.delete(taskId);
+            this.persistent?.removeLineHandler(taskId);
+            ledger.append({ type: 'task_completed', taskId, timestamp: new Date().toISOString() });
+            bus.publish({ kind: 'message', messageId: randomUUID(), role: 'agent', parts: [{ kind: 'text', text: accumulated || 'Done' }] });
+            bus.finished();
+            resolve();
+          }
+          if (ev.type === 'error') {
+            settled = true;
+            clearTimeout(timer);
+            this.contextByTaskId.delete(taskId);
+            this.persistent?.removeLineHandler(taskId);
+            ledger.append({ type: 'task_failed', taskId, error: ev.message, timestamp: new Date().toISOString() });
+            this.fail(bus, taskId, contextId, ev.message);
+            bus.finished();
+            resolve();
+          }
+        }
+      });
+
+      // Send task input to the persistent process
+      this.persistent!.writeWhenActive(taskId, adapter.formatInput(task));
+    });
+  }
+
+  async cancelTask(taskId: string, bus: ExecutionEventBus): Promise<void> {
+    const contextId = this.contextByTaskId.get(taskId) ?? taskId;
+
+    if (this.adapter.mode === 'persistent' && this.persistent) {
+      this.persistent.removeLineHandler(taskId);
+    } else {
+      this.pm.kill(taskId, this.config.killTimeout ?? 5000);
+    }
+
+    this.contextByTaskId.delete(taskId);
+    this.ledger.append({ type: 'task_cancelled', taskId, timestamp: new Date().toISOString() });
+    bus.publish({
+      kind: 'status-update', taskId, contextId, final: true,
+      status: {
+        state: 'canceled',
+        message: { kind: 'message', role: 'agent', messageId: randomUUID(), parts: [{ kind: 'text', text: 'Task cancelled.' }] },
+        timestamp: new Date().toISOString(),
+      },
+    });
+    bus.finished();
+  }
+
+  async shutdown(): Promise<void> {
+    this.contextByTaskId.clear();
+    await this.pm.killAll();
+    if (this.persistent) {
+      await this.persistent.kill();
+      this.persistent = null;
+    }
+  }
+
+  private fail(
+    bus: ExecutionEventBus,
+    taskId: string,
+    contextId: string,
+    text: string,
+    state: 'failed' | 'rejected' = 'failed',
+  ): void {
+    this.contextByTaskId.delete(taskId);
+    bus.publish({
+      kind: 'status-update', taskId, contextId, final: true,
+      status: {
+        state,
+        message: { kind: 'message', role: 'agent', messageId: randomUUID(), parts: [{ kind: 'text', text }] },
+        timestamp: new Date().toISOString(),
+      },
+    });
+  }
+
+  private splitCli(cli: string): string[] {
+    const parts: string[] = [];
+    let cur = '';
+    let inQ: string | null = null;
+    for (const ch of cli) {
+      if (inQ) { if (ch === inQ) inQ = null; else cur += ch; }
+      else if (ch === '"' || ch === "'") inQ = ch;
+      else if (ch === ' ' || ch === '\t') { if (cur) { parts.push(cur); cur = ''; } }
+      else cur += ch;
+    }
+    if (cur) parts.push(cur);
+    return parts;
+  }
+}

package/src/core/ledger.ts

@@ -0,0 +1,39 @@
+// PLUMB — Ledger
+// Append-only JSONL. Every task event is one line. Crash-survivable. Query with jq.
+// Stolen from pi's append-only tree storage, simplified to linear per-day files.
+
+import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { LedgerEvent } from '../types.ts';
+
+const LEDGER_DIR = '.plumb/ledger';
+
+export class Ledger {
+  private path: string;
+
+  constructor() {
+    if (!existsSync(LEDGER_DIR)) {
+      mkdirSync(LEDGER_DIR, { recursive: true });
+    }
+    const date = new Date().toISOString().slice(0, 10);
+    this.path = join(LEDGER_DIR, `${date}.jsonl`);
+  }
+
+  append(event: LedgerEvent): void {
+    try {
+      appendFileSync(this.path, JSON.stringify(event) + '\n');
+    } catch {
+      // Ledger failure is non-fatal. Log to stderr and continue.
+      process.stderr.write(JSON.stringify({
+        ts: new Date().toISOString(),
+        l: 'error',
+        m: 'ledger_write_failed',
+        event_type: event.type,
+      }) + '\n');
+    }
+  }
+
+  getPath(): string {
+    return this.path;
+  }
+}

package/src/core/process.ts

@@ -0,0 +1,297 @@
+// PLUMB — Process Manager
+// Spawns CLI agents, routes stdout/stderr, enforces SIGTERM→SIGKILL cancellation.
+// Stolen from fangai's ProcessManager + attachJsonlReader.
+// LF-only JSONL reader: does NOT use Node readline (which splits on U+2028/U+2029,
+// breaking Pi's JSONL protocol where those codepoints are valid inside strings).
+
+import { spawn, type ChildProcess } from 'node:child_process';
+
+function log(level: string, msg: string, data?: Record<string, unknown>): void {
+  const entry: Record<string, unknown> = {
+    ts: new Date().toISOString(),
+    l: level,
+    m: msg,
+    ...(data ?? {}),
+  };
+  process.stderr.write(JSON.stringify(entry) + '\n');
+}
+
+export function attachJsonlReader(
+  stream: NodeJS.ReadableStream,
+  onLine: (line: string) => void,
+): () => void {
+  let buffer = '';
+
+  const onData = (chunk: Buffer | string) => {
+    buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    while (true) {
+      const idx = buffer.indexOf('\n');
+      if (idx === -1) break;
+      let line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      if (line.endsWith('\r')) line = line.slice(0, -1);
+      if (line.length > 0) onLine(line);
+    }
+  };
+
+  const onEnd = () => {
+    if (buffer.length > 0) {
+      const remaining = buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer;
+      if (remaining.length > 0) onLine(remaining);
+      buffer = '';
+    }
+  };
+
+  stream.on('data', onData);
+  stream.on('end', onEnd);
+  return () => {
+    stream.removeListener('data', onData);
+    stream.removeListener('end', onEnd);
+  };
+}
+
+export class ProcessManager {
+  private processes = new Map<string, ChildProcess>();
+  private killTimers = new Map<string, NodeJS.Timeout>();
+  private cleanups = new Map<string, () => void>();
+
+  spawn(
+    taskId: string,
+    cmd: string,
+    args: string[],
+    opts: { cwd?: string; env?: Record<string, string> },
+    handlers: {
+      onLine: (line: string) => void;
+      onError: (text: string) => void;
+      onExit: (code: number | null, signal: string | null) => void;
+    },
+  ): ChildProcess {
+    const proc = spawn(cmd, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: opts.cwd,
+      env: { ...(process.env as Record<string, string>), ...opts.env },
+    });
+    this.processes.set(taskId, proc);
+    log('info', 'process_spawned', { taskId, cmd, pid: proc.pid });
+
+    const detach = attachJsonlReader(proc.stdout!, handlers.onLine);
+    this.cleanups.set(taskId, detach);
+
+    let stderrBuf = '';
+    proc.stderr!.on('data', (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+      const lines = stderrBuf.split('\n');
+      stderrBuf = lines.pop()!;
+      for (const line of lines) {
+        if (line.trim()) handlers.onError(line);
+      }
+    });
+
+    proc.on('exit', (code, signal) => {
+      log('info', 'process_exited', { taskId, code, signal });
+      detach();
+      this.processes.delete(taskId);
+      this.cleanups.delete(taskId);
+      const timer = this.killTimers.get(taskId);
+      if (timer) { clearTimeout(timer); this.killTimers.delete(taskId); }
+      handlers.onExit(code, signal);
+    });
+
+    proc.on('error', (err) => {
+      log('error', 'process_error', { taskId, error: err.message });
+      detach();
+      this.processes.delete(taskId);
+      this.cleanups.delete(taskId);
+      handlers.onError(err.message);
+      handlers.onExit(1, null);
+    });
+
+    return proc;
+  }
+
+  stdin(taskId: string, data: string, close = false): void {
+    const proc = this.processes.get(taskId);
+    if (!proc) return;
+    proc.stdin!.write(data);
+    if (close) proc.stdin!.end();
+  }
+
+  kill(taskId: string, timeout = 5000): void {
+    const proc = this.processes.get(taskId);
+    if (!proc) return;
+    log('warn', 'process_kill', { taskId, timeout });
+    proc.kill('SIGTERM');
+    const timer = setTimeout(() => {
+      try { proc.kill('SIGKILL'); } catch { /* gone */ }
+    }, timeout);
+    this.killTimers.set(taskId, timer);
+  }
+
+  async killAll(timeout = 5000): Promise<void> {
+    const ids = [...this.processes.keys()];
+    if (ids.length === 0) return;
+    await Promise.all(ids.map(id => new Promise<void>(resolve => {
+      const proc = this.processes.get(id);
+      if (!proc) { resolve(); return; }
+      const timer = setTimeout(() => {
+        try { proc.kill('SIGKILL'); } catch { /* gone */ }
+        resolve();
+      }, timeout);
+      proc.on('exit', () => { clearTimeout(timer); resolve(); });
+      proc.kill('SIGTERM');
+    })));
+  }
+
+  has(taskId: string): boolean { return this.processes.has(taskId); }
+}
+
+// ─── Persistent Process Manager ───────────────────────────────────────────
+// Single long-running process for adapters with mode: 'persistent'.
+// Tasks are queued. Lines route to active task. Task completes on protocol signal.
+
+export class PersistentProcess {
+  private proc: ChildProcess | null = null;
+  private detachReader: (() => void) | null = null;
+  private readonly cmd: string;
+  private readonly args: string[];
+  private readonly opts: { cwd?: string; env?: Record<string, string> };
+
+  private taskHandlers = new Map<string, (line: string) => void>();
+  private taskQueue: string[] = [];
+  private activeTaskId: string | null = null;
+  private writeBuffer = new Map<string, string[]>();
+
+  readonly onCrash?: (crashedTaskId: string, remainingCount: number) => void;
+
+  constructor(
+    cmd: string,
+    args: string[],
+    opts: { cwd?: string; env?: Record<string, string> },
+    callbacks?: { onCrash?: (crashedTaskId: string, remainingCount: number) => void },
+  ) {
+    this.cmd = cmd;
+    this.args = args;
+    this.opts = opts;
+    this.onCrash = callbacks?.onCrash;
+  }
+
+  async ensure(): Promise<void> {
+    if (this.proc && this.proc.exitCode === null) return;
+
+    this.proc = spawn(this.cmd, this.args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: this.opts.cwd,
+      env: { ...(process.env as Record<string, string>), ...this.opts.env },
+    });
+
+    log('info', 'persistent_spawned', { cmd: this.cmd, pid: this.proc.pid });
+
+    this.detachReader = attachJsonlReader(this.proc.stdout!, (line) => {
+      this.routeLine(line);
+    });
+
+    this.proc.stderr!.on('data', () => {
+      // stderr from persistent process — ignored
+    });
+
+    this.proc.on('exit', () => {
+      log('warn', 'persistent_exited', { activeTaskId: this.activeTaskId, queuedCount: this.taskQueue.length });
+      if (this.detachReader) { this.detachReader(); this.detachReader = null; }
+
+      if (this.activeTaskId && this.taskHandlers.size > 0) {
+        const crashedId = this.activeTaskId;
+        const remaining = this.taskHandlers.size;
+        const errorLine = JSON.stringify({ type: 'error', message: 'Process crashed unexpectedly' });
+        for (const [, handler] of this.taskHandlers) {
+          try { handler(errorLine); } catch { /* swallow */ }
+        }
+        this.onCrash?.(crashedId, remaining);
+      }
+      this.proc = null;
+      this.activeTaskId = null;
+      this.writeBuffer.clear();
+    });
+
+    await new Promise<void>((resolve) => {
+      this.proc!.once('spawn', () => resolve());
+      this.proc!.once('error', () => { this.proc = null; resolve(); });
+    });
+  }
+
+  private routeLine(line: string): void {
+    if (!this.activeTaskId) return;
+    const handler = this.taskHandlers.get(this.activeTaskId);
+    handler?.(line);
+  }
+
+  setLineHandler(taskId: string, handler: (line: string) => void): void {
+    this.taskHandlers.set(taskId, handler);
+    if (!this.activeTaskId && this.taskQueue.length === 0) {
+      this.activeTaskId = taskId;
+      this.taskQueue.push(taskId);
+      this.flushBuffer(taskId);
+    } else {
+      this.taskQueue.push(taskId);
+    }
+  }
+
+  removeLineHandler(taskId: string): void {
+    this.taskHandlers.delete(taskId);
+    this.writeBuffer.delete(taskId);
+    this.taskQueue = this.taskQueue.filter(id => id !== taskId);
+    if (this.activeTaskId === taskId) {
+      this.activeTaskId = null;
+      this.advanceQueue();
+    }
+  }
+
+  private advanceQueue(): void {
+    if (this.activeTaskId) return;
+    while (this.taskQueue.length > 0) {
+      const next = this.taskQueue[0];
+      if (this.taskHandlers.has(next)) {
+        this.activeTaskId = next;
+        this.flushBuffer(next);
+        return;
+      }
+      this.taskQueue.shift();
+    }
+  }
+
+  private flushBuffer(taskId: string): void {
+    const chunks = this.writeBuffer.get(taskId);
+    if (!chunks || chunks.length === 0) return;
+    for (const chunk of chunks) this.write(chunk);
+    this.writeBuffer.delete(taskId);
+  }
+
+  writeWhenActive(taskId: string, data: string): void {
+    if (!this.proc) return;
+    if (this.activeTaskId === taskId) {
+      this.write(data);
+      return;
+    }
+    let chunks = this.writeBuffer.get(taskId);
+    if (!chunks) { chunks = []; this.writeBuffer.set(taskId, chunks); }
+    chunks.push(data);
+  }
+
+  write(data: string): void {
+    if (!this.proc) return;
+    this.proc.stdin!.write(data);
+  }
+
+  async kill(): Promise<void> {
+    if (this.proc) {
+      log('info', 'persistent_kill', {});
+      if (this.detachReader) { this.detachReader(); this.detachReader = null; }
+      this.proc.kill('SIGTERM');
+      this.proc = null;
+      this.activeTaskId = null;
+      this.writeBuffer.clear();
+    }
+  }
+
+  get isAlive(): boolean { return this.proc !== null && this.proc.exitCode === null; }
+  getActiveTaskId(): string | null { return this.activeTaskId; }
+}