plumb-bridge 0.1.2 → 0.1.3

package/src/core/server.ts

@@ -1,10 +1,11 @@
 // PLUMB — Server
 // Express + @a2a-js/sdk. Agent Card. JSON-RPC. REST. Health.
-// Stolen from fangai's createFangServer, adapted: Plumb naming, ledger injection, no Cursor.
+// Derived from prior bridge layout: Plumb naming, ledger injection, no vendor IDE coupling.
 
+import { timingSafeEqual } from 'node:crypto';
 import type { Request, Response, NextFunction } from 'express';
 import express from 'express';
-import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
+import { DefaultRequestHandler } from '@a2a-js/sdk/server';
 import {
   agentCardHandler,
   jsonRpcHandler,
@@ -14,6 +15,20 @@ import {
 import type { AgentAdapter, PlumbConfig } from '../types.ts';
 import { Ledger } from './ledger.ts';
 import { PlumbExecutor } from './executor.ts';
+import { PlumbTaskStore } from './task-store.ts';
+
+let _pkgVersion: string | undefined;
+function getPackageVersion(): string {
+  if (_pkgVersion !== undefined) return _pkgVersion;
+  try {
+    const { readFileSync } = require('node:fs');
+    const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));
+    _pkgVersion = pkg.version ?? '0.0.0';
+  } catch {
+    _pkgVersion = '0.0.0';
+  }
+  return _pkgVersion!;
+}
 
 export function createPlumbServer(config: PlumbConfig & { adapter: AgentAdapter }) {
   const { adapter, port } = config;
@@ -24,7 +39,7 @@ export function createPlumbServer(config: PlumbConfig & { adapter: AgentAdapter
     name,
     description: `${adapter.displayName} via plumb — A2A bridge`,
     protocolVersion: '0.3.0',
-    version: '0.1.0',
+    version: getPackageVersion(),
     url: process.env.PLUMB_PUBLIC_URL ?? `http://localhost:${port}`,
     capabilities: { streaming: true },
     skills: adapter.skills.map(s => ({ ...s, description: s.name })),
@@ -39,13 +54,21 @@ export function createPlumbServer(config: PlumbConfig & { adapter: AgentAdapter
   };
 
   const executor = new PlumbExecutor(adapter, config, ledger);
-  const taskStore = new InMemoryTaskStore();
+  const taskStore = new PlumbTaskStore({ maxTasks: 100, completedRetentionMinutes: 60 });
   const requestHandler = new DefaultRequestHandler(agentCard, taskStore, executor);
 
+  // Periodic cleanup: evict terminal tasks past retention window every 5 min
+  const cleanupInterval = setInterval(() => {
+    taskStore.cleanupStaleCompleted();
+  }, 5 * 60 * 1000);
+  // Don't hold the process open
+  if (cleanupInterval.unref) cleanupInterval.unref();
+
   return {
     executor,
     agentCard,
     ledger,
+    taskStore,
     setupApp: (app: express.Express) => {
       app.use(express.json({ limit: '10mb' }));
 
@@ -55,20 +78,28 @@ export function createPlumbServer(config: PlumbConfig & { adapter: AgentAdapter
         res.redirect('/.well-known/agent-card.json');
       });
       app.get('/health', (_req: Request, res: Response) => {
-        res.json({
+        const health: Record<string, unknown> = {
           status: 'ok',
           agent: name,
           adapter: adapter.id,
           mode: adapter.mode,
           tier: adapter.tier,
           ledger: ledger.getPath(),
-        });
+        };
+        const alive = executor.isPersistentAlive();
+        if (alive !== null) {
+          health.agentAlive = alive;
+        }
+        res.json(health);
       });
 
       // Auth gate — protects A2A endpoints if apiKey is configured
       if (config.apiKey) {
+        const expected = Buffer.from(`Bearer ${config.apiKey}`);
         app.use((req: Request, res: Response, next: NextFunction) => {
-          if (req.headers.authorization !== `Bearer ${config.apiKey}`) {
+          const header = req.headers.authorization ?? '';
+          const given = Buffer.from(header);
+          if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
             return res.status(401).json({ error: { message: 'Unauthorized' } });
           }
           next();

package/src/core/session-store.ts

@@ -0,0 +1,158 @@
+// PLUMB — Cursor Session Store
+// In-memory session tracking for multi-turn Cursor conversations.
+// Ported from fangai cursor-adapter.ts. Tracks session_ids from
+// cursor-agent's --continue/--resume lifecycle.
+//
+// When sessionTtlMs is set, stale server sessions are abandoned (no --continue)
+// and a cold recap of the last N turns is injected into the next prompt so cold
+// starts maintain continuity without relying on Cursor holding the session.
+
+export interface SessionTurn {
+  user: string;
+  assistant: string;
+}
+
+export interface CursorSession {
+  id: string;
+  createdAt: Date;
+  lastUsedAt: Date;
+  workspace: string;
+  model: string;
+  turnCount: number;
+  /** Last N completed turns for recap after --continue is unsafe. */
+  turns: SessionTurn[];
+}
+
+export interface CursorSessionStoreOptions {
+  /** Max age since lastUsedAt before dropping session and injecting recap. null = no TTL. */
+  sessionTtlMs?: number | null;
+  /** Max completed turns to retain per session and include in recap. Default 8. */
+  recapMaxTurns?: number;
+  /** Max chars per turn leg stored/echoed in recap. Default 8000. */
+  recapMaxCharsPerLeg?: number;
+}
+
+export class CursorSessionStore {
+  private sessions = new Map<string, CursorSession>();
+  private lastSessionId: string | null = null;
+  private readonly sessionTtlMs: number | null;
+  private readonly recapMaxTurns: number;
+  private readonly recapMaxCharsPerLeg: number;
+  /** Queued cold recap for the next formatInput after TTL expiry. */
+  private coldRecapPending: string | null = null;
+
+  constructor(opts: CursorSessionStoreOptions = {}) {
+    this.sessionTtlMs = opts.sessionTtlMs === undefined ? null : opts.sessionTtlMs;
+    this.recapMaxTurns = opts.recapMaxTurns ?? 8;
+    this.recapMaxCharsPerLeg = opts.recapMaxCharsPerLeg ?? 8000;
+  }
+
+  /** Register a new session from cursor-agent output. */
+  register(sessionId: string, workspace: string, model: string): void {
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      existing.lastUsedAt = new Date();
+      existing.turnCount++;
+    } else {
+      this.sessions.set(sessionId, {
+        id: sessionId,
+        createdAt: new Date(),
+        lastUsedAt: new Date(),
+        workspace,
+        model,
+        turnCount: 1,
+        turns: [],
+      });
+    }
+    this.lastSessionId = sessionId;
+  }
+
+  /**
+   * If the current lastSession is older than sessionTtlMs, remove it,
+   * queue a cold recap for the next prompt, and clear lastSession so
+   * the next spawn is fresh (no --continue).
+   */
+  expireLastSessionIfStale(nowMs: number = Date.now()): void {
+    if (this.sessionTtlMs === null || this.lastSessionId === null) return;
+    const s = this.sessions.get(this.lastSessionId);
+    if (!s) {
+      this.lastSessionId = null;
+      return;
+    }
+    if (nowMs - s.lastUsedAt.getTime() <= this.sessionTtlMs) return;
+
+    const recap = this.buildRecapBlock(s.turns);
+    if (recap) this.coldRecapPending = recap;
+
+    this.sessions.delete(this.lastSessionId);
+    this.lastSessionId = null;
+  }
+
+  /** Pop the cold recap block (from TTL expiry) once, for the next user message. */
+  consumeColdRecap(): string | null {
+    const r = this.coldRecapPending;
+    this.coldRecapPending = null;
+    return r;
+  }
+
+  /** Append a completed turn after a successful result event. */
+  recordCompletedTurn(sessionId: string | null, user: string, assistant: string): void {
+    if (!sessionId) return;
+    const s = this.sessions.get(sessionId);
+    if (!s) return;
+    s.turns.push({
+      user: this.truncateLeg(user),
+      assistant: this.truncateLeg(assistant.trim()),
+    });
+    while (s.turns.length > this.recapMaxTurns) s.turns.shift();
+  }
+
+  /** Get the last active session ID for --continue. */
+  get lastSession(): string | null {
+    return this.lastSessionId;
+  }
+
+  /** Get a specific session by ID. */
+  get(sessionId: string): CursorSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /** List all sessions (most recent first). */
+  list(): CursorSession[] {
+    return Array.from(this.sessions.values()).sort(
+      (a, b) => b.lastUsedAt.getTime() - a.lastUsedAt.getTime(),
+    );
+  }
+
+  /** Clear all sessions. */
+  clear(): void {
+    this.sessions.clear();
+    this.lastSessionId = null;
+    this.coldRecapPending = null;
+  }
+
+  private truncateLeg(text: string): string {
+    const t = text.trim();
+    if (t.length <= this.recapMaxCharsPerLeg) return t;
+    return `${t.slice(0, this.recapMaxCharsPerLeg)}\n...[truncated]`;
+  }
+
+  private buildRecapBlock(turns: SessionTurn[]): string | null {
+    if (!turns.length) return null;
+    const lines: string[] = [
+      '[Plumb: Prior Cursor session expired. Continuity recap — answer the new message after the separator.]',
+      '',
+      '### Earlier turns (recap)',
+    ];
+    const slice = turns.slice(-this.recapMaxTurns);
+    for (let i = 0; i < slice.length; i++) {
+      const t = slice[i]!;
+      lines.push(`${i + 1}. **User:** ${t.user}`);
+      lines.push(`   **Assistant:** ${t.assistant}`);
+      lines.push('');
+    }
+    lines.push('---');
+    lines.push('');
+    return lines.join('\n');
+  }
+}

package/src/core/task-store.ts

@@ -0,0 +1,137 @@
+// PLUMB — Task Store
+// LRU-bounded + TTL-cleanup task store. Replaces SDK InMemoryTaskStore.
+// Prevents unbounded memory growth: evicts terminal tasks after retention
+// window, enforces max task cap. Based on FangTaskStore (fangai, tested).
+
+import type { Task } from '@a2a-js/sdk';
+import type { TaskStore, ServerCallContext } from '@a2a-js/sdk/server';
+
+const TERMINAL_STATES = new Set<string>([
+  'completed',
+  'failed',
+  'canceled',
+  'rejected',
+]);
+
+interface StoredEntry {
+  task: Task;
+  /** Timestamp when this task entered a terminal state (ms). null = active. */
+  terminalSinceMs: number | null;
+}
+
+function shallowClone(task: Task): Task {
+  const t: Task = { ...task };
+  if (t.history !== undefined) {
+    t.history = [...t.history];
+  }
+  if (t.artifacts !== undefined) {
+    t.artifacts = t.artifacts.map(a => ({ ...a }));
+  }
+  return t;
+}
+
+export interface PlumbTaskStoreOptions {
+  /** Maximum tasks retained (LRU eviction). Default 100. */
+  maxTasks?: number;
+  /** Drop terminal tasks older than this many minutes. Default 60. */
+  completedRetentionMinutes?: number;
+}
+
+export class PlumbTaskStore implements TaskStore {
+  private readonly maxTasks: number;
+  private readonly retentionMs: number;
+  /** Map iteration order = LRU. Touch = delete + re-set. */
+  private readonly entries = new Map<string, StoredEntry>();
+
+  constructor(options?: PlumbTaskStoreOptions) {
+    const mt = options?.maxTasks ?? 100;
+    this.maxTasks = mt < 1 ? 1 : mt;
+    const mins = options?.completedRetentionMinutes ?? 60;
+    this.retentionMs = Math.max(1, mins) * 60 * 1000;
+  }
+
+  async save(task: Task, _context?: ServerCallContext): Promise<void> {
+    const cloned = shallowClone(task);
+    const now = Date.now();
+    const terminal = TERMINAL_STATES.has(cloned.status.state);
+
+    let terminalSinceMs: number | null = null;
+    if (terminal) {
+      const prev = this.entries.get(cloned.id);
+      if (prev && prev.terminalSinceMs !== null && TERMINAL_STATES.has(prev.task.status.state)) {
+        terminalSinceMs = prev.terminalSinceMs;
+      } else {
+        terminalSinceMs = now;
+      }
+    }
+
+    // Touch: delete then re-set to maintain LRU order
+    if (this.entries.has(cloned.id)) {
+      this.entries.delete(cloned.id);
+    }
+    this.entries.set(cloned.id, { task: cloned, terminalSinceMs });
+
+    this.evictIfNeeded();
+    return Promise.resolve();
+  }
+
+  async load(taskId: string, _context?: ServerCallContext): Promise<Task | undefined> {
+    const entry = this.entries.get(taskId);
+    if (!entry) return Promise.resolve(undefined);
+
+    // Touch for LRU
+    this.entries.delete(taskId);
+    const touched: StoredEntry = {
+      task: entry.task,
+      terminalSinceMs: entry.terminalSinceMs,
+    };
+    this.entries.set(taskId, touched);
+
+    return Promise.resolve(shallowClone(entry.task));
+  }
+
+  /** Remove a single task by ID. */
+  delete(taskId: string, _context?: ServerCallContext): Promise<void> {
+    this.entries.delete(taskId);
+    return Promise.resolve();
+  }
+
+  /** Drop terminal tasks past retention window. */
+  cleanupStaleCompleted(): void {
+    const now = Date.now();
+    for (const [id, entry] of this.entries) {
+      if (
+        TERMINAL_STATES.has(entry.task.status.state) &&
+        entry.terminalSinceMs !== null &&
+        now - entry.terminalSinceMs > this.retentionMs
+      ) {
+        this.entries.delete(id);
+      }
+    }
+  }
+
+  /** Number of tasks currently stored. */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  private evictIfNeeded(): void {
+    while (this.entries.size > this.maxTasks) {
+      let victim: string | undefined;
+      // Evict terminal tasks first
+      for (const id of this.entries.keys()) {
+        const entry = this.entries.get(id);
+        if (entry && TERMINAL_STATES.has(entry.task.status.state)) {
+          victim = id;
+          break;
+        }
+      }
+      // If no terminal tasks, evict oldest
+      if (victim === undefined) {
+        victim = this.entries.keys().next().value as string | undefined;
+      }
+      if (victim === undefined) break;
+      this.entries.delete(victim);
+    }
+  }
+}

package/src/types.ts

@@ -6,6 +6,7 @@ export interface AgentTask {
   message: string;
   context?: {
     workdir?: string;
+    labels?: string[];
     metadata?: Record<string, unknown>;
   };
 }
@@ -23,7 +24,6 @@ export interface PlumbConfig {
   name?: string;
   workdir?: string;
   env?: Record<string, string>;
-  maxConcurrent?: number;
   taskTimeout?: number;
   killTimeout?: number;
   apiKey?: string;
@@ -59,3 +59,32 @@ export type LedgerEvent =
   | { type: 'task_completed'; taskId: string; timestamp: string }
   | { type: 'task_failed'; taskId: string; error: string; timestamp: string }
   | { type: 'task_cancelled'; taskId: string; timestamp: string };
+
+// ─── Persistent RPC Types ────────────────────────────────────────────────────
+// Correlated request/response over stdin/stdout for persistent agents (e.g. Pi).
+
+/** Content shape for host_tool_result (subset of AgentToolResult). */
+export type RpcHostToolResultContent = ReadonlyArray<Record<string, unknown>>;
+
+/** Parsed RPC response from stdout { type: "response" }. */
+export interface RpcParsedResponse {
+  command?: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+/**
+ * Executes a host_tool_call from the persistent agent.
+ * Must return fragments suitable for { result: { content } }.
+ * abortSignal cooperatively cancels when agent emits host_tool_cancel.
+ */
+export type RpcHostToolExecutor = (
+  ctx: {
+    requestId: string;
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    abortSignal: AbortSignal;
+  },
+) => Promise<{ content: RpcHostToolResultContent; isError?: boolean }>;