agent-relay 3.2.2 → 3.2.4

package/packages/sdk/src/__tests__/communicate/adapters/e2e-pi.test.ts

@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import test from 'node:test';
+
+import { onRelay } from '../../../communicate/adapters/pi.js';
+import type { Message, MessageCallback } from '../../../communicate/types.js';
+
+const API_KEY = process.env.RELAY_API_KEY!;
+const BASE_URL = (process.env.RELAY_BASE_URL ?? 'https://api.relaycast.dev').replace(/\/+$/, '');
+const AGENT_NAME = `e2e-pi-${randomUUID().slice(0, 8)}`;
+
+/**
+ * Minimal relay implementation that speaks the real Relaycast API surface.
+ * The Pi adapter accepts any RelayLike — this lets us e2e-test the adapter
+ * independent of the SDK transport layer.
+ */
+class LiveRelay {
+  private agentToken?: string;
+  private agentId?: string;
+  private callbacks: MessageCallback[] = [];
+
+  constructor(private readonly name: string) {}
+
+  async register(): Promise<void> {
+    const res = await fetch(`${BASE_URL}/v1/agents`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${API_KEY}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ name: this.name, type: 'agent' }),
+    });
+    const body = await res.json() as any;
+    if (!body.ok) throw new Error(`Register failed: ${JSON.stringify(body)}`);
+    this.agentId = body.data.id;
+    this.agentToken = body.data.token;
+  }
+
+  async send(to: string, text: string): Promise<void> {
+    const res = await fetch(`${BASE_URL}/v1/dm`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${this.agentToken}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ to, text }),
+    });
+    const body = await res.json() as any;
+    if (!body.ok) throw new Error(`DM failed: ${JSON.stringify(body)}`);
+  }
+
+  async post(channel: string, text: string): Promise<void> {
+    const res = await fetch(`${BASE_URL}/v1/channels/${encodeURIComponent(channel)}/messages`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${this.agentToken}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ text }),
+    });
+    const body = await res.json() as any;
+    if (!body.ok) throw new Error(`Post failed: ${JSON.stringify(body)}`);
+  }
+
+  async inbox(): Promise<Message[]> {
+    const res = await fetch(`${BASE_URL}/v1/inbox`, {
+      headers: { authorization: `Bearer ${this.agentToken}` },
+    });
+    const body = await res.json() as any;
+    if (!body.ok) throw new Error(`Inbox failed: ${JSON.stringify(body)}`);
+    // Map the real inbox shape into Message[]
+    const msgs: Message[] = [];
+    for (const dm of body.data.unread_dms ?? []) {
+      msgs.push({ sender: dm.from ?? 'unknown', text: dm.text ?? '' });
+    }
+    return msgs;
+  }
+
+  async agents(): Promise<string[]> {
+    const res = await fetch(`${BASE_URL}/v1/agents`, {
+      headers: { authorization: `Bearer ${API_KEY}` },
+    });
+    const body = await res.json() as any;
+    if (!body.ok) throw new Error(`Agents failed: ${JSON.stringify(body)}`);
+    return (body.data as any[]).map((a) => a.name);
+  }
+
+  onMessage(callback: MessageCallback): () => void {
+    this.callbacks.push(callback);
+    return () => { this.callbacks = this.callbacks.filter((c) => c !== callback); };
+  }
+
+  async close(): Promise<void> {
+    if (!this.agentId) return;
+    // Best-effort unregister
+    try {
+      await fetch(`${BASE_URL}/v1/agents/${this.agentId}`, {
+        method: 'DELETE',
+        headers: { authorization: `Bearer ${API_KEY}` },
+      });
+    } catch { /* ignore */ }
+  }
+}
+
+test('Pi adapter e2e: relay tools work against live Relaycast', async () => {
+  const relay = new LiveRelay(AGENT_NAME);
+  await relay.register();
+
+  try {
+    const config = onRelay(AGENT_NAME, {}, relay);
+
+    const findTool = (name: string) => {
+      const tool = config.customTools.find((t: any) => t.name === name);
+      assert.ok(tool, `Tool ${name} not found`);
+      return tool;
+    };
+
+    const relayAgents = findTool('relay_agents');
+    const relaySend = findTool('relay_send');
+    const relayPost = findTool('relay_post');
+    const relayInbox = findTool('relay_inbox');
+
+    // 1. relay_agents — should include our freshly registered agent
+    const agentsResult = await relayAgents.execute('call-1', {});
+    const agentsText = agentsResult.content[0].text;
+    console.log('relay_agents:', agentsText.split('\n').length, 'agents');
+    assert.ok(agentsText.includes(AGENT_NAME), `Agent list must include ${AGENT_NAME}`);
+
+    // 2. relay_send — DM to self
+    const sendResult = await relaySend.execute('call-2', { to: AGENT_NAME, text: 'e2e self-ping' });
+    console.log('relay_send:', sendResult.content[0].text);
+    assert.ok(sendResult.content[0].text.includes('Sent relay message'));
+
+    // 3. relay_post — post to general channel
+    const postResult = await relayPost.execute('call-3', { channel: 'general', text: `e2e from ${AGENT_NAME}` });
+    console.log('relay_post:', postResult.content[0].text);
+    assert.ok(postResult.content[0].text.includes('Posted relay message'));
+
+    // 4. relay_inbox — drain inbox
+    const inboxResult = await relayInbox.execute('call-4', {});
+    console.log('relay_inbox:', inboxResult.content[0].text);
+    assert.ok(typeof inboxResult.content[0].text === 'string');
+
+    console.log('All Pi adapter e2e checks passed.');
+  } finally {
+    await relay.close();
+    console.log('Relay closed.');
+  }
+});

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

@@ -0,0 +1,200 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+const adkAdapterModulePath = '../../../communicate/adapters/google-adk.js';
+
+async function loadAdkAdapterModule(): Promise<any> {
+  return import(adkAdapterModulePath);
+}
+
+class FakeRelay {
+  private callbacks: Array<(message: any) => void | Promise<void>> = [];
+
+  async send(_to: string, _text: string): Promise<void> {}
+
+  async post(_channel: string, _text: string): Promise<void> {}
+
+  async inbox(): Promise<any[]> {
+    return [];
+  }
+
+  async agents(): Promise<string[]> {
+    return ['Lead', 'Impl-TS'];
+  }
+
+  onMessage(callback: (message: any) => void | Promise<void>): () => void {
+    this.callbacks.push(callback);
+    return () => {
+      this.callbacks = this.callbacks.filter((entry) => entry !== callback);
+    };
+  }
+
+  async emit(message: any): Promise<void> {
+    for (const callback of [...this.callbacks]) {
+      await callback(message);
+    }
+  }
+}
+
+function createMockAgent() {
+  return {
+    name: 'test-agent',
+    tools: [] as any[],
+  };
+}
+
+function createMockRunner() {
+  const calls: Array<{ userId: string; sessionId: string; newMessage: any }> = [];
+  return {
+    calls,
+    async *runAsync(params: { userId: string; sessionId: string; newMessage: any }) {
+      calls.push(params);
+      yield { type: 'done' };
+    },
+  };
+}
+
+test('Google ADK onRelay appends relay tools to agent.tools', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+
+  // Add an existing tool
+  agent.tools.push({ name: 'existing-tool', description: 'Existing tool' });
+
+  const result = onRelay('AdkTester', { agent }, relay);
+
+  const toolNames = result.agent.tools.map((tool: any) => tool.name);
+  assert.deepEqual(toolNames, [
+    'existing-tool',
+    'relay_send',
+    'relay_inbox',
+    'relay_post',
+    'relay_agents',
+  ]);
+});
+
+test('Google ADK onRelay tools have correct structure', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+
+  const result = onRelay('AdkTester', { agent }, relay);
+
+  for (const toolName of ['relay_send', 'relay_inbox', 'relay_post', 'relay_agents']) {
+    const tool = result.tools.find((entry: any) => entry.name === toolName);
+    assert.ok(tool, `Expected ${toolName} to be registered`);
+    assert.equal(typeof tool.execute, 'function');
+    assert.ok(tool.parameters, `Expected ${toolName} to have parameters`);
+    assert.ok(tool.description, `Expected ${toolName} to have a description`);
+  }
+});
+
+test('Google ADK relay_send tool calls relay.send', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const sendCalls: Array<{ to: string; text: string }> = [];
+  relay.send = async (to: string, text: string) => {
+    sendCalls.push({ to, text });
+  };
+  const agent = createMockAgent();
+
+  const result = onRelay('AdkTester', { agent }, relay);
+  const sendTool = result.tools.find((t: any) => t.name === 'relay_send');
+
+  const output = await sendTool.execute({ to: 'Lead', text: 'Hello' });
+  assert.equal(sendCalls.length, 1);
+  assert.deepEqual(sendCalls[0], { to: 'Lead', text: 'Hello' });
+  assert.ok(output.result.includes('Lead'));
+});
+
+test('Google ADK relay_inbox tool returns formatted inbox', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+
+  const result = onRelay('AdkTester', { agent }, relay);
+  const inboxTool = result.tools.find((t: any) => t.name === 'relay_inbox');
+
+  const output = await inboxTool.execute({});
+  assert.equal(output.result, 'No new relay messages.');
+});
+
+test('Google ADK relay_agents tool returns agent list', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+
+  const result = onRelay('AdkTester', { agent }, relay);
+  const agentsTool = result.tools.find((t: any) => t.name === 'relay_agents');
+
+  const output = await agentsTool.execute({});
+  assert.equal(output.result, 'Lead\nImpl-TS');
+});
+
+test('Google ADK onRelay routes incoming messages to the runner', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+  const runner = createMockRunner();
+
+  onRelay('AdkTester', { agent, runner }, relay);
+
+  await relay.emit({
+    sender: 'Lead',
+    text: 'Need status update',
+    messageId: 'msg-1',
+  });
+
+  assert.equal(runner.calls.length, 1);
+  assert.equal(runner.calls[0].userId, 'relay');
+  assert.equal(runner.calls[0].sessionId, 'relay-session');
+  assert.ok(runner.calls[0].newMessage.parts[0].text.includes('Lead'));
+  assert.ok(runner.calls[0].newMessage.parts[0].text.includes('Need status update'));
+});
+
+test('Google ADK onRelay uses custom userId and sessionId', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+  const runner = createMockRunner();
+
+  onRelay(
+    'AdkTester',
+    { agent, runner, userId: 'custom-user', sessionId: 'custom-session' },
+    relay,
+  );
+
+  await relay.emit({ sender: 'Peer', text: 'ping', messageId: 'msg-2' });
+
+  assert.equal(runner.calls[0].userId, 'custom-user');
+  assert.equal(runner.calls[0].sessionId, 'custom-session');
+});
+
+test('Google ADK onRelay unsubscribe stops message routing', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+  const runner = createMockRunner();
+
+  const result = onRelay('AdkTester', { agent, runner }, relay);
+
+  // Unsubscribe from message routing
+  result.unsubscribe();
+
+  await relay.emit({ sender: 'Lead', text: 'Should not arrive', messageId: 'msg-3' });
+
+  assert.equal(runner.calls.length, 0);
+});
+
+test('Google ADK onRelay without runner does not subscribe to messages', async () => {
+  const { onRelay } = await loadAdkAdapterModule();
+  const relay = new FakeRelay();
+  const agent = createMockAgent();
+
+  const result = onRelay('AdkTester', { agent }, relay);
+
+  // unsubscribe should be a no-op
+  assert.equal(typeof result.unsubscribe, 'function');
+  result.unsubscribe(); // should not throw
+});

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

@@ -0,0 +1,162 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+const langgraphAdapterModulePath = '../../../communicate/adapters/langgraph.js';
+
+async function loadLangGraphAdapterModule(): Promise<any> {
+  return import(langgraphAdapterModulePath);
+}
+
+class FakeRelay {
+  private callbacks: Array<(message: any) => void | Promise<void>> = [];
+
+  async send(_to: string, _text: string): Promise<void> {}
+
+  async post(_channel: string, _text: string): Promise<void> {}
+
+  async inbox(): Promise<any[]> {
+    return [];
+  }
+
+  async agents(): Promise<string[]> {
+    return ['Lead', 'Impl-TS'];
+  }
+
+  onMessage(callback: (message: any) => void | Promise<void>): () => void {
+    this.callbacks.push(callback);
+    return () => {
+      this.callbacks = this.callbacks.filter((entry) => entry !== callback);
+    };
+  }
+
+  async emit(message: any): Promise<void> {
+    for (const callback of [...this.callbacks]) {
+      await callback(message);
+    }
+  }
+}
+
+function createFakeGraph() {
+  return {
+    nodes: {},
+    invokeCalls: [] as Array<{ input: Record<string, unknown>; config?: Record<string, unknown> }>,
+    async invoke(input: Record<string, unknown>, config?: Record<string, unknown>) {
+      this.invokeCalls.push({ input, config });
+      return { messages: [] };
+    },
+  };
+}
+
+test('LangGraph onRelay returns relay tools', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const graph = createFakeGraph();
+
+  const result = onRelay(graph, relay);
+
+  const toolNames = result.tools.map((tool: any) => tool.name);
+  assert.deepEqual(toolNames, ['relay_send', 'relay_inbox', 'relay_post', 'relay_agents']);
+
+  for (const tool of result.tools) {
+    assert.equal(typeof tool.invoke, 'function');
+    assert.ok(tool.schema);
+    assert.ok(tool.description);
+  }
+});
+
+test('LangGraph relay_send tool calls relay.send', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const sendCalls: Array<{ to: string; text: string }> = [];
+  relay.send = async (to: string, text: string) => {
+    sendCalls.push({ to, text });
+  };
+  const graph = createFakeGraph();
+
+  const result = onRelay(graph, relay);
+  const sendTool = result.tools.find((t: any) => t.name === 'relay_send');
+
+  const output = await sendTool.invoke({ to: 'Lead', text: 'Hello' });
+  assert.equal(output, 'Sent relay message to Lead.');
+  assert.deepEqual(sendCalls, [{ to: 'Lead', text: 'Hello' }]);
+});
+
+test('LangGraph relay_inbox tool returns formatted inbox', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const graph = createFakeGraph();
+
+  const result = onRelay(graph, relay);
+  const inboxTool = result.tools.find((t: any) => t.name === 'relay_inbox');
+
+  const output = await inboxTool.invoke({});
+  assert.equal(output, 'No new relay messages.');
+});
+
+test('LangGraph relay_post tool calls relay.post', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const postCalls: Array<{ channel: string; text: string }> = [];
+  relay.post = async (channel: string, text: string) => {
+    postCalls.push({ channel, text });
+  };
+  const graph = createFakeGraph();
+
+  const result = onRelay(graph, relay);
+  const postTool = result.tools.find((t: any) => t.name === 'relay_post');
+
+  const output = await postTool.invoke({ channel: 'general', text: 'Update' });
+  assert.equal(output, 'Posted relay message to #general.');
+  assert.deepEqual(postCalls, [{ channel: 'general', text: 'Update' }]);
+});
+
+test('LangGraph relay_agents tool lists agents', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const graph = createFakeGraph();
+
+  const result = onRelay(graph, relay);
+  const agentsTool = result.tools.find((t: any) => t.name === 'relay_agents');
+
+  const output = await agentsTool.invoke({});
+  assert.equal(output, 'Lead\nImpl-TS');
+});
+
+test('LangGraph onRelay routes incoming messages via graph.invoke', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const graph = createFakeGraph();
+
+  onRelay(graph, relay);
+
+  await relay.emit({
+    sender: 'Lead',
+    text: 'Need status update',
+    messageId: 'msg-1',
+  });
+
+  assert.equal(graph.invokeCalls.length, 1);
+  const call = graph.invokeCalls[0];
+  assert.ok(Array.isArray(call.input.messages));
+  const msg = (call.input.messages as any[])[0];
+  assert.equal(msg.role, 'user');
+  assert.match(msg.content, /Lead/);
+  assert.match(msg.content, /Need status update/);
+});
+
+test('LangGraph onRelay unsubscribe stops message routing', async () => {
+  const { onRelay } = await loadLangGraphAdapterModule();
+  const relay = new FakeRelay();
+  const graph = createFakeGraph();
+
+  const result = onRelay(graph, relay);
+  result.unsubscribe();
+
+  await relay.emit({
+    sender: 'Lead',
+    text: 'Should not arrive',
+    messageId: 'msg-2',
+  });
+
+  assert.equal(graph.invokeCalls.length, 0);
+});

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

@@ -0,0 +1,166 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+const adapterModulePath = '../../../communicate/adapters/openai-agents.js';
+
+async function loadModule(): Promise<any> {
+  return import(adapterModulePath);
+}
+
+class FakeRelay {
+  private callbacks: Array<(message: any) => void | Promise<void>> = [];
+
+  async send(_to: string, _text: string): Promise<void> {}
+
+  async post(_channel: string, _text: string): Promise<void> {}
+
+  async inbox(): Promise<any[]> {
+    return [];
+  }
+
+  async agents(): Promise<string[]> {
+    return ['Lead', 'Impl-TS'];
+  }
+
+  onMessage(callback: (message: any) => void | Promise<void>): () => void {
+    this.callbacks.push(callback);
+    return () => {
+      this.callbacks = this.callbacks.filter((entry) => entry !== callback);
+    };
+  }
+
+  async emit(message: any): Promise<void> {
+    for (const callback of [...this.callbacks]) {
+      await callback(message);
+    }
+  }
+}
+
+function createAgent(instructions: string | ((...args: unknown[]) => string | Promise<string>) = 'You are a helpful agent.') {
+  return {
+    name: 'TestAgent',
+    instructions,
+    tools: [] as any[],
+  };
+}
+
+test('onRelay appends relay tools to agent.tools', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const agent = createAgent();
+  agent.tools.push({ type: 'function', name: 'existing-tool' });
+
+  const result = onRelay(agent, relay);
+
+  const toolNames = result.agent.tools.map((t: any) => t.name);
+  assert.deepEqual(toolNames, [
+    'existing-tool',
+    'relay_send',
+    'relay_inbox',
+    'relay_post',
+    'relay_agents',
+  ]);
+
+  for (const toolName of ['relay_send', 'relay_inbox', 'relay_post', 'relay_agents']) {
+    const tool = result.agent.tools.find((t: any) => t.name === toolName);
+    assert.ok(tool, `Expected ${toolName} to be registered`);
+    assert.equal(tool.type, 'function');
+    assert.equal(typeof tool.invoke, 'function');
+    assert.ok(tool.parameters);
+    assert.equal(tool.parameters.type, 'object');
+  }
+});
+
+test('relay tools invoke correctly', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const agent = createAgent();
+
+  const result = onRelay(agent, relay);
+
+  const agentsTool = result.agent.tools.find((t: any) => t.name === 'relay_agents');
+  const output = await agentsTool.invoke(null, '{}');
+  assert.equal(output, 'Lead\nImpl-TS');
+
+  const inboxTool = result.agent.tools.find((t: any) => t.name === 'relay_inbox');
+  const inboxOutput = await inboxTool.invoke(null, '{}');
+  assert.equal(inboxOutput, 'No new relay messages.');
+});
+
+test('incoming relay messages are appended to instructions', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const agent = createAgent('Base instructions.');
+
+  onRelay(agent, relay);
+
+  await relay.emit({ sender: 'Lead', text: 'Need status', messageId: 'msg-1' });
+
+  const instructions = await (agent.instructions as (...args: unknown[]) => Promise<string>)();
+  assert.match(instructions, /Base instructions\./);
+  assert.match(instructions, /Lead/);
+  assert.match(instructions, /Need status/);
+});
+
+test('pending messages are drained after instructions call', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const agent = createAgent('Base.');
+
+  onRelay(agent, relay);
+
+  await relay.emit({ sender: 'Worker', text: 'Done', messageId: 'msg-2' });
+
+  const first = await (agent.instructions as (...args: unknown[]) => Promise<string>)();
+  assert.match(first, /Worker/);
+
+  const second = await (agent.instructions as (...args: unknown[]) => Promise<string>)();
+  assert.ok(!second.includes('Worker'), 'Messages should be drained after first read');
+  assert.equal(second, 'Base.');
+});
+
+test('instructions function is preserved when original is a function', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const agent = {
+    name: 'FnAgent',
+    instructions: async () => 'Dynamic instructions',
+    tools: [] as any[],
+  };
+
+  onRelay(agent, relay);
+
+  const output = await agent.instructions();
+  assert.equal(output, 'Dynamic instructions');
+});
+
+test('cleanup restores original instructions and removes relay tools', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const originalInstructions = 'Original.';
+  const agent = createAgent(originalInstructions);
+
+  const result = onRelay(agent, relay);
+
+  assert.equal(result.agent.tools.length, 4);
+  assert.equal(typeof result.agent.instructions, 'function');
+
+  result.cleanup();
+
+  assert.equal(result.agent.tools.length, 0);
+  assert.equal(result.agent.instructions, originalInstructions);
+});
+
+test('cleanup stops message routing', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const agent = createAgent('Base.');
+
+  const result = onRelay(agent, relay);
+  result.cleanup();
+
+  await relay.emit({ sender: 'Late', text: 'Should not appear', messageId: 'msg-3' });
+
+  // instructions was restored to a string, so no messages appended
+  assert.equal(result.agent.instructions, 'Base.');
+});