agent-relay 3.2.2 → 3.2.4

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

@@ -0,0 +1,112 @@
+import { Relay } from '../core.js';
+import { formatRelayInbox, formatRelayMessage, type Message, type MessageCallback } from '../types.js';
+
+/** Minimal shape of a LangGraph CompiledStateGraph for relay integration. */
+type CompiledGraphLike = {
+  invoke(input: Record<string, unknown>, config?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  nodes: Record<string, unknown>;
+};
+
+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;
+};
+
+/** A tool definition compatible with LangGraph ToolNode. */
+export interface RelayToolDef {
+  name: string;
+  description: string;
+  schema: Record<string, unknown>;
+  invoke(input: Record<string, string>): Promise<string>;
+}
+
+function createRelayTools(relay: RelayLike): RelayToolDef[] {
+  return [
+    {
+      name: 'relay_send',
+      description: 'Send a direct message to another relay agent.',
+      schema: {
+        type: 'object',
+        properties: {
+          to: { type: 'string', description: 'Recipient agent name' },
+          text: { type: 'string', description: 'Message text' },
+        },
+        required: ['to', 'text'],
+      },
+      async invoke(input: Record<string, string>) {
+        await relay.send(input.to, input.text);
+        return `Sent relay message to ${input.to}.`;
+      },
+    },
+    {
+      name: 'relay_inbox',
+      description: 'Drain and inspect newly received relay messages.',
+      schema: { type: 'object', properties: {}, required: [] },
+      async invoke() {
+        return formatRelayInbox(await relay.inbox());
+      },
+    },
+    {
+      name: 'relay_post',
+      description: 'Post a message to a relay channel.',
+      schema: {
+        type: 'object',
+        properties: {
+          channel: { type: 'string', description: 'Channel name' },
+          text: { type: 'string', description: 'Message text' },
+        },
+        required: ['channel', 'text'],
+      },
+      async invoke(input: Record<string, string>) {
+        await relay.post(input.channel, input.text);
+        return `Posted relay message to #${input.channel}.`;
+      },
+    },
+    {
+      name: 'relay_agents',
+      description: 'List currently online relay agents.',
+      schema: { type: 'object', properties: {}, required: [] },
+      async invoke() {
+        return (await relay.agents()).join('\n');
+      },
+    },
+  ];
+}
+
+export interface LangGraphRelayResult {
+  /** Relay tool definitions to pass to a LangGraph ToolNode. */
+  tools: RelayToolDef[];
+  /** Unsubscribe from incoming relay messages. */
+  unsubscribe: () => void;
+}
+
+/**
+ * Attach relay communication tools and message routing to a LangGraph compiled graph.
+ *
+ * Tools are returned as objects compatible with LangGraph's ToolNode. Incoming
+ * relay messages are routed into the graph via `graph.invoke()` with a
+ * `messages` state update.
+ *
+ * @param graph - A compiled LangGraph state graph.
+ * @param relayOrName - Optional pre-configured Relay instance or agent name string (defaults to 'langgraph').
+ * @returns Relay tools and an unsubscribe handle.
+ */
+export function onRelay(
+  graph: CompiledGraphLike,
+  relayOrName?: RelayLike | string,
+): LangGraphRelayResult {
+  const r: RelayLike = typeof relayOrName === 'string'
+    ? new Relay(relayOrName) as unknown as RelayLike
+    : relayOrName ?? (new Relay('langgraph') as unknown as RelayLike);
+  const tools = createRelayTools(r);
+
+  const unsubscribe = r.onMessage(async (message) => {
+    const prompt = formatRelayMessage(message);
+    await graph.invoke({ messages: [{ role: 'user', content: prompt }] });
+  });
+
+  return { tools, unsubscribe };
+}

package/packages/sdk/src/communicate/adapters/openai-agents.ts

@@ -0,0 +1,113 @@
+import { Relay } from '../core.js';
+import { formatRelayInbox, formatRelayMessage, type Message, type MessageCallback } from '../types.js';
+
+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;
+};
+
+type JsonObjectSchema = {
+  type: 'object';
+  properties: Record<string, Record<string, unknown>>;
+  required: string[];
+  additionalProperties: boolean;
+};
+
+type FunctionToolLike = {
+  type: 'function';
+  name: string;
+  description: string;
+  parameters: JsonObjectSchema;
+  strict: boolean;
+  invoke: (runContext: unknown, input: string) => Promise<string>;
+  needsApproval: false;
+  isEnabled: true;
+};
+
+type AgentLike = {
+  name: string;
+  instructions: string | ((...args: unknown[]) => string | Promise<string>);
+  tools: unknown[];
+};
+
+function schema(props: Record<string, Record<string, unknown>>, required: string[]): JsonObjectSchema {
+  return { type: 'object', properties: props, required, additionalProperties: false };
+}
+
+function createRelayTools(relay: RelayLike): FunctionToolLike[] {
+  const defs: Array<[string, string, JsonObjectSchema, (p: Record<string, string>) => Promise<string>]> = [
+    ['relay_send', 'Send a direct message to another relay agent.',
+      schema({ to: { type: 'string' }, text: { type: 'string' } }, ['to', 'text']),
+      async (p) => { await relay.send(p.to, p.text); return `Sent relay message to ${p.to}.`; }],
+    ['relay_inbox', 'Drain and inspect newly received relay messages.',
+      schema({}, []),
+      async () => formatRelayInbox(await relay.inbox())],
+    ['relay_post', 'Post a message to a relay channel.',
+      schema({ channel: { type: 'string' }, text: { type: 'string' } }, ['channel', 'text']),
+      async (p) => { await relay.post(p.channel, p.text); return `Posted relay message to #${p.channel}.`; }],
+    ['relay_agents', 'List currently online relay agents.',
+      schema({}, []),
+      async () => (await relay.agents()).join('\n')],
+  ];
+
+  return defs.map(([name, description, parameters, run]) => ({
+    type: 'function' as const,
+    name,
+    description,
+    parameters,
+    strict: false,
+    needsApproval: false as const,
+    isEnabled: true as const,
+    async invoke(_runContext: unknown, input: string): Promise<string> {
+      const params = input ? JSON.parse(input) : {};
+      return run(params);
+    },
+  }));
+}
+
+/**
+ * Attach relay communication tools and message routing to an OpenAI Agent.
+ * @param agent - OpenAI Agent instance to augment with relay tools.
+ * @param relay - Optional pre-configured Relay instance.
+ * @returns Object with the augmented agent and a cleanup function.
+ */
+export function onRelay<TAgent extends AgentLike>(
+  agent: TAgent,
+  relay: RelayLike = new Relay(agent.name),
+): { agent: TAgent; cleanup: () => void } {
+  const relayTools = createRelayTools(relay);
+  agent.tools = [...agent.tools, ...relayTools];
+
+  const pendingMessages: string[] = [];
+  const originalInstructions = agent.instructions;
+
+  const unsubscribe = relay.onMessage(async (message) => {
+    pendingMessages.push(formatRelayMessage(message));
+  });
+
+  agent.instructions = async (...args: unknown[]): Promise<string> => {
+    let base: string;
+    if (typeof originalInstructions === 'function') {
+      base = await originalInstructions(...args);
+    } else {
+      base = originalInstructions ?? '';
+    }
+
+    if (pendingMessages.length > 0) {
+      const msgs = pendingMessages.splice(0, pendingMessages.length);
+      return `${base}\n\n--- Relay Messages ---\n${msgs.join('\n')}`;
+    }
+    return base;
+  };
+
+  const cleanup = (): void => {
+    unsubscribe();
+    agent.instructions = originalInstructions;
+    agent.tools = agent.tools.filter((t) => !relayTools.includes(t as FunctionToolLike));
+  };
+
+  return { agent, cleanup };
+}

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

@@ -0,0 +1,105 @@
+import { Type } from '@sinclair/typebox';
+
+import { Relay } from '../core.js';
+import { formatRelayInbox, formatRelayMessage, type Message, type MessageCallback } from '../types.js';
+
+type ToolResult = {
+  content: Array<{ type: 'text'; text: string }>;
+  details: Record<string, unknown>;
+};
+
+type RelayTool = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (
+    toolCallId: string,
+    params: any,
+    signal?: AbortSignal,
+    onUpdate?: unknown
+  ) => Promise<ToolResult>;
+};
+
+type PiSessionLike = {
+  isStreaming: boolean;
+  steer(text: string): Promise<void>;
+  followUp(text: string): Promise<void>;
+};
+
+type PiConfigLike = {
+  customTools?: RelayTool[];
+  onSessionCreated?: (session: PiSessionLike) => void | Promise<void>;
+};
+
+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;
+};
+
+const txt = (text: string): ToolResult => ({ content: [{ type: 'text', text }], details: {} });
+
+function createRelayTools(relay: RelayLike): RelayTool[] {
+  const toolDefs: Array<[string, string, unknown, (p: Record<string, string>) => Promise<string>]> = [
+    ['relay_send', 'Send a direct message to another relay agent.',
+      Type.Object({ to: Type.String(), text: Type.String() }),
+      async (p) => { await relay.send(p.to, p.text); return `Sent relay message to ${p.to}.`; }],
+    ['relay_inbox', 'Drain and inspect newly received relay messages.',
+      Type.Object({}),
+      async () => formatRelayInbox(await relay.inbox())],
+    ['relay_post', 'Post a message to a relay channel.',
+      Type.Object({ channel: Type.String(), text: Type.String() }),
+      async (p) => { await relay.post(p.channel, p.text); return `Posted relay message to #${p.channel}.`; }],
+    ['relay_agents', 'List currently online relay agents.',
+      Type.Object({}),
+      async () => (await relay.agents()).join('\n')],
+  ];
+  return toolDefs.map(([name, description, parameters, run]) => ({
+    name, label: name.replace('_', ' '), description, parameters,
+    async execute(_id: string, params: Record<string, string>) { return txt(await run(params)); },
+  }));
+}
+
+/**
+ * Attach relay communication tools and message routing to a Pi agent config.
+ * @param name - Agent name for relay registration.
+ * @param config - Pi agent session config to augment.
+ * @param relay - Optional pre-configured Relay instance.
+ * @returns Augmented config with relay tools and session hook.
+ */
+export function onRelay<TConfig extends PiConfigLike>(
+  name: string,
+  config: TConfig,
+  relay: RelayLike = new Relay(name)
+): TConfig & { customTools: RelayTool[]; onSessionCreated: (session: PiSessionLike) => Promise<void>; cleanup: () => void } {
+  const customTools = [...(config.customTools ?? []), ...createRelayTools(relay)];
+  const originalOnSessionCreated = config.onSessionCreated;
+  let unsubscribe: (() => void) | undefined;
+
+  return {
+    ...config,
+    customTools,
+    async onSessionCreated(session: PiSessionLike): Promise<void> {
+      if (originalOnSessionCreated) {
+        await originalOnSessionCreated(session);
+      }
+
+      unsubscribe?.();
+      unsubscribe = relay.onMessage(async (message) => {
+        const prompt = formatRelayMessage(message);
+        if (session.isStreaming) {
+          await session.steer(prompt);
+          return;
+        }
+        await session.followUp(prompt);
+      });
+    },
+    cleanup() {
+      unsubscribe?.();
+      unsubscribe = undefined;
+    },
+  };
+}

package/packages/sdk/src/communicate/core.ts

@@ -0,0 +1,157 @@
+import { RelayTransport } from './transport.js';
+import {
+  type Message,
+  type MessageCallback,
+  type RelayConfig,
+  resolveRelayConfig,
+} from './types.js';
+
+const MAX_PENDING_MESSAGES = 10_000;
+
+/**
+ * Core relay client for inter-agent communication.
+ *
+ * Lazily connects on first API call. Buffers incoming WebSocket messages
+ * for {@link inbox} when no callbacks are registered.
+ */
+export class Relay {
+  readonly agentName: string;
+  readonly config;
+  readonly transport: RelayTransport;
+
+  private pending: Message[] = [];
+  private callbacks = new Set<MessageCallback>();
+  private connectPromise?: Promise<void>;
+  private connected = false;
+  private readonly exitHandler?: () => void;
+
+  constructor(agentName: string, config: RelayConfig = {}) {
+    this.agentName = agentName;
+    this.config = resolveRelayConfig(config);
+    this.transport = new RelayTransport(agentName, this.config);
+    this.transport.onWsMessage((message) => this.handleTransportMessage(message));
+
+    if (this.config.autoCleanup) {
+      this.exitHandler = () => {
+        void this.close();
+      };
+      process.once('beforeExit', this.exitHandler);
+      process.once('SIGTERM', this.exitHandler);
+      process.once('SIGINT', this.exitHandler);
+    }
+  }
+
+  /**
+   * Send a direct message to another agent.
+   * @param to - Recipient agent name.
+   * @param text - Message content.
+   */
+  async send(to: string, text: string): Promise<void> {
+    await this.ensureConnected();
+    await this.transport.sendDm(to, text);
+  }
+
+  /**
+   * Post a message to a channel.
+   * @param channel - Target channel name.
+   * @param text - Message content.
+   */
+  async post(channel: string, text: string): Promise<void> {
+    await this.ensureConnected();
+    await this.transport.postMessage(channel, text);
+  }
+
+  /**
+   * Reply to a specific message in a thread.
+   * @param messageId - ID of the message to reply to.
+   * @param text - Reply content.
+   */
+  async reply(messageId: string, text: string): Promise<void> {
+    await this.ensureConnected();
+    await this.transport.reply(messageId, text);
+  }
+
+  /**
+   * Drain and return all buffered messages, clearing the buffer.
+   * @returns Array of buffered messages.
+   */
+  async inbox(): Promise<Message[]> {
+    await this.ensureConnected();
+    const messages = [...this.pending];
+    this.pending = [];
+    return messages;
+  }
+
+  /**
+   * Register a callback for incoming messages.
+   * @param callback - Invoked for each received message.
+   * @returns Unsubscribe function.
+   */
+  onMessage(callback: MessageCallback): () => void {
+    this.callbacks.add(callback);
+    void this.ensureConnected();
+
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+
+  /**
+   * List currently online agents.
+   * @returns Array of agent names.
+   */
+  async agents(): Promise<string[]> {
+    await this.ensureConnected();
+    return this.transport.listAgents();
+  }
+
+  /** Unregister the agent, close the WebSocket, and clean up. */
+  async close(): Promise<void> {
+    if (this.exitHandler) {
+      process.removeListener('beforeExit', this.exitHandler);
+      process.removeListener('SIGTERM', this.exitHandler);
+      process.removeListener('SIGINT', this.exitHandler);
+    }
+
+    this.connected = false;
+    this.connectPromise = undefined;
+    await this.transport.disconnect();
+  }
+
+  private async ensureConnected(): Promise<void> {
+    if (this.connected) {
+      return;
+    }
+
+    if (!this.connectPromise) {
+      this.connectPromise = this.transport.connect().then(
+        () => {
+          this.connected = true;
+        },
+        (err) => {
+          // Clear cached promise so the next call can retry
+          this.connectPromise = undefined;
+          throw err;
+        },
+      );
+    }
+
+    await this.connectPromise;
+  }
+
+  private async handleTransportMessage(message: Message): Promise<void> {
+    // Always buffer the message (spec: "both" case — callbacks AND inbox)
+    if (this.pending.length >= MAX_PENDING_MESSAGES) {
+      this.pending.shift();
+      process.emitWarning(
+        'Relay pending buffer exceeded 10,000 messages; dropping oldest message.',
+        'RelayWarning'
+      );
+    }
+    this.pending.push(message);
+
+    for (const callback of [...this.callbacks]) {
+      await callback(message);
+    }
+  }
+}

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

@@ -0,0 +1,3 @@
+export * from './types.js';
+export { Relay } from './core.js';
+export { onPiRelay, onClaudeRelay } from './adapters/index.js';