@geminilight/mindos 0.6.28 → 0.6.29

package/app/lib/a2a/task-handler.ts

@@ -200,18 +200,18 @@ export function handleGetTask(params: GetTaskParams): A2ATask | null {
   return tasks.get(params.id) ?? null;
 }
 
-export function handleCancelTask(params: CancelTaskParams): A2ATask | null {
+export function handleCancelTask(params: CancelTaskParams): { task: A2ATask | null; reason: 'not_found' | 'not_cancelable' | 'ok' } {
   const task = tasks.get(params.id);
-  if (!task) return null;
+  if (!task) return { task: null, reason: 'not_found' };
 
   const terminalStates: TaskState[] = ['TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED', 'TASK_STATE_REJECTED'];
-  if (terminalStates.includes(task.status.state)) return null; // not cancelable
+  if (terminalStates.includes(task.status.state)) return { task: null, reason: 'not_cancelable' };
 
   task.status = {
     state: 'TASK_STATE_CANCELED',
     timestamp: new Date().toISOString(),
   };
-  return task;
+  return { task, reason: 'ok' };
 }
 
 /* ── Helpers ───────────────────────────────────────────────────────────── */

package/app/lib/a2a/types.ts

@@ -210,3 +210,18 @@ export interface SkillMatch {
   skillName: string;
   confidence: number;
 }
+
+/* ── Delegation History (Phase 3 UI) ─────────────────────────────────── */
+
+/** A recorded delegation attempt for the history log */
+export interface DelegationRecord {
+  id: string;
+  agentId: string;
+  agentName: string;
+  message: string;
+  status: 'pending' | 'completed' | 'failed';
+  startedAt: string;
+  completedAt: string | null;
+  result: string | null;
+  error: string | null;
+}

package/app/lib/acp/acp-tools.ts

@@ -0,0 +1,93 @@
+/**
+ * ACP Agent Tools — Expose ACP capabilities as tools
+ * for the MindOS built-in agent to discover and invoke ACP agents.
+ */
+
+import { Type, type Static } from '@sinclair/typebox';
+import type { AgentTool } from '@mariozechner/pi-agent-core';
+import { getAcpAgents, findAcpAgent } from './registry';
+import { createSessionFromEntry, prompt, closeSession } from './session';
+
+function textResult(text: string) {
+  return { content: [{ type: 'text' as const, text }], details: {} };
+}
+
+/* ── Parameter Schemas ─────────────────────────────────────────────────── */
+
+const ListAcpAgentsParams = Type.Object({
+  tag: Type.Optional(Type.String({ description: 'Optional tag to filter agents by (e.g. "coding", "search")' })),
+});
+
+const CallAcpAgentParams = Type.Object({
+  agent_id: Type.String({ description: 'ID of the ACP agent from the registry (from list_acp_agents)' }),
+  message: Type.String({ description: 'Natural language message to send to the ACP agent' }),
+});
+
+/* ── Tool Implementations ──────────────────────────────────────────────── */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const acpTools: AgentTool<any>[] = [
+  {
+    name: 'list_acp_agents',
+    label: 'List ACP Agents',
+    description: 'List available ACP (Agent Client Protocol) agents from the public registry. These are local subprocess-based agents like Gemini CLI, Claude, Copilot, etc. Optionally filter by tag.',
+    parameters: ListAcpAgentsParams,
+    execute: async (_id: string, params: Static<typeof ListAcpAgentsParams>) => {
+      try {
+        let agents = await getAcpAgents();
+
+        if (params.tag) {
+          const tag = params.tag.toLowerCase();
+          agents = agents.filter(a =>
+            a.tags?.some(t => t.toLowerCase().includes(tag))
+          );
+        }
+
+        if (agents.length === 0) {
+          return textResult(
+            params.tag
+              ? `No ACP agents found with tag "${params.tag}". Try list_acp_agents without a tag filter.`
+              : 'No ACP agents found in the registry. The registry may be unavailable.'
+          );
+        }
+
+        const lines = agents.map(a => {
+          const tags = a.tags?.join(', ') || 'none';
+          return `- **${a.name}** (id: \`${a.id}\`, transport: ${a.transport})\n  ${a.description}\n  Tags: ${tags}`;
+        });
+
+        return textResult(`Available ACP agents (${agents.length}):\n\n${lines.join('\n\n')}`);
+      } catch (err) {
+        return textResult(`Failed to list ACP agents: ${(err as Error).message}`);
+      }
+    },
+  },
+
+  {
+    name: 'call_acp_agent',
+    label: 'Call ACP Agent',
+    description: 'Spawn an ACP agent, send it a message, and return the result. The agent runs as a local subprocess. Use list_acp_agents first to see available agents.',
+    parameters: CallAcpAgentParams,
+    execute: async (_id: string, params: Static<typeof CallAcpAgentParams>) => {
+      try {
+        const entry = await findAcpAgent(params.agent_id);
+        if (!entry) {
+          return textResult(`ACP agent not found: ${params.agent_id}. Use list_acp_agents to see available agents.`);
+        }
+
+        const session = await createSessionFromEntry(entry);
+
+        try {
+          const response = await prompt(session.id, params.message);
+          return textResult(
+            `**${entry.name}** responded:\n\n${response.text || '(empty response)'}`
+          );
+        } finally {
+          await closeSession(session.id).catch(() => {});
+        }
+      } catch (err) {
+        return textResult(`ACP call failed: ${(err as Error).message}`);
+      }
+    },
+  },
+];

package/app/lib/acp/bridge.ts

@@ -0,0 +1,138 @@
+/**
+ * A2A-ACP Bridge — Translate between A2A protocol and ACP protocol.
+ * Allows A2A agents to delegate to ACP agents transparently,
+ * and ACP session results to be returned as A2A tasks.
+ */
+
+import type { A2AMessage, A2ATask, TaskState } from '@/lib/a2a/types';
+import type { AcpPromptResponse, AcpSessionUpdate } from './types';
+import { createSession, prompt, closeSession } from './session';
+
+/* ── A2A → ACP ─────────────────────────────────────────────────────────── */
+
+/**
+ * Bridge an A2A SendMessage request to an ACP session/prompt.
+ * Creates a session, sends the message, returns the result, then closes.
+ */
+export async function bridgeA2aToAcp(
+  a2aMessage: A2AMessage,
+  acpAgentId: string,
+): Promise<A2ATask> {
+  const taskId = `acp-bridge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  // Extract text from A2A message parts
+  const text = a2aMessage.parts
+    .map(p => p.text ?? '')
+    .filter(Boolean)
+    .join('\n');
+
+  if (!text) {
+    return makeFailedTask(taskId, 'No text content in A2A message');
+  }
+
+  let session;
+  try {
+    session = await createSession(acpAgentId);
+  } catch (err) {
+    return makeFailedTask(taskId, `Failed to create ACP session: ${(err as Error).message}`);
+  }
+
+  try {
+    const response = await prompt(session.id, text);
+    return bridgeAcpResponseToA2a(taskId, response);
+  } catch (err) {
+    return makeFailedTask(taskId, `ACP prompt failed: ${(err as Error).message}`);
+  } finally {
+    await closeSession(session.id).catch(() => {});
+  }
+}
+
+/* ── ACP → A2A ─────────────────────────────────────────────────────────── */
+
+/**
+ * Convert a completed ACP prompt response to an A2A task result.
+ */
+export function bridgeAcpResponseToA2a(
+  taskId: string,
+  response: AcpPromptResponse,
+): A2ATask {
+  return {
+    id: taskId,
+    status: {
+      state: 'TASK_STATE_COMPLETED',
+      message: {
+        role: 'ROLE_AGENT',
+        parts: [{ text: response.text }],
+      },
+      timestamp: new Date().toISOString(),
+    },
+    artifacts: response.text ? [{
+      artifactId: `${taskId}-artifact`,
+      parts: [{ text: response.text }],
+    }] : undefined,
+  };
+}
+
+/**
+ * Convert a stream of ACP session updates to A2A task updates.
+ * Aggregates text updates and maps final state.
+ */
+export function bridgeAcpUpdatesToA2a(
+  taskId: string,
+  updates: AcpSessionUpdate[],
+): A2ATask {
+  let aggregatedText = '';
+  let finalState: TaskState = 'TASK_STATE_WORKING';
+  let errorMessage = '';
+
+  for (const update of updates) {
+    switch (update.type) {
+      case 'text':
+        aggregatedText += update.text ?? '';
+        break;
+      case 'done':
+        finalState = 'TASK_STATE_COMPLETED';
+        break;
+      case 'error':
+        finalState = 'TASK_STATE_FAILED';
+        errorMessage = update.error ?? 'Unknown error';
+        break;
+    }
+  }
+
+  if (finalState === 'TASK_STATE_FAILED') {
+    return makeFailedTask(taskId, errorMessage);
+  }
+
+  return {
+    id: taskId,
+    status: {
+      state: finalState,
+      message: aggregatedText ? {
+        role: 'ROLE_AGENT',
+        parts: [{ text: aggregatedText }],
+      } : undefined,
+      timestamp: new Date().toISOString(),
+    },
+    artifacts: aggregatedText ? [{
+      artifactId: `${taskId}-artifact`,
+      parts: [{ text: aggregatedText }],
+    }] : undefined,
+  };
+}
+
+/* ── Internal ──────────────────────────────────────────────────────────── */
+
+function makeFailedTask(taskId: string, error: string): A2ATask {
+  return {
+    id: taskId,
+    status: {
+      state: 'TASK_STATE_FAILED',
+      message: {
+        role: 'ROLE_AGENT',
+        parts: [{ text: error }],
+      },
+      timestamp: new Date().toISOString(),
+    },
+  };
+}

package/app/lib/acp/index.ts

@@ -0,0 +1,24 @@
+export { fetchAcpRegistry, getAcpAgents, findAcpAgent, clearRegistryCache } from './registry';
+export { spawnAcpAgent, sendMessage, sendAndWait, onMessage, killAgent, killAllAgents, getProcess, getActiveProcesses } from './subprocess';
+export { createSession, createSessionFromEntry, prompt, promptStream, cancelPrompt, closeSession, getSession, getActiveSessions, closeAllSessions } from './session';
+export { bridgeA2aToAcp, bridgeAcpResponseToA2a, bridgeAcpUpdatesToA2a } from './bridge';
+export { acpTools } from './acp-tools';
+export { ACP_ERRORS } from './types';
+export type {
+  AcpCapabilities,
+  AcpSessionState,
+  AcpSession,
+  AcpJsonRpcRequest,
+  AcpJsonRpcResponse,
+  AcpJsonRpcError,
+  AcpPromptRequest,
+  AcpPromptResponse,
+  AcpUpdateType,
+  AcpSessionUpdate,
+  AcpToolCall,
+  AcpToolResult,
+  AcpRegistryEntry,
+  AcpRegistry,
+  AcpTransportType,
+} from './types';
+export type { AcpProcess } from './subprocess';

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();
+}