agent-relay 3.2.2 → 3.2.4

package/packages/sdk/src/communicate/a2a-types.ts

@@ -0,0 +1,338 @@
+/**
+ * A2A (Agent-to-Agent) protocol data model types.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+// --- Data model ---
+
+export interface A2APart {
+  text?: string;
+  file?: Record<string, unknown>; // FileContent — phase 2
+  data?: Record<string, unknown>; // Structured data — phase 2
+}
+
+export interface A2AMessage {
+  role: 'user' | 'agent';
+  parts: A2APart[];
+  messageId?: string;
+  contextId?: string;
+  taskId?: string;
+}
+
+export type A2ATaskState =
+  | 'submitted'
+  | 'working'
+  | 'completed'
+  | 'failed'
+  | 'canceled';
+
+export const VALID_TASK_STATES: ReadonlySet<string> = new Set([
+  'submitted',
+  'working',
+  'completed',
+  'failed',
+  'canceled',
+]);
+
+export interface A2ATaskStatus {
+  state: A2ATaskState;
+  message?: A2AMessage;
+  timestamp?: string;
+}
+
+export interface A2ATask {
+  id: string;
+  contextId?: string;
+  status: A2ATaskStatus;
+  messages: A2AMessage[];
+  artifacts: Record<string, unknown>[];
+}
+
+export interface A2ASkill {
+  id: string;
+  name: string;
+  description: string;
+}
+
+export interface A2AAgentCard {
+  name: string;
+  description: string;
+  url: string;
+  version: string;
+  capabilities: Record<string, unknown>;
+  skills: A2ASkill[];
+  defaultInputModes: string[];
+  defaultOutputModes: string[];
+}
+
+export interface A2AConfig {
+  /** Server mode */
+  serverPort?: number;
+  serverHost?: string;
+  /** Client mode */
+  targetUrl?: string;
+  /** Agent Card registry (known A2A agent URLs) */
+  registry?: string[];
+  /** Auth */
+  authScheme?: 'bearer' | 'api_key' | string;
+  authToken?: string;
+  /** Agent metadata */
+  agentDescription?: string;
+  skills?: A2ASkill[];
+}
+
+// --- Factories ---
+
+export function createA2APart(text?: string): A2APart {
+  const part: A2APart = {};
+  if (text !== undefined) part.text = text;
+  return part;
+}
+
+export function createA2AMessage(
+  role: 'user' | 'agent',
+  parts: A2APart[],
+  opts?: { messageId?: string; contextId?: string; taskId?: string },
+): A2AMessage {
+  return {
+    role,
+    parts,
+    messageId: opts?.messageId ?? randomUUID(),
+    contextId: opts?.contextId,
+    taskId: opts?.taskId,
+  };
+}
+
+export function createA2ATaskStatus(
+  state: A2ATaskState,
+  message?: A2AMessage,
+): A2ATaskStatus {
+  return {
+    state,
+    message,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function createA2ATask(
+  id: string,
+  contextId?: string,
+): A2ATask {
+  return {
+    id,
+    contextId,
+    status: createA2ATaskStatus('submitted'),
+    messages: [],
+    artifacts: [],
+  };
+}
+
+export function createA2AAgentCard(
+  name: string,
+  description: string,
+  url: string,
+  skills: A2ASkill[] = [],
+): A2AAgentCard {
+  return {
+    name,
+    description,
+    url,
+    version: '1.0.0',
+    capabilities: { streaming: true, pushNotifications: false },
+    skills,
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+  };
+}
+
+// --- Serialization helpers ---
+
+export function a2aPartToDict(part: A2APart): Record<string, unknown> {
+  const d: Record<string, unknown> = {};
+  if (part.text !== undefined) d.text = part.text;
+  if (part.file !== undefined) d.file = part.file;
+  if (part.data !== undefined) d.data = part.data;
+  return d;
+}
+
+export function a2aPartFromDict(d: Record<string, unknown>): A2APart {
+  return {
+    text: d.text as string | undefined,
+    file: d.file as Record<string, unknown> | undefined,
+    data: d.data as Record<string, unknown> | undefined,
+  };
+}
+
+export function a2aMessageToDict(msg: A2AMessage): Record<string, unknown> {
+  const d: Record<string, unknown> = {
+    role: msg.role,
+    parts: msg.parts.map(a2aPartToDict),
+  };
+  if (msg.messageId !== undefined) d.messageId = msg.messageId;
+  if (msg.contextId !== undefined) d.contextId = msg.contextId;
+  if (msg.taskId !== undefined) d.taskId = msg.taskId;
+  return d;
+}
+
+export function a2aMessageFromDict(d: Record<string, unknown>): A2AMessage {
+  const parts = ((d.parts as Record<string, unknown>[] | undefined) ?? []).map(a2aPartFromDict);
+  return {
+    role: d.role as 'user' | 'agent',
+    parts,
+    messageId: d.messageId as string | undefined,
+    contextId: d.contextId as string | undefined,
+    taskId: d.taskId as string | undefined,
+  };
+}
+
+export function a2aMessageGetText(msg: A2AMessage): string {
+  return msg.parts
+    .filter((p) => p.text)
+    .map((p) => p.text!)
+    .join(' ');
+}
+
+export function a2aTaskStatusToDict(status: A2ATaskStatus): Record<string, unknown> {
+  const d: Record<string, unknown> = { state: status.state };
+  if (status.message !== undefined) d.message = a2aMessageToDict(status.message);
+  if (status.timestamp !== undefined) d.timestamp = status.timestamp;
+  return d;
+}
+
+export function a2aTaskStatusFromDict(d: Record<string, unknown>): A2ATaskStatus {
+  let message: A2AMessage | undefined;
+  if (d.message !== undefined && d.message !== null) {
+    message = a2aMessageFromDict(d.message as Record<string, unknown>);
+  }
+  return {
+    state: d.state as A2ATaskState,
+    message,
+    timestamp: d.timestamp as string | undefined,
+  };
+}
+
+export function a2aTaskToDict(task: A2ATask): Record<string, unknown> {
+  return {
+    id: task.id,
+    contextId: task.contextId,
+    status: a2aTaskStatusToDict(task.status),
+    messages: task.messages.map(a2aMessageToDict),
+    artifacts: task.artifacts,
+  };
+}
+
+export function a2aTaskFromDict(d: Record<string, unknown>): A2ATask {
+  const status = d.status
+    ? a2aTaskStatusFromDict(d.status as Record<string, unknown>)
+    : createA2ATaskStatus('submitted');
+  const messages = ((d.messages as Record<string, unknown>[]) ?? []).map(a2aMessageFromDict);
+  return {
+    id: d.id as string,
+    contextId: d.contextId as string | undefined,
+    status,
+    messages,
+    artifacts: (d.artifacts as Record<string, unknown>[]) ?? [],
+  };
+}
+
+export function a2aSkillToDict(skill: A2ASkill): Record<string, unknown> {
+  return { id: skill.id, name: skill.name, description: skill.description };
+}
+
+export function a2aSkillFromDict(d: Record<string, unknown>): A2ASkill {
+  return {
+    id: d.id as string,
+    name: d.name as string,
+    description: d.description as string,
+  };
+}
+
+export function a2aAgentCardToDict(card: A2AAgentCard): Record<string, unknown> {
+  return {
+    name: card.name,
+    description: card.description,
+    url: card.url,
+    version: card.version,
+    capabilities: card.capabilities,
+    skills: card.skills.map(a2aSkillToDict),
+    defaultInputModes: card.defaultInputModes,
+    defaultOutputModes: card.defaultOutputModes,
+  };
+}
+
+export function a2aAgentCardFromDict(d: Record<string, unknown>): A2AAgentCard {
+  const skills = ((d.skills as Record<string, unknown>[]) ?? []).map(a2aSkillFromDict);
+  return {
+    name: d.name as string,
+    description: d.description as string,
+    url: d.url as string,
+    version: (d.version as string) ?? '1.0.0',
+    capabilities: (d.capabilities as Record<string, unknown>) ?? {
+      streaming: true,
+      pushNotifications: false,
+    },
+    skills,
+    defaultInputModes: (d.defaultInputModes as string[]) ?? ['text'],
+    defaultOutputModes: (d.defaultOutputModes as string[]) ?? ['text'],
+  };
+}
+
+// --- JSON-RPC 2.0 helpers ---
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  method: string;
+  params: Record<string, unknown>;
+  id: string | number;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  result?: unknown;
+  error?: { code: number; message: string };
+  id: string | number | null;
+}
+
+export function makeJsonRpcRequest(
+  method: string,
+  params: Record<string, unknown>,
+  id?: string | number,
+): JsonRpcRequest {
+  return {
+    jsonrpc: '2.0',
+    method,
+    params,
+    id: id ?? randomUUID(),
+  };
+}
+
+export function makeJsonRpcResponse(
+  result: unknown,
+  id: string | number,
+): JsonRpcResponse {
+  return { jsonrpc: '2.0', result, id };
+}
+
+export function makeJsonRpcError(
+  code: number,
+  message: string,
+  id: string | number | null,
+): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    error: { code, message },
+    id,
+  };
+}
+
+// Standard JSON-RPC error codes
+export const JSONRPC_PARSE_ERROR = -32700;
+export const JSONRPC_INVALID_REQUEST = -32600;
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+export const JSONRPC_INVALID_PARAMS = -32602;
+export const JSONRPC_INTERNAL_ERROR = -32603;
+
+// A2A-specific error codes
+export const A2A_TASK_NOT_FOUND = -32001;
+export const A2A_TASK_NOT_CANCELABLE = -32002;

package/packages/sdk/src/communicate/adapters/claude-sdk.ts

@@ -0,0 +1,85 @@
+import { Relay } from '../core.js';
+import { formatRelayMessage, type Message } from '../types.js';
+
+type HookResult = {
+  continue?: boolean;
+  systemMessage?: string;
+};
+
+type HookCallback = (...args: unknown[]) => Promise<HookResult>;
+
+type HookMatcher = {
+  matcher?: string;
+  hooks: HookCallback[];
+  timeout?: number;
+};
+
+type ClaudeOptionsLike = {
+  mcpServers?: Record<string, unknown>;
+  hooks?: Partial<Record<'PostToolUse' | 'Stop', HookMatcher[]>>;
+};
+
+type RelayLike = {
+  inbox(): Promise<Message[]>;
+};
+
+function appendHook(
+  hooks: ClaudeOptionsLike['hooks'],
+  event: 'PostToolUse' | 'Stop',
+  callback: HookCallback
+): ClaudeOptionsLike['hooks'] {
+  const matchers = [...(hooks?.[event] ?? []), { hooks: [callback] }];
+
+  return {
+    ...hooks,
+    [event]: matchers,
+  };
+}
+
+async function drainInbox(relay: RelayLike): Promise<string | undefined> {
+  const messages = await relay.inbox();
+  if (messages.length === 0) {
+    return undefined;
+  }
+
+  return `New messages from other agents:\n${messages.map((message) => formatRelayMessage(message)).join('\n')}`;
+}
+
+/**
+ * Attach relay communication to Claude Agent SDK options via MCP server and hooks.
+ * @param _name - Agent name for relay registration.
+ * @param options - Claude SDK query options to augment.
+ * @param relay - Optional pre-configured Relay instance.
+ * @returns Augmented options with relaycast MCP server and inbox-draining hooks.
+ */
+export function onRelay<TOptions extends ClaudeOptionsLike>(
+  _name: string,
+  options: TOptions,
+  relay: RelayLike = new Relay(_name)
+): TOptions {
+  const mcpServers = {
+    ...(options.mcpServers ?? {}),
+    relaycast: {
+      command: 'agent-relay',
+      args: ['mcp'],
+    },
+  };
+
+  let hooks = options.hooks;
+
+  hooks = appendHook(hooks, 'PostToolUse', async () => {
+    const systemMessage = await drainInbox(relay);
+    return systemMessage ? { systemMessage } : {};
+  });
+
+  hooks = appendHook(hooks, 'Stop', async () => {
+    const systemMessage = await drainInbox(relay);
+    return systemMessage ? { continue: true, systemMessage } : {};
+  });
+
+  return {
+    ...options,
+    mcpServers,
+    hooks,
+  };
+}

package/packages/sdk/src/communicate/adapters/crewai.ts

@@ -0,0 +1,141 @@
+import { Relay } from '../core.js';
+import { formatRelayInbox, formatRelayMessage, type Message, type MessageCallback } from '../types.js';
+
+/**
+ * Minimal structural types mirroring the CrewAI JS SDK's Agent and Crew classes.
+ * We use duck-typing so callers don't need to import crewai directly.
+ */
+
+type CrewAITool = {
+  tool_name: string;
+  description: string;
+  execute: (args: Record<string, unknown>) => Promise<string>;
+};
+
+type CrewAIAgentLike = {
+  role: string;
+  tools: any[];
+  step_callback?: ((step: any) => void) | null;
+};
+
+type CrewAICrewLike = {
+  agents: CrewAIAgentLike[];
+  task_callback?: ((output: any) => void) | null;
+};
+
+type RelayLike = {
+  send(to: string, text: string): Promise<void>;
+  post(channel: string, text: string): Promise<void>;
+  inbox(): Promise<Message[]>;
+  agents(): Promise<string[]>;
+  onMessage(callback: MessageCallback): () => void;
+};
+
+function createRelayTools(relay: RelayLike): CrewAITool[] {
+  return [
+    {
+      tool_name: 'relay_send',
+      description: 'Send a direct message to another relay agent.',
+      async execute(args) {
+        await relay.send(args.to as string, args.text as string);
+        return `Sent relay message to ${args.to}.`;
+      },
+    },
+    {
+      tool_name: 'relay_inbox',
+      description: 'Drain and inspect newly received relay messages.',
+      async execute() {
+        return formatRelayInbox(await relay.inbox());
+      },
+    },
+    {
+      tool_name: 'relay_post',
+      description: 'Post a message to a relay channel.',
+      async execute(args) {
+        await relay.post(args.channel as string, args.text as string);
+        return `Posted relay message to #${args.channel}.`;
+      },
+    },
+    {
+      tool_name: 'relay_agents',
+      description: 'List currently online relay agents.',
+      async execute() {
+        return (await relay.agents()).join('\n');
+      },
+    },
+  ];
+}
+
+/**
+ * Attach relay communication tools and message routing to a CrewAI Agent.
+ *
+ * Adds relay tools to the agent's `tools` array and installs a `step_callback`
+ * that receives incoming relay messages.
+ *
+ * @param agent - A CrewAI Agent instance (or duck-typed equivalent).
+ * @param relay - Optional pre-configured Relay instance.
+ * @returns Object with an `unsubscribe` function to stop message routing.
+ */
+export function onRelay(
+  agent: CrewAIAgentLike,
+  relay?: RelayLike,
+): { unsubscribe: () => void } {
+  const relayInstance: RelayLike = relay ?? new Relay(agent.role);
+  const relayTools = createRelayTools(relayInstance);
+
+  // Append relay tools to agent's tools array
+  for (const tool of relayTools) {
+    agent.tools.push(tool);
+  }
+
+  // Install message routing via step_callback
+  const originalCallback = agent.step_callback;
+
+  const unsubscribe = relayInstance.onMessage(async (message) => {
+    const formatted = formatRelayMessage(message);
+
+    // Route relay messages through the original callback if one exists
+    if (originalCallback) {
+      originalCallback({ relay_message: formatted });
+    }
+  });
+
+  // Compose original callback with relay step forwarding
+  if (originalCallback) {
+    agent.step_callback = (step: any) => {
+      // Forward non-relay steps to original callback
+      if (!step?.relay_message) {
+        originalCallback(step);
+      }
+    };
+  }
+
+  return { unsubscribe };
+}
+
+/**
+ * Attach relay communication tools to all agents in a CrewAI Crew.
+ *
+ * @param crew - A CrewAI Crew instance (or duck-typed equivalent).
+ * @param relay - Optional pre-configured Relay instance.
+ * @returns Object with an `unsubscribe` function to stop all message routing.
+ */
+export function onCrewRelay(
+  crew: CrewAICrewLike,
+  relay?: RelayLike,
+): { unsubscribe: () => void } {
+  const unsubscribers: Array<() => void> = [];
+
+  for (const agent of crew.agents) {
+    const result = onRelay(agent, relay);
+    unsubscribers.push(result.unsubscribe);
+  }
+
+  return {
+    unsubscribe() {
+      for (const unsub of unsubscribers) {
+        unsub();
+      }
+    },
+  };
+}

package/packages/sdk/src/communicate/adapters/google-adk.ts

@@ -0,0 +1,139 @@
+import { Relay } from '../core.js';
+import { formatRelayInbox, formatRelayMessage, type Message, type MessageCallback } from '../types.js';
+
+type JsonObjectSchema = {
+  type: 'object';
+  properties: Record<string, Record<string, unknown>>;
+  required: string[];
+};
+
+type FunctionToolLike = {
+  name: string;
+  description: string;
+};
+
+type ToolUnionLike = FunctionToolLike;
+
+type RunnerLike = {
+  runAsync(params: {
+    userId: string;
+    sessionId: string;
+    newMessage: { role: string; parts: Array<{ text: string }> };
+  }): AsyncGenerator<unknown, void, undefined>;
+};
+
+type LlmAgentLike = {
+  name: string;
+  tools: ToolUnionLike[];
+};
+
+type RelayLike = {
+  send(to: string, text: string): Promise<void>;
+  post(channel: string, text: string): Promise<void>;
+  inbox(): Promise<Message[]>;
+  agents(): Promise<string[]>;
+  onMessage(callback: MessageCallback): () => void;
+};
+
+interface GoogleAdkRelayOptions {
+  /** Google ADK LlmAgent instance. */
+  agent: LlmAgentLike;
+  /** Optional Runner for routing incoming messages to the agent. */
+  runner?: RunnerLike;
+  /** User ID for runner sessions. Defaults to 'relay'. */
+  userId?: string;
+  /** Session ID for runner sessions. Defaults to 'relay-session'. */
+  sessionId?: string;
+}
+
+/**
+ * Create a FunctionTool-shaped object for Google ADK.
+ * We construct the tool objects duck-typed to avoid importing the actual
+ * FunctionTool class (which requires @google/genai at runtime).
+ */
+function createRelayFunctionTools(relay: RelayLike): FunctionToolLike[] {
+  // We dynamically import FunctionTool to create real ADK tool instances
+  // For now, we build tool-like objects that match the FunctionTool constructor shape
+  // and lazily construct them.
+  const toolDefs: Array<{
+    name: string;
+    description: string;
+    parameters: JsonObjectSchema;
+    execute: (input: Record<string, string>) => Promise<Record<string, unknown>>;
+  }> = [
+    {
+      name: 'relay_send',
+      description: 'Send a direct message to another relay agent.',
+      parameters: { type: 'object', properties: { to: { type: 'string' }, text: { type: 'string' } }, required: ['to', 'text'] },
+      async execute(input) {
+        await relay.send(input.to, input.text);
+        return { result: `Sent relay message to ${input.to}.` };
+      },
+    },
+    {
+      name: 'relay_inbox',
+      description: 'Drain and inspect newly received relay messages.',
+      parameters: { type: 'object', properties: {}, required: [] },
+      async execute() {
+        return { result: formatRelayInbox(await relay.inbox()) };
+      },
+    },
+    {
+      name: 'relay_post',
+      description: 'Post a message to a relay channel.',
+      parameters: { type: 'object', properties: { channel: { type: 'string' }, text: { type: 'string' } }, required: ['channel', 'text'] },
+      async execute(input) {
+        await relay.post(input.channel, input.text);
+        return { result: `Posted relay message to #${input.channel}.` };
+      },
+    },
+    {
+      name: 'relay_agents',
+      description: 'List currently online relay agents.',
+      parameters: { type: 'object', properties: {}, required: [] },
+      async execute() {
+        return { result: (await relay.agents()).join('\n') };
+      },
+    },
+  ];
+
+  return toolDefs;
+}
+
+/**
+ * Attach relay communication tools and message routing to a Google ADK agent.
+ * @param name - Agent name for relay registration.
+ * @param options - Google ADK agent and optional runner configuration.
+ * @param relay - Optional pre-configured Relay instance.
+ * @returns Object with the augmented agent, an unsubscribe function, and the relay tools added.
+ */
+export function onRelay(
+  name: string,
+  options: GoogleAdkRelayOptions,
+  relay: RelayLike = new Relay(name),
+): { agent: LlmAgentLike; tools: FunctionToolLike[]; unsubscribe: () => void } {
+  const { agent, runner, userId = 'relay', sessionId = 'relay-session' } = options;
+
+  const relayTools = createRelayFunctionTools(relay);
+
+  // Append relay tools to the agent's tool list
+  for (const tool of relayTools) {
+    agent.tools.push(tool as ToolUnionLike);
+  }
+
+  let unsubscribe: () => void = () => {};
+
+  if (runner) {
+    unsubscribe = relay.onMessage(async (message: Message) => {
+      const prompt = formatRelayMessage(message);
+      const content = { role: 'user', parts: [{ text: prompt }] };
+
+      // Drain the async generator to completion
+      for await (const _event of runner.runAsync({ userId, sessionId, newMessage: content })) {
+        // Events are consumed; the agent handles them internally.
+      }
+    });
+  }
+
+  return { agent, tools: relayTools, unsubscribe };
+}

package/packages/sdk/src/communicate/adapters/index.ts

@@ -0,0 +1,6 @@
+export { onRelay as onPiRelay } from './pi.js';
+export { onRelay as onClaudeRelay } from './claude-sdk.js';
+export { onRelay as onCrewAIRelay, onCrewRelay } from './crewai.js';
+export { onRelay as onOpenAIAgentsRelay } from './openai-agents.js';
+export { onRelay as onLangGraphRelay } from './langgraph.js';
+export { onRelay as onGoogleAdkRelay } from './google-adk.js';