@geminilight/mindos 0.6.27 → 0.6.29

package/app/lib/acp/registry.ts

@@ -0,0 +1,135 @@
+/**
+ * ACP Registry Client — Fetch and cache the ACP agent registry.
+ * The registry lists available ACP agents (Gemini CLI, Claude, Copilot, etc.)
+ * with their transport type, command, and metadata.
+ */
+
+import type { AcpRegistry, AcpRegistryEntry } from './types';
+
+/* ── Constants ─────────────────────────────────────────────────────────── */
+
+const REGISTRY_URL = 'https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const FETCH_TIMEOUT_MS = 10_000;
+
+/* ── Cache ─────────────────────────────────────────────────────────────── */
+
+let cachedRegistry: AcpRegistry | null = null;
+
+/* ── Public API ────────────────────────────────────────────────────────── */
+
+/**
+ * Fetch the ACP registry from the CDN. Caches for 1 hour.
+ * Returns null if the fetch fails.
+ */
+export async function fetchAcpRegistry(): Promise<AcpRegistry | null> {
+  // Return cached if still valid
+  if (cachedRegistry && Date.now() - new Date(cachedRegistry.fetchedAt).getTime() < CACHE_TTL_MS) {
+    return cachedRegistry;
+  }
+
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      headers: { 'Accept': 'application/json' },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+
+    if (!res.ok) return cachedRegistry ?? null;
+
+    const data = await res.json();
+
+    // The registry JSON may have varying shapes; normalize it
+    const agents: AcpRegistryEntry[] = parseRegistryEntries(data);
+
+    cachedRegistry = {
+      version: data.version ?? '1',
+      agents,
+      fetchedAt: new Date().toISOString(),
+    };
+
+    return cachedRegistry;
+  } catch {
+    // Return stale cache if available, otherwise null
+    return cachedRegistry ?? null;
+  }
+}
+
+/**
+ * Get all available ACP agents from the registry.
+ */
+export async function getAcpAgents(): Promise<AcpRegistryEntry[]> {
+  const registry = await fetchAcpRegistry();
+  return registry?.agents ?? [];
+}
+
+/**
+ * Find a specific ACP agent by ID.
+ */
+export async function findAcpAgent(id: string): Promise<AcpRegistryEntry | null> {
+  const agents = await getAcpAgents();
+  return agents.find(a => a.id === id) ?? null;
+}
+
+/**
+ * Clear the registry cache (useful for testing).
+ */
+export function clearRegistryCache(): void {
+  cachedRegistry = null;
+}
+
+/* ── Internal ──────────────────────────────────────────────────────────── */
+
+/**
+ * Parse raw registry JSON into typed entries.
+ * Handles both array and object-keyed formats.
+ */
+function parseRegistryEntries(data: unknown): AcpRegistryEntry[] {
+  if (!data || typeof data !== 'object') return [];
+
+  // If data has an `agents` array, use that
+  const obj = data as Record<string, unknown>;
+  let rawAgents: unknown[];
+
+  if (Array.isArray(obj.agents)) {
+    rawAgents = obj.agents;
+  } else if (Array.isArray(data)) {
+    rawAgents = data;
+  } else {
+    // Object-keyed format: { "agent-id": { ... }, ... }
+    rawAgents = Object.entries(obj)
+      .filter(([key]) => key !== 'version' && key !== '$schema')
+      .map(([key, val]) => ({ ...(val as object), id: key }));
+  }
+
+  return rawAgents
+    .map(normalizeEntry)
+    .filter((e): e is AcpRegistryEntry => e !== null);
+}
+
+function normalizeEntry(raw: unknown): AcpRegistryEntry | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const entry = raw as Record<string, unknown>;
+
+  const id = String(entry.id ?? entry.name ?? '');
+  const name = String(entry.name ?? entry.id ?? '');
+  if (!id && !name) return null;
+
+  return {
+    id: id || name,
+    name: name || id,
+    description: String(entry.description ?? ''),
+    version: entry.version ? String(entry.version) : undefined,
+    transport: normalizeTransport(entry.transport),
+    command: String(entry.command ?? entry.cmd ?? ''),
+    args: Array.isArray(entry.args) ? entry.args.map(String) : undefined,
+    env: entry.env && typeof entry.env === 'object' ? entry.env as Record<string, string> : undefined,
+    tags: Array.isArray(entry.tags) ? entry.tags.map(String) : undefined,
+    homepage: entry.homepage ? String(entry.homepage) : undefined,
+  };
+}
+
+function normalizeTransport(raw: unknown): AcpRegistryEntry['transport'] {
+  const t = String(raw ?? 'stdio').toLowerCase();
+  if (t === 'npx' || t === 'uvx' || t === 'binary') return t;
+  return 'stdio';
+}

package/app/lib/acp/session.ts

@@ -0,0 +1,264 @@
+/**
+ * ACP Session Manager — High-level session lifecycle for ACP agents.
+ * Manages session creation, prompt turns, cancellation, and cleanup.
+ */
+
+import type {
+  AcpSession,
+  AcpSessionState,
+  AcpSessionUpdate,
+  AcpPromptResponse,
+  AcpRegistryEntry,
+} from './types';
+import {
+  spawnAcpAgent,
+  sendAndWait,
+  sendMessage,
+  onMessage,
+  killAgent,
+  type AcpProcess,
+} from './subprocess';
+import { findAcpAgent } from './registry';
+
+/* ── State ─────────────────────────────────────────────────────────────── */
+
+const sessions = new Map<string, AcpSession>();
+const sessionProcesses = new Map<string, AcpProcess>();
+
+/* ── Public API ────────────────────────────────────────────────────────── */
+
+/**
+ * Create a new ACP session by spawning an agent process.
+ */
+export async function createSession(
+  agentId: string,
+  options?: { env?: Record<string, string> },
+): Promise<AcpSession> {
+  const entry = await findAcpAgent(agentId);
+  if (!entry) {
+    throw new Error(`ACP agent not found in registry: ${agentId}`);
+  }
+
+  return createSessionFromEntry(entry, options);
+}
+
+/**
+ * Create a session from a known registry entry (skips registry lookup).
+ */
+export async function createSessionFromEntry(
+  entry: AcpRegistryEntry,
+  options?: { env?: Record<string, string> },
+): Promise<AcpSession> {
+  const proc = spawnAcpAgent(entry, options);
+
+  // Send session/new and wait for ack
+  try {
+    const response = await sendAndWait(proc, 'session/new', {}, 15_000);
+
+    if (response.error) {
+      killAgent(proc);
+      throw new Error(`session/new failed: ${response.error.message}`);
+    }
+  } catch (err) {
+    killAgent(proc);
+    throw err;
+  }
+
+  const sessionId = `ses-${entry.id}-${Date.now()}`;
+  const session: AcpSession = {
+    id: sessionId,
+    agentId: entry.id,
+    state: 'idle',
+    createdAt: new Date().toISOString(),
+    lastActivityAt: new Date().toISOString(),
+  };
+
+  sessions.set(sessionId, session);
+  sessionProcesses.set(sessionId, proc);
+  return session;
+}
+
+/**
+ * Send a prompt to an active session and collect the full response.
+ * For streaming, use promptStream() instead.
+ */
+export async function prompt(
+  sessionId: string,
+  text: string,
+): Promise<AcpPromptResponse> {
+  const { session, proc } = getSessionAndProc(sessionId);
+
+  if (session.state === 'active') {
+    throw new Error(`Session ${sessionId} is busy processing another prompt`);
+  }
+
+  updateSessionState(session, 'active');
+
+  try {
+    const response = await sendAndWait(proc, 'session/prompt', { text }, 60_000);
+
+    if (response.error) {
+      updateSessionState(session, 'error');
+      throw new Error(`session/prompt error: ${response.error.message}`);
+    }
+
+    updateSessionState(session, 'idle');
+    const result = response.result as Record<string, unknown>;
+    return {
+      sessionId,
+      text: String(result?.text ?? ''),
+      done: true,
+      toolCalls: result?.toolCalls as AcpPromptResponse['toolCalls'],
+      metadata: result?.metadata as AcpPromptResponse['metadata'],
+    };
+  } catch (err) {
+    updateSessionState(session, 'error');
+    throw err;
+  }
+}
+
+/**
+ * Send a prompt and receive streaming updates via callback.
+ * Returns the final aggregated response.
+ */
+export async function promptStream(
+  sessionId: string,
+  text: string,
+  onUpdate: (update: AcpSessionUpdate) => void,
+): Promise<AcpPromptResponse> {
+  const { session, proc } = getSessionAndProc(sessionId);
+
+  if (session.state === 'active') {
+    throw new Error(`Session ${sessionId} is busy processing another prompt`);
+  }
+
+  updateSessionState(session, 'active');
+
+  return new Promise((resolve, reject) => {
+    let aggregatedText = '';
+
+    const unsub = onMessage(proc, (msg) => {
+      // Handle streaming notifications (no id field, or notification pattern)
+      if (msg.result && typeof msg.result === 'object') {
+        const update = msg.result as Record<string, unknown>;
+        const sessionUpdate: AcpSessionUpdate = {
+          sessionId,
+          type: (update.type as AcpSessionUpdate['type']) ?? 'text',
+          text: update.text as string | undefined,
+          toolCall: update.toolCall as AcpSessionUpdate['toolCall'],
+          toolResult: update.toolResult as AcpSessionUpdate['toolResult'],
+          error: update.error as string | undefined,
+        };
+
+        onUpdate(sessionUpdate);
+
+        if (sessionUpdate.type === 'text' && sessionUpdate.text) {
+          aggregatedText += sessionUpdate.text;
+        }
+
+        if (sessionUpdate.type === 'done') {
+          unsub();
+          updateSessionState(session, 'idle');
+          resolve({
+            sessionId,
+            text: aggregatedText,
+            done: true,
+          });
+        }
+
+        if (sessionUpdate.type === 'error') {
+          unsub();
+          updateSessionState(session, 'error');
+          reject(new Error(sessionUpdate.error ?? 'Unknown ACP error'));
+        }
+      }
+    });
+
+    // Send the prompt
+    try {
+      sendMessage(proc, 'session/prompt', { text, stream: true });
+    } catch (err) {
+      unsub();
+      updateSessionState(session, 'error');
+      reject(err);
+    }
+  });
+}
+
+/**
+ * Cancel the current prompt turn on a session.
+ */
+export async function cancelPrompt(sessionId: string): Promise<void> {
+  const { session, proc } = getSessionAndProc(sessionId);
+
+  if (session.state !== 'active') return;
+
+  try {
+    await sendAndWait(proc, 'session/cancel', {}, 5_000);
+  } catch {
+    // Best-effort cancel — don't throw if the agent doesn't support it
+  }
+
+  updateSessionState(session, 'idle');
+}
+
+/**
+ * Close a session and terminate the subprocess.
+ */
+export async function closeSession(sessionId: string): Promise<void> {
+  const proc = sessionProcesses.get(sessionId);
+
+  if (proc?.alive) {
+    try {
+      await sendAndWait(proc, 'session/close', {}, 5_000);
+    } catch {
+      // Best-effort close
+    }
+    killAgent(proc);
+  }
+
+  sessions.delete(sessionId);
+  sessionProcesses.delete(sessionId);
+}
+
+/**
+ * Get a session by its ID.
+ */
+export function getSession(sessionId: string): AcpSession | undefined {
+  return sessions.get(sessionId);
+}
+
+/**
+ * Get all active sessions.
+ */
+export function getActiveSessions(): AcpSession[] {
+  return [...sessions.values()];
+}
+
+/**
+ * Close all active sessions. Used for cleanup.
+ */
+export async function closeAllSessions(): Promise<void> {
+  const ids = [...sessions.keys()];
+  await Promise.allSettled(ids.map(id => closeSession(id)));
+}
+
+/* ── Internal ──────────────────────────────────────────────────────────── */
+
+function getSessionAndProc(sessionId: string): { session: AcpSession; proc: AcpProcess } {
+  const session = sessions.get(sessionId);
+  if (!session) throw new Error(`Session not found: ${sessionId}`);
+
+  const proc = sessionProcesses.get(sessionId);
+  if (!proc?.alive) {
+    updateSessionState(session, 'error');
+    throw new Error(`Session process is dead: ${sessionId}`);
+  }
+
+  return { session, proc };
+}
+
+function updateSessionState(session: AcpSession, state: AcpSessionState): void {
+  session.state = state;
+  session.lastActivityAt = new Date().toISOString();
+}

package/app/lib/acp/subprocess.ts

@@ -0,0 +1,209 @@
+/**
+ * ACP Subprocess Manager — Spawn and communicate with ACP agent processes.
+ * ACP agents communicate via JSON-RPC 2.0 over stdio (stdin/stdout).
+ */
+
+import { spawn, type ChildProcess } from 'child_process';
+import type {
+  AcpJsonRpcRequest,
+  AcpJsonRpcResponse,
+  AcpRegistryEntry,
+  AcpTransportType,
+} from './types';
+
+/* ── Types ─────────────────────────────────────────────────────────────── */
+
+export interface AcpProcess {
+  id: string;
+  agentId: string;
+  proc: ChildProcess;
+  alive: boolean;
+}
+
+type MessageCallback = (msg: AcpJsonRpcResponse) => void;
+
+/* ── State ─────────────────────────────────────────────────────────────── */
+
+const processes = new Map<string, AcpProcess>();
+const messageListeners = new Map<string, Set<MessageCallback>>();
+let rpcIdCounter = 1;
+
+/* ── Public API ────────────────────────────────────────────────────────── */
+
+/**
+ * Spawn an ACP agent subprocess.
+ */
+export function spawnAcpAgent(
+  entry: AcpRegistryEntry,
+  options?: { env?: Record<string, string> },
+): AcpProcess {
+  const { cmd, args } = buildCommand(entry);
+
+  const mergedEnv = {
+    ...process.env,
+    ...(entry.env ?? {}),
+    ...(options?.env ?? {}),
+  };
+
+  const proc = spawn(cmd, args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: mergedEnv,
+    shell: false,
+  });
+
+  const id = `acp-${entry.id}-${Date.now()}`;
+  const acpProc: AcpProcess = { id, agentId: entry.id, proc, alive: true };
+
+  processes.set(id, acpProc);
+  messageListeners.set(id, new Set());
+
+  // Parse newline-delimited JSON from stdout
+  let buffer = '';
+  proc.stdout?.on('data', (chunk: Buffer) => {
+    buffer += chunk.toString();
+    const lines = buffer.split('\n');
+    buffer = lines.pop() ?? '';
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const msg = JSON.parse(trimmed) as AcpJsonRpcResponse;
+        const listeners = messageListeners.get(id);
+        if (listeners) {
+          for (const cb of listeners) cb(msg);
+        }
+      } catch {
+        // Not valid JSON — skip (could be agent debug output)
+      }
+    }
+  });
+
+  proc.on('close', () => {
+    acpProc.alive = false;
+    messageListeners.delete(id);
+  });
+
+  proc.on('error', () => {
+    acpProc.alive = false;
+  });
+
+  return acpProc;
+}
+
+/**
+ * Send a JSON-RPC message to an ACP agent's stdin.
+ */
+export function sendMessage(acpProc: AcpProcess, method: string, params?: Record<string, unknown>): string {
+  if (!acpProc.alive || !acpProc.proc.stdin?.writable) {
+    throw new Error(`ACP process ${acpProc.id} is not alive`);
+  }
+
+  const id = `rpc-${rpcIdCounter++}`;
+  const request: AcpJsonRpcRequest = {
+    jsonrpc: '2.0',
+    id,
+    method,
+    ...(params ? { params } : {}),
+  };
+
+  acpProc.proc.stdin.write(JSON.stringify(request) + '\n');
+  return id;
+}
+
+/**
+ * Register a callback for messages from an ACP agent.
+ * Returns an unsubscribe function.
+ */
+export function onMessage(acpProc: AcpProcess, callback: MessageCallback): () => void {
+  const listeners = messageListeners.get(acpProc.id);
+  if (!listeners) throw new Error(`ACP process ${acpProc.id} not found`);
+
+  listeners.add(callback);
+  return () => { listeners.delete(callback); };
+}
+
+/**
+ * Send a JSON-RPC request and wait for a response with the matching ID.
+ */
+export function sendAndWait(
+  acpProc: AcpProcess,
+  method: string,
+  params?: Record<string, unknown>,
+  timeoutMs = 30_000,
+): Promise<AcpJsonRpcResponse> {
+  return new Promise((resolve, reject) => {
+    const rpcId = sendMessage(acpProc, method, params);
+
+    const timer = setTimeout(() => {
+      unsub();
+      reject(new Error(`ACP RPC timeout after ${timeoutMs}ms for method: ${method}`));
+    }, timeoutMs);
+
+    const unsub = onMessage(acpProc, (msg) => {
+      if (String(msg.id) === rpcId) {
+        clearTimeout(timer);
+        unsub();
+        resolve(msg);
+      }
+    });
+  });
+}
+
+/**
+ * Kill an ACP agent process.
+ */
+export function killAgent(acpProc: AcpProcess): void {
+  if (acpProc.alive && acpProc.proc.pid) {
+    acpProc.proc.kill('SIGTERM');
+    // Force kill after 5s if still alive
+    setTimeout(() => {
+      if (acpProc.alive) {
+        acpProc.proc.kill('SIGKILL');
+      }
+    }, 5000);
+  }
+  acpProc.alive = false;
+  processes.delete(acpProc.id);
+  messageListeners.delete(acpProc.id);
+}
+
+/**
+ * Get a process by its ID.
+ */
+export function getProcess(id: string): AcpProcess | undefined {
+  return processes.get(id);
+}
+
+/**
+ * Get all active processes.
+ */
+export function getActiveProcesses(): AcpProcess[] {
+  return [...processes.values()].filter(p => p.alive);
+}
+
+/**
+ * Kill all active ACP processes. Used for cleanup.
+ */
+export function killAllAgents(): void {
+  for (const proc of processes.values()) {
+    killAgent(proc);
+  }
+}
+
+/* ── Internal ──────────────────────────────────────────────────────────── */
+
+function buildCommand(entry: AcpRegistryEntry): { cmd: string; args: string[] } {
+  const transport: AcpTransportType = entry.transport;
+
+  switch (transport) {
+    case 'npx':
+      return { cmd: 'npx', args: [entry.command, ...(entry.args ?? [])] };
+    case 'uvx':
+      return { cmd: 'uvx', args: [entry.command, ...(entry.args ?? [])] };
+    case 'binary':
+    case 'stdio':
+    default:
+      return { cmd: entry.command, args: entry.args ?? [] };
+  }
+}