@radaros/core 0.1.0 → 0.2.0

package/src/a2a/a2a-remote-agent.ts

@@ -0,0 +1,270 @@
+import type {
+  A2AAgentCard,
+  A2AJsonRpcRequest,
+  A2AJsonRpcResponse,
+  A2AMessage,
+  A2APart,
+  A2ATask,
+} from "./types.js";
+import type { RunOpts, RunOutput } from "../agent/types.js";
+import type { ToolDef, ToolResult } from "../tools/types.js";
+import type { StreamChunk } from "../models/types.js";
+import type { RunContext } from "../agent/run-context.js";
+import { z } from "zod";
+
+export interface A2ARemoteAgentConfig {
+  url: string;
+  /** Custom headers for every request (e.g. auth tokens). */
+  headers?: Record<string, string>;
+  /** Override the discovered name. */
+  name?: string;
+  /** Request timeout in ms (default 60000). */
+  timeoutMs?: number;
+}
+
+/**
+ * A2ARemoteAgent wraps a remote A2A-compliant agent.
+ * It can be used as a tool, a Team member, or called directly.
+ */
+export class A2ARemoteAgent {
+  readonly url: string;
+  name: string;
+  instructions: string;
+  skills: Array<{ id: string; name: string; description?: string }> = [];
+
+  private headers: Record<string, string>;
+  private timeoutMs: number;
+  private card: A2AAgentCard | null = null;
+  private rpcId = 0;
+
+  get tools(): ToolDef[] {
+    return [];
+  }
+
+  get modelId(): string {
+    return "a2a-remote";
+  }
+
+  get providerId(): string {
+    return "a2a";
+  }
+
+  get hasStructuredOutput(): boolean {
+    return false;
+  }
+
+  constructor(config: A2ARemoteAgentConfig) {
+    this.url = config.url.replace(/\/$/, "");
+    this.name = config.name ?? "remote-agent";
+    this.instructions = "";
+    this.headers = config.headers ?? {};
+    this.timeoutMs = config.timeoutMs ?? 60_000;
+  }
+
+  /**
+   * Fetch the Agent Card from /.well-known/agent.json and populate metadata.
+   */
+  async discover(): Promise<A2AAgentCard> {
+    const res = await fetch(`${this.url}/.well-known/agent.json`, {
+      headers: this.headers,
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+
+    if (!res.ok) {
+      throw new Error(
+        `A2A discover failed: ${res.status} ${res.statusText} from ${this.url}`
+      );
+    }
+
+    this.card = (await res.json()) as A2AAgentCard;
+    this.name = this.card.name;
+    this.instructions = this.card.description ?? "";
+    this.skills =
+      this.card.skills?.map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+      })) ?? [];
+
+    return this.card;
+  }
+
+  /**
+   * Synchronous run: sends message/send and returns RunOutput.
+   */
+  async run(
+    input: string,
+    opts?: RunOpts
+  ): Promise<RunOutput> {
+    const message: A2AMessage = {
+      role: "user",
+      parts: [{ kind: "text", text: input }],
+    };
+
+    const rpcReq: A2AJsonRpcRequest = {
+      jsonrpc: "2.0",
+      id: ++this.rpcId,
+      method: "message/send",
+      params: {
+        message,
+        ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+      },
+    };
+
+    const startMs = Date.now();
+    const res = await fetch(this.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.headers,
+      },
+      body: JSON.stringify(rpcReq),
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+
+    if (!res.ok) {
+      throw new Error(`A2A message/send failed: ${res.status} ${res.statusText}`);
+    }
+
+    const rpcRes = (await res.json()) as A2AJsonRpcResponse;
+    if (rpcRes.error) {
+      throw new Error(`A2A error: ${rpcRes.error.message}`);
+    }
+
+    const task = rpcRes.result as A2ATask;
+    const agentMsg = task.status?.message;
+    const text = agentMsg
+      ? this.partsToText(agentMsg.parts)
+      : "";
+
+    return {
+      text,
+      toolCalls: [],
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      durationMs: Date.now() - startMs,
+    };
+  }
+
+  /**
+   * Streaming run: sends message/stream and yields StreamChunks from SSE.
+   */
+  async *stream(
+    input: string,
+    opts?: RunOpts
+  ): AsyncGenerator<StreamChunk> {
+    const message: A2AMessage = {
+      role: "user",
+      parts: [{ kind: "text", text: input }],
+    };
+
+    const rpcReq: A2AJsonRpcRequest = {
+      jsonrpc: "2.0",
+      id: ++this.rpcId,
+      method: "message/stream",
+      params: {
+        message,
+        ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+      },
+    };
+
+    const res = await fetch(this.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.headers,
+      },
+      body: JSON.stringify(rpcReq),
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+
+    if (!res.ok) {
+      throw new Error(`A2A message/stream failed: ${res.status} ${res.statusText}`);
+    }
+
+    if (!res.body) {
+      throw new Error("A2A message/stream: no response body for SSE");
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop()!;
+
+      for (const line of lines) {
+        if (!line.startsWith("data: ")) continue;
+        const jsonStr = line.slice(6).trim();
+        if (!jsonStr) continue;
+
+        try {
+          const event = JSON.parse(jsonStr) as A2AJsonRpcResponse;
+          const task = event.result as A2ATask | undefined;
+          if (!task) continue;
+
+          if (
+            task.status?.state === "working" &&
+            task.status.message?.parts?.length
+          ) {
+            for (const part of task.status.message.parts) {
+              if (part.kind === "text") {
+                yield { type: "text", text: part.text };
+              }
+            }
+          }
+
+          if (task.status?.state === "completed") {
+            yield {
+              type: "finish",
+              finishReason: "stop",
+              usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            };
+          }
+        } catch {
+          // skip unparseable lines
+        }
+      }
+    }
+  }
+
+  /**
+   * Wrap this remote agent as a ToolDef so it can be used by an orchestrator agent.
+   */
+  asTool(): ToolDef {
+    const self = this;
+    return {
+      name: `a2a_${this.name.replace(/[^a-zA-Z0-9_]/g, "_")}`,
+      description:
+        this.instructions ||
+        `Remote A2A agent: ${this.name}`,
+      parameters: z.object({
+        message: z.string().describe("The message to send to the remote agent"),
+      }),
+      async execute(
+        args: Record<string, unknown>,
+        _ctx: RunContext
+      ): Promise<string | ToolResult> {
+        const result = await self.run(args.message as string);
+        return result.text;
+      },
+    };
+  }
+
+  getAgentCard(): A2AAgentCard | null {
+    return this.card;
+  }
+
+  private partsToText(parts: A2APart[]): string {
+    return parts
+      .filter(
+        (p): p is { kind: "text"; text: string } => p.kind === "text"
+      )
+      .map((p) => p.text)
+      .join("\n");
+  }
+}

package/src/a2a/types.ts

@@ -0,0 +1,142 @@
+/**
+ * A2A (Agent-to-Agent) Protocol types.
+ * Based on the A2A specification v0.2.
+ * https://google.github.io/A2A/specification/
+ */
+
+// ── Parts ─────────────────────────────────────────────────────────────────
+
+export interface A2ATextPart {
+  kind: "text";
+  text: string;
+}
+
+export interface A2AFilePart {
+  kind: "file";
+  file: {
+    name?: string;
+    mimeType?: string;
+    bytes?: string;
+    uri?: string;
+  };
+}
+
+export interface A2ADataPart {
+  kind: "data";
+  data: Record<string, unknown>;
+}
+
+export type A2APart = A2ATextPart | A2AFilePart | A2ADataPart;
+
+// ── Messages ──────────────────────────────────────────────────────────────
+
+export interface A2AMessage {
+  role: "user" | "agent";
+  parts: A2APart[];
+  messageId?: string;
+  taskId?: string;
+  referenceTaskIds?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+// ── Task ──────────────────────────────────────────────────────────────────
+
+export type A2ATaskState =
+  | "submitted"
+  | "working"
+  | "input-required"
+  | "completed"
+  | "failed"
+  | "canceled";
+
+export interface A2AArtifact {
+  artifactId: string;
+  name?: string;
+  description?: string;
+  parts: A2APart[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2ATask {
+  id: string;
+  sessionId?: string;
+  status: {
+    state: A2ATaskState;
+    message?: A2AMessage;
+    timestamp?: string;
+  };
+  artifacts?: A2AArtifact[];
+  history?: A2AMessage[];
+  metadata?: Record<string, unknown>;
+}
+
+// ── Agent Card ────────────────────────────────────────────────────────────
+
+export interface A2ASkill {
+  id: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  examples?: string[];
+}
+
+export interface A2AAgentCard {
+  name: string;
+  description?: string;
+  url: string;
+  version?: string;
+  provider?: {
+    organization: string;
+    url?: string;
+  };
+  capabilities?: {
+    streaming?: boolean;
+    pushNotifications?: boolean;
+    stateTransitionHistory?: boolean;
+  };
+  authentication?: {
+    schemes?: string[];
+    credentials?: string;
+  };
+  skills?: A2ASkill[];
+  defaultInputModes?: string[];
+  defaultOutputModes?: string[];
+  supportedInputModes?: string[];
+  supportedOutputModes?: string[];
+}
+
+// ── JSON-RPC ──────────────────────────────────────────────────────────────
+
+export interface A2AJsonRpcRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface A2AJsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+// ── Send/Stream params ────────────────────────────────────────────────────
+
+export interface A2ASendParams {
+  message: A2AMessage;
+  configuration?: {
+    acceptedOutputModes?: string[];
+    blocking?: boolean;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2ATaskQueryParams {
+  id: string;
+  historyLength?: number;
+}

package/src/index.ts

@@ -109,3 +109,27 @@ export type { AgentEventMap } from "./events/types.js";
 // Logger
 export { Logger } from "./logger/logger.js";
 export type { LogLevel, LoggerConfig } from "./logger/logger.js";
+
+// MCP
+export { MCPToolProvider } from "./mcp/mcp-client.js";
+export type { MCPToolProviderConfig } from "./mcp/mcp-client.js";
+
+// A2A
+export { A2ARemoteAgent } from "./a2a/a2a-remote-agent.js";
+export type { A2ARemoteAgentConfig } from "./a2a/a2a-remote-agent.js";
+export type {
+  A2AAgentCard,
+  A2ASkill,
+  A2ATask,
+  A2ATaskState,
+  A2AMessage,
+  A2APart,
+  A2ATextPart,
+  A2AFilePart,
+  A2ADataPart,
+  A2AArtifact,
+  A2AJsonRpcRequest,
+  A2AJsonRpcResponse,
+  A2ASendParams,
+  A2ATaskQueryParams,
+} from "./a2a/types.js";

package/src/mcp/mcp-client.ts

@@ -0,0 +1,264 @@
+import type { ToolDef, ToolResult } from "../tools/types.js";
+import type { RunContext } from "../agent/run-context.js";
+
+export interface MCPToolProviderConfig {
+  name: string;
+  transport: "stdio" | "http";
+  /** For stdio transport: command to spawn */
+  command?: string;
+  /** For stdio transport: args for the command */
+  args?: string[];
+  /** For stdio transport: environment variables */
+  env?: Record<string, string>;
+  /** For http transport: server URL */
+  url?: string;
+  /** For http transport: custom headers */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Connects to an MCP (Model Context Protocol) server and exposes its tools
+ * as native RadarOS ToolDef[] that any Agent can use.
+ *
+ * Supports stdio and HTTP (Streamable HTTP) transports.
+ * Requires: npm install @modelcontextprotocol/sdk
+ */
+export class MCPToolProvider {
+  readonly name: string;
+  private config: MCPToolProviderConfig;
+  private client: any = null;
+  private transportInstance: any = null;
+  private tools: ToolDef[] = [];
+  private connected = false;
+
+  constructor(config: MCPToolProviderConfig) {
+    this.name = config.name;
+    this.config = config;
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+
+    let ClientClass: any;
+    try {
+      const mod = await import("@modelcontextprotocol/sdk/client/index.js");
+      ClientClass = mod.Client;
+    } catch {
+      throw new Error(
+        "@modelcontextprotocol/sdk is required for MCPToolProvider. Install it: npm install @modelcontextprotocol/sdk"
+      );
+    }
+
+    this.client = new ClientClass(
+      { name: `radaros-${this.name}`, version: "1.0.0" },
+      { capabilities: {} }
+    );
+
+    if (this.config.transport === "stdio") {
+      if (!this.config.command) {
+        throw new Error("MCPToolProvider: 'command' is required for stdio transport");
+      }
+      const { StdioClientTransport } = await import(
+        "@modelcontextprotocol/sdk/client/stdio.js"
+      );
+
+      this.transportInstance = new StdioClientTransport({
+        command: this.config.command,
+        args: this.config.args ?? [],
+        env: { ...process.env, ...(this.config.env ?? {}) } as Record<string, string>,
+      });
+    } else if (this.config.transport === "http") {
+      if (!this.config.url) {
+        throw new Error("MCPToolProvider: 'url' is required for http transport");
+      }
+
+      let TransportClass: any;
+      try {
+        const mod = await import(
+          "@modelcontextprotocol/sdk/client/streamableHttp.js"
+        );
+        TransportClass = mod.StreamableHTTPClientTransport;
+      } catch {
+        const mod = await import("@modelcontextprotocol/sdk/client/sse.js");
+        TransportClass = mod.SSEClientTransport;
+      }
+
+      this.transportInstance = new TransportClass(
+        new URL(this.config.url),
+        { requestInit: { headers: this.config.headers ?? {} } }
+      );
+    } else {
+      throw new Error(`MCPToolProvider: unsupported transport '${this.config.transport}'`);
+    }
+
+    await this.client.connect(this.transportInstance);
+    this.connected = true;
+    await this.discoverTools();
+  }
+
+  private async discoverTools(): Promise<void> {
+    const { z } = await import("zod");
+    const result = await this.client.listTools();
+    const mcpTools: any[] = result.tools ?? [];
+
+    this.tools = mcpTools.map((mcpTool: any) => {
+      const toolName = mcpTool.name;
+      const description = mcpTool.description ?? "";
+      const inputSchema = mcpTool.inputSchema ?? { type: "object", properties: {} };
+
+      const parameters = this.jsonSchemaToZod(inputSchema, z);
+
+      const execute = async (
+        args: Record<string, unknown>,
+        _ctx: RunContext
+      ): Promise<string | ToolResult> => {
+        const callResult = await this.client.callTool({
+          name: toolName,
+          arguments: args,
+        });
+
+        const contents: any[] = callResult.content ?? [];
+        const textParts = contents
+          .filter((c: any) => c.type === "text")
+          .map((c: any) => c.text);
+
+        const text = textParts.join("\n") || JSON.stringify(callResult);
+
+        const artifacts = contents
+          .filter((c: any) => c.type !== "text")
+          .map((c: any) => ({
+            type: c.type,
+            data: c.data ?? c.blob ?? c.text,
+            mimeType: c.mimeType,
+          }));
+
+        if (artifacts.length > 0) {
+          return { content: text, artifacts };
+        }
+        return text;
+      };
+
+      return {
+        name: `${this.name}__${toolName}`,
+        description: `[${this.name}] ${description}`,
+        parameters,
+        execute,
+        rawJsonSchema: inputSchema,
+      } satisfies ToolDef;
+    });
+  }
+
+  private jsonSchemaToZod(schema: any, z: any): any {
+    if (!schema || !schema.properties) {
+      return z.object({}).passthrough();
+    }
+
+    const shape: Record<string, any> = {};
+    const required: string[] = schema.required ?? [];
+
+    for (const [key, prop] of Object.entries(schema.properties) as [string, any][]) {
+      let field: any;
+
+      switch (prop.type) {
+        case "string":
+          field = z.string();
+          if (prop.enum) field = z.enum(prop.enum);
+          break;
+        case "number":
+        case "integer":
+          field = z.number();
+          break;
+        case "boolean":
+          field = z.boolean();
+          break;
+        case "array":
+          field = z.array(z.any());
+          break;
+        case "object":
+          field = z.record(z.any());
+          break;
+        default:
+          field = z.any();
+      }
+
+      if (prop.description) {
+        field = field.describe(prop.description);
+      }
+
+      if (!required.includes(key)) {
+        field = field.optional();
+      }
+
+      shape[key] = field;
+    }
+
+    return z.object(shape);
+  }
+
+  /**
+   * Returns tools from this MCP server as RadarOS ToolDef[].
+   * Optionally filter by tool names to reduce token usage.
+   *
+   * @param filter - Tool names to include (without the server name prefix).
+   *                 If omitted, returns all tools.
+   *
+   * @example
+   * // All tools
+   * await mcp.getTools()
+   *
+   * // Only specific tools (pass the original MCP tool names, not prefixed)
+   * await mcp.getTools({ include: ["get_latest_release", "search_repositories"] })
+   *
+   * // Exclude specific tools
+   * await mcp.getTools({ exclude: ["push_files", "create_repository"] })
+   */
+  async getTools(filter?: {
+    include?: string[];
+    exclude?: string[];
+  }): Promise<ToolDef[]> {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    if (!filter) {
+      return [...this.tools];
+    }
+
+    const prefix = `${this.name}__`;
+
+    return this.tools.filter((tool) => {
+      const shortName = tool.name.startsWith(prefix)
+        ? tool.name.slice(prefix.length)
+        : tool.name;
+
+      if (filter.include) {
+        return filter.include.includes(shortName);
+      }
+      if (filter.exclude) {
+        return !filter.exclude.includes(shortName);
+      }
+      return true;
+    });
+  }
+
+  /** Refresh the tool list from the MCP server. */
+  async refresh(): Promise<void> {
+    if (!this.connected) {
+      throw new Error("MCPToolProvider: not connected. Call connect() first.");
+    }
+    await this.discoverTools();
+  }
+
+  /** Disconnect from the MCP server. */
+  async close(): Promise<void> {
+    if (this.client && this.connected) {
+      try {
+        await this.client.close();
+      } catch {
+        // ignore close errors
+      }
+      this.connected = false;
+      this.tools = [];
+    }
+  }
+}