@geminilight/mindos 0.6.25 → 0.7.0

package/app/lib/a2a/client.ts

@@ -0,0 +1,207 @@
+/**
+ * A2A Client — Discover external agents and delegate tasks via A2A protocol.
+ * Phase 2: MindOS as an A2A Client (orchestrator).
+ */
+
+import type {
+  AgentCard,
+  RemoteAgent,
+  A2ATask,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  SendMessageParams,
+} from './types';
+
+/* ── Constants ─────────────────────────────────────────────────────────── */
+
+const DISCOVERY_TIMEOUT_MS = 5_000;
+const RPC_TIMEOUT_MS = 30_000;
+const CARD_CACHE_TTL_MS = 5 * 60 * 1000; // 5 min
+
+/* ── Agent Registry (in-memory cache) ──────────────────────────────────── */
+
+const registry = new Map<string, RemoteAgent>();
+
+/** Derive a stable ID from a URL (includes protocol to avoid collisions) */
+function urlToId(url: string): string {
+  try {
+    const u = new URL(url);
+    const proto = u.protocol.replace(':', '');
+    const port = u.port || (u.protocol === 'https:' ? '443' : '80');
+    return `${proto}-${u.hostname}-${port}`;
+  } catch {
+    return url.replace(/[^a-zA-Z0-9]/g, '-');
+  }
+}
+
+/* ── HTTP helpers ──────────────────────────────────────────────────────── */
+
+async function fetchWithTimeout(url: string, opts: RequestInit & { timeoutMs?: number } = {}): Promise<Response> {
+  const { timeoutMs = DISCOVERY_TIMEOUT_MS, ...fetchOpts } = opts;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...fetchOpts, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function jsonRpcCall(endpoint: string, method: string, params: unknown, token?: string): Promise<JsonRpcResponse> {
+  const body: JsonRpcRequest = {
+    jsonrpc: '2.0',
+    id: `mindos-${Date.now()}`,
+    method,
+    params: params as Record<string, unknown>,
+  };
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'A2A-Version': '1.0',
+  };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+
+  const res = await fetchWithTimeout(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    timeoutMs: RPC_TIMEOUT_MS,
+  });
+
+  if (!res.ok) {
+    throw new Error(`A2A RPC failed: ${res.status} ${res.statusText}`);
+  }
+
+  return res.json();
+}
+
+/* ── Discovery ─────────────────────────────────────────────────────────── */
+
+/**
+ * Discover an A2A agent at the given base URL.
+ * Fetches /.well-known/agent-card.json and caches the result.
+ */
+export async function discoverAgent(baseUrl: string): Promise<RemoteAgent | null> {
+  const cleanUrl = baseUrl.replace(/\/+$/, '');
+  const cardUrl = `${cleanUrl}/.well-known/agent-card.json`;
+  const id = urlToId(cleanUrl);
+
+  // Check cache
+  const cached = registry.get(id);
+  if (cached && Date.now() - new Date(cached.discoveredAt).getTime() < CARD_CACHE_TTL_MS) {
+    return cached;
+  }
+
+  try {
+    const res = await fetchWithTimeout(cardUrl);
+    if (!res.ok) return null;
+
+    const card: AgentCard = await res.json();
+    // Validate minimum required fields
+    if (!card || typeof card.name !== 'string' || !card.name ||
+        !Array.isArray(card.supportedInterfaces) || card.supportedInterfaces.length === 0) {
+      return null;
+    }
+
+    // Find JSON-RPC endpoint
+    const jsonRpcInterface = card.supportedInterfaces.find(i => i.protocolBinding === 'JSONRPC');
+    if (!jsonRpcInterface) return null;
+
+    const agent: RemoteAgent = {
+      id,
+      card,
+      endpoint: jsonRpcInterface.url,
+      discoveredAt: new Date().toISOString(),
+      reachable: true,
+    };
+
+    registry.set(id, agent);
+    return agent;
+  } catch {
+    // Mark as unreachable if previously cached
+    if (cached) {
+      cached.reachable = false;
+      return cached;
+    }
+    return null;
+  }
+}
+
+/**
+ * Discover agents from a list of URLs (concurrent, best-effort).
+ */
+export async function discoverAgents(urls: string[]): Promise<RemoteAgent[]> {
+  const results = await Promise.allSettled(urls.map(discoverAgent));
+  return results
+    .filter((r): r is PromiseFulfilledResult<RemoteAgent | null> => r.status === 'fulfilled')
+    .map(r => r.value)
+    .filter((a): a is RemoteAgent => a !== null);
+}
+
+/* ── Task Delegation ───────────────────────────────────────────────────── */
+
+/**
+ * Send a message to a remote agent via A2A JSON-RPC.
+ * Returns the resulting task.
+ */
+export async function delegateTask(
+  agentId: string,
+  message: string,
+  token?: string,
+): Promise<A2ATask> {
+  const agent = registry.get(agentId);
+  if (!agent) throw new Error(`Agent not found: ${agentId}`);
+  if (!agent.reachable) throw new Error(`Agent not reachable: ${agent.card.name}`);
+
+  const params: SendMessageParams = {
+    message: {
+      role: 'ROLE_USER',
+      parts: [{ text: message }],
+    },
+    configuration: { blocking: true },
+  };
+
+  const response = await jsonRpcCall(agent.endpoint, 'SendMessage', params, token);
+
+  if (response.error) {
+    throw new Error(`A2A error [${response.error.code}]: ${response.error.message}`);
+  }
+
+  return response.result as A2ATask;
+}
+
+/**
+ * Check the status of a task on a remote agent.
+ */
+export async function checkRemoteTaskStatus(
+  agentId: string,
+  taskId: string,
+  token?: string,
+): Promise<A2ATask> {
+  const agent = registry.get(agentId);
+  if (!agent) throw new Error(`Agent not found: ${agentId}`);
+
+  const response = await jsonRpcCall(agent.endpoint, 'GetTask', { id: taskId }, token);
+
+  if (response.error) {
+    throw new Error(`A2A error [${response.error.code}]: ${response.error.message}`);
+  }
+
+  return response.result as A2ATask;
+}
+
+/* ── Registry Access ───────────────────────────────────────────────────── */
+
+/** Get all discovered agents */
+export function getDiscoveredAgents(): RemoteAgent[] {
+  return [...registry.values()];
+}
+
+/** Get a specific agent by ID */
+export function getAgent(id: string): RemoteAgent | undefined {
+  return registry.get(id);
+}
+
+/** Clear the agent registry cache */
+export function clearRegistry(): void {
+  registry.clear();
+}

package/app/lib/a2a/index.ts

@@ -1,5 +1,8 @@
 export { buildAgentCard } from './agent-card';
 export { handleSendMessage, handleGetTask, handleCancelTask } from './task-handler';
+export { discoverAgent, discoverAgents, delegateTask, checkRemoteTaskStatus, getDiscoveredAgents, getAgent, clearRegistry } from './client';
+export { matchSkill, decompose, createPlan, executePlan } from './orchestrator';
+export { a2aTools } from './a2a-tools';
 export { A2A_ERRORS } from './types';
 export type {
   AgentCard,
@@ -20,4 +23,9 @@ export type {
   SendMessageParams,
   GetTaskParams,
   CancelTaskParams,
+  RemoteAgent,
+  SubTask,
+  ExecutionStrategy,
+  OrchestrationPlan,
+  SkillMatch,
 } from './types';

package/app/lib/a2a/orchestrator.ts

@@ -0,0 +1,255 @@
+/**
+ * A2A Orchestrator — Multi-agent task decomposition and execution.
+ * Phase 3: Breaks complex requests into sub-tasks, matches to agents, executes, aggregates.
+ */
+
+import { randomUUID } from 'crypto';
+import type {
+  RemoteAgent,
+  SubTask,
+  OrchestrationPlan,
+  ExecutionStrategy,
+  SkillMatch,
+  AgentSkill,
+} from './types';
+import { getDiscoveredAgents, delegateTask } from './client';
+
+/* ── Constants ─────────────────────────────────────────────────────────── */
+
+const MAX_SUBTASKS = 10;
+
+/* ── Skill Matcher ─────────────────────────────────────────────────────── */
+
+/** Score how well a skill matches a task description (keyword overlap, deduplicated) */
+function scoreSkillMatch(taskDesc: string, skill: AgentSkill): number {
+  const taskWords = new Set(taskDesc.toLowerCase().split(/\s+/));
+  // Deduplicate skill words to avoid double-counting from name + description overlap
+  const skillWords = new Set([
+    ...skill.name.toLowerCase().split(/\s+/),
+    ...skill.description.toLowerCase().split(/\s+/),
+    ...(skill.tags ?? []).map(t => t.toLowerCase()),
+  ]);
+  let matches = 0;
+  for (const w of skillWords) {
+    if (w.length > 2 && taskWords.has(w)) matches++;
+  }
+  return matches;
+}
+
+/**
+ * Find the best agent+skill match for a sub-task description.
+ * Returns null if no agent has a relevant skill.
+ */
+export function matchSkill(taskDescription: string): SkillMatch | null {
+  const agents = getDiscoveredAgents().filter(a => a.reachable);
+  if (agents.length === 0) return null;
+
+  let best: SkillMatch | null = null;
+  let bestScore = 0;
+
+  for (const agent of agents) {
+    for (const skill of agent.card.skills) {
+      const score = scoreSkillMatch(taskDescription, skill);
+      if (score > bestScore) {
+        bestScore = score;
+        best = {
+          agentId: agent.id,
+          agentName: agent.card.name,
+          skillId: skill.id,
+          skillName: skill.name,
+          confidence: Math.min(score / 3, 1),
+        };
+      }
+    }
+  }
+
+  return best;
+}
+
+/* ── Task Decomposer ───────────────────────────────────────────────────── */
+
+/**
+ * Decompose a complex request into sub-tasks.
+ * Uses simple heuristics: split on sentence boundaries and conjunctions.
+ * For LLM-based decomposition, the agent tool can call this with pre-decomposed parts.
+ */
+export function decompose(request: string, subtaskDescriptions?: string[]): SubTask[] {
+  let descriptions: string[];
+
+  if (subtaskDescriptions && subtaskDescriptions.length > 0) {
+    descriptions = subtaskDescriptions;
+  } else {
+    descriptions = splitIntoSubtasks(request);
+  }
+
+  return descriptions.slice(0, MAX_SUBTASKS).map((desc, i) => ({
+    id: `st-${randomUUID().slice(0, 8)}`,
+    description: desc.trim(),
+    assignedAgentId: null,
+    matchedSkillId: null,
+    status: 'pending' as const,
+    result: null,
+    error: null,
+    dependsOn: [],
+  }));
+}
+
+/** Simple heuristic: split on "and then", "then", "also", numbered lists, semicolons */
+function splitIntoSubtasks(text: string): string[] {
+  // Try numbered list first: split on "N. " pattern at boundaries
+  const numbered = text.split(/(?:^|\s)(?=\d+\.\s)/m).map(s => s.replace(/^\d+\.\s*/, '').trim()).filter(Boolean);
+  if (numbered.length >= 2) return numbered;
+
+  // Try splitting on conjunctions/semicolons
+  const parts = text.split(/;\s*|\.\s+(?:then|and then|also|next|finally)\s+/i).filter(Boolean);
+  if (parts.length >= 2) return parts;
+
+  // Fallback: treat as single task
+  return [text];
+}
+
+/* ── Execution Engine ──────────────────────────────────────────────────── */
+
+/**
+ * Create an orchestration plan from a request.
+ */
+export function createPlan(
+  request: string,
+  strategy: ExecutionStrategy = 'parallel',
+  subtaskDescriptions?: string[],
+): OrchestrationPlan {
+  const subtasks = decompose(request, subtaskDescriptions);
+
+  // Auto-match skills to agents
+  for (const st of subtasks) {
+    const match = matchSkill(st.description);
+    if (match) {
+      st.assignedAgentId = match.agentId;
+      st.matchedSkillId = match.skillId;
+    }
+  }
+
+  return {
+    id: `plan-${randomUUID().slice(0, 8)}`,
+    originalRequest: request,
+    strategy,
+    subtasks,
+    createdAt: new Date().toISOString(),
+    completedAt: null,
+    status: 'planning',
+    aggregatedResult: null,
+  };
+}
+
+/**
+ * Execute a single sub-task by delegating to its assigned agent.
+ */
+async function executeSubtask(subtask: SubTask, token?: string): Promise<void> {
+  if (!subtask.assignedAgentId) {
+    subtask.status = 'failed';
+    subtask.error = 'No agent assigned to this subtask';
+    return;
+  }
+
+  subtask.status = 'running';
+
+  try {
+    // delegateTask has its own 30s RPC timeout via fetchWithTimeout in client.ts
+    const task = await delegateTask(subtask.assignedAgentId, subtask.description, token);
+
+    if (task.status.state === 'TASK_STATE_COMPLETED') {
+      subtask.status = 'completed';
+      subtask.result = task.artifacts?.[0]?.parts?.[0]?.text
+        ?? task.history?.find(m => m.role === 'ROLE_AGENT')?.parts?.[0]?.text
+        ?? 'Completed (no text result)';
+    } else if (task.status.state === 'TASK_STATE_FAILED') {
+      subtask.status = 'failed';
+      subtask.error = task.status.message?.parts?.[0]?.text ?? 'Agent reported failure';
+    } else {
+      subtask.status = 'completed';
+      subtask.result = `Task in progress (state: ${task.status.state})`;
+    }
+  } catch (err) {
+    subtask.status = 'failed';
+    subtask.error = (err as Error).message;
+  }
+}
+
+/**
+ * Execute all sub-tasks in an orchestration plan.
+ */
+export async function executePlan(plan: OrchestrationPlan, token?: string): Promise<OrchestrationPlan> {
+  plan.status = 'executing';
+
+  const unassigned = plan.subtasks.filter(st => !st.assignedAgentId);
+  if (unassigned.length === plan.subtasks.length) {
+    plan.status = 'failed';
+    plan.aggregatedResult = 'No agents available for any subtask. Discover agents first using discover_agent.';
+    return plan;
+  }
+
+  // Mark unassigned subtasks as failed before execution
+  for (const st of plan.subtasks) {
+    if (!st.assignedAgentId) {
+      st.status = 'failed';
+      st.error = 'No matching agent found for this subtask';
+    }
+  }
+
+  const assignedTasks = plan.subtasks.filter(st => st.assignedAgentId);
+
+  if (plan.strategy === 'parallel') {
+    await Promise.allSettled(
+      assignedTasks.map(st => executeSubtask(st, token))
+    );
+  } else {
+    // Sequential or dependency-based
+    for (const st of plan.subtasks) {
+      if (!st.assignedAgentId) {
+        st.status = 'failed';
+        st.error = 'No agent assigned';
+        continue;
+      }
+
+      // Check dependencies
+      if (st.dependsOn.length > 0) {
+        const deps = st.dependsOn.map(id => plan.subtasks.find(s => s.id === id));
+        const allDone = deps.every(d => d?.status === 'completed');
+        if (!allDone) {
+          st.status = 'failed';
+          st.error = 'Dependencies not met';
+          continue;
+        }
+      }
+
+      await executeSubtask(st, token);
+
+      // Stop on failure in sequential mode
+      if (plan.strategy === 'sequential' && st.status === 'failed') break;
+    }
+  }
+
+  // Aggregate results
+  const completed = plan.subtasks.filter(st => st.status === 'completed');
+  const failed = plan.subtasks.filter(st => st.status === 'failed');
+
+  if (failed.length === plan.subtasks.length) {
+    plan.status = 'failed';
+    plan.aggregatedResult = `All ${failed.length} subtasks failed:\n` +
+      failed.map(st => `- ${st.description}: ${st.error}`).join('\n');
+  } else {
+    plan.status = 'completed';
+    const parts: string[] = [];
+    for (const st of plan.subtasks) {
+      if (st.status === 'completed' && st.result) {
+        parts.push(`## ${st.description}\n\n${st.result}`);
+      } else if (st.status === 'failed') {
+        parts.push(`## ${st.description}\n\n[Failed: ${st.error}]`);
+      }
+    }
+    plan.aggregatedResult = parts.join('\n\n---\n\n');
+  }
+
+  plan.completedAt = new Date().toISOString();
+  return plan;
+}

package/app/lib/a2a/types.ts

@@ -156,3 +156,57 @@ export const A2A_ERRORS = {
   INVALID_PARAMS: { code: -32602, message: 'Invalid params' },
   INTERNAL_ERROR: { code: -32603, message: 'Internal error' },
 } as const;
+
+/* ── A2A Client Types (Phase 2) ────────────────────────────────────────── */
+
+/** A discovered remote agent with its card and endpoint */
+export interface RemoteAgent {
+  /** Unique identifier (derived from agent card URL) */
+  id: string;
+  /** The agent's card metadata */
+  card: AgentCard;
+  /** The JSON-RPC endpoint URL */
+  endpoint: string;
+  /** When this card was last fetched */
+  discoveredAt: string;
+  /** Whether the agent is currently reachable */
+  reachable: boolean;
+}
+
+/* ── Orchestration Types (Phase 3) ─────────────────────────────────────── */
+
+/** A sub-task decomposed from a user request */
+export interface SubTask {
+  id: string;
+  description: string;
+  assignedAgentId: string | null;
+  matchedSkillId: string | null;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  result: string | null;
+  error: string | null;
+  dependsOn: string[];
+}
+
+/** Execution strategy for sub-tasks */
+export type ExecutionStrategy = 'parallel' | 'sequential' | 'dependency';
+
+/** An orchestration plan produced by the decomposer */
+export interface OrchestrationPlan {
+  id: string;
+  originalRequest: string;
+  strategy: ExecutionStrategy;
+  subtasks: SubTask[];
+  createdAt: string;
+  completedAt: string | null;
+  status: 'planning' | 'executing' | 'completed' | 'failed';
+  aggregatedResult: string | null;
+}
+
+/** Result of matching a sub-task to an agent skill */
+export interface SkillMatch {
+  agentId: string;
+  agentName: string;
+  skillId: string;
+  skillName: string;
+  confidence: number;
+}

package/app/lib/agent/tools.ts

@@ -9,6 +9,7 @@ import {
 } from '@/lib/fs';
 import { readSkillContentByName, scanSkillDirs } from '@/lib/pi-integration/skills';
 import { callMcporterTool, createMcporterAgentTools, listMcporterServers, listMcporterTools } from '@/lib/pi-integration/mcporter';
+import { a2aTools } from '@/lib/a2a/a2a-tools';
 
 // Max chars per file to avoid token overflow (~100k chars ≈ ~25k tokens)
 const MAX_FILE_CHARS = 20_000;
@@ -186,10 +187,11 @@ export function getOrganizeTools(): AgentTool<any>[] {
 }
 
 export async function getRequestScopedTools(): Promise<AgentTool<any>[]> {
+  const baseTools = [...knowledgeBaseTools, ...a2aTools];
   try {
     const result = await listMcporterServers();
     const okServers = (result.servers ?? []).filter((server) => server.status === 'ok');
-    if (okServers.length === 0) return knowledgeBaseTools;
+    if (okServers.length === 0) return baseTools;
 
     const detailedServers = await Promise.all(okServers.map(async (server) => {
       try {
@@ -200,10 +202,10 @@ export async function getRequestScopedTools(): Promise<AgentTool<any>[]> {
     }));
 
     const dynamicMcpTools = createMcporterAgentTools(detailedServers);
-    if (dynamicMcpTools.length === 0) return knowledgeBaseTools;
-    return [...knowledgeBaseTools, ...dynamicMcpTools];
+    if (dynamicMcpTools.length === 0) return baseTools;
+    return [...baseTools, ...dynamicMcpTools];
   } catch {
-    return knowledgeBaseTools;
+    return baseTools;
   }
 }
 

package/app/lib/i18n-en.ts

@@ -241,6 +241,27 @@ export const en = {
       agentDetailPanelAria: 'Agent connection configuration',
       agentDetailTransport: 'Transport',
       agentDetailSnippet: 'Config snippet',
+      // A2A
+      a2aLabel: 'A2A',
+      a2aReady: 'A2A Ready',
+      a2aChecking: 'Checking A2A...',
+      a2aUnavailable: 'A2A Unavailable',
+      a2aRemote: 'Remote',
+      a2aDiscover: 'Discover Remote Agent',
+      a2aDiscoverHint: 'Connect to an external A2A agent by URL',
+      a2aDiscoverPlaceholder: 'https://agent.example.com',
+      a2aDiscovering: 'Discovering...',
+      a2aDiscoverSuccess: 'Agent discovered!',
+      a2aDiscoverFailed: 'No A2A agent found at this URL',
+      a2aDiscoverFailedHint: 'The server may not support the A2A protocol. Check the URL and try again.',
+      a2aSkills: 'Skills',
+      a2aEndpoint: 'Endpoint',
+      a2aVersion: 'Version',
+      a2aCapabilities: 'A2A Capabilities',
+      a2aStatus: 'Status',
+      a2aConnected: 'Connected & A2A Ready',
+      a2aNoRemote: 'No remote agents',
+      a2aNoRemoteHint: 'Discover remote agents to enable cross-agent delegation.',
     },
     plugins: {
       title: 'Plugins',
@@ -1463,4 +1484,35 @@ prompt: "Here's my resume, read it and organize my info into MindOS.",
       ],
     },
   },
+
+  /** Disabled-state and contextual tooltip hints */
+  hints: {
+    noValidFiles: 'No valid files selected',
+    aiOrganizing: 'AI is organizing',
+    importInProgress: 'Import in progress',
+    templateInitializing: 'Another template is being initialized',
+    configureAiKey: 'Configure API key in Settings → AI',
+    syncInProgress: 'Sync already in progress',
+    toggleInProgress: 'Toggle operation in progress',
+    typeMessage: 'Type a message',
+    mentionInProgress: 'Mention or command in progress',
+    cleanupInProgress: 'Cleanup already in progress',
+    tokenResetInProgress: 'Token reset in progress',
+    aiNotConfigured: 'AI not configured or generation in progress',
+    generationInProgress: 'Generation in progress or AI not configured',
+    cannotJumpForward: 'Cannot jump forward in setup',
+    testInProgressOrNoKey: 'Test in progress or no API key',
+    workflowStepRunning: 'Workflow step already running',
+    workflowRunning: 'Workflow step is running',
+    sessionHistory: 'Session history',
+    newSession: 'New session',
+    attachFile: 'Attach local file',
+    maximizePanel: 'Maximize panel',
+    restorePanel: 'Restore panel',
+    dockToSide: 'Dock to side panel',
+    openAsPopup: 'Open as popup',
+    closePanel: 'Close',
+    newChat: 'New chat',
+    closeSession: 'Close session',
+  },
 } as const;