agent-relay 3.2.14 → 3.2.16

package/packages/sdk/src/client.ts

@@ -20,6 +20,7 @@ import {
   type ProtocolEnvelope,
   type ProtocolError,
   type RestartPolicy,
+  type MessageInjectionMode,
 } from './protocol.js';
 
 export interface AgentRelayClientOptions {
@@ -99,6 +100,7 @@ export interface SendMessageInput {
   workspaceAlias?: string;
   priority?: number;
   data?: Record<string, unknown>;
+  mode?: MessageInjectionMode;
 }
 
 export interface ListAgent {
@@ -369,6 +371,16 @@ export class AgentRelayClient {
     return this.requestOk<{ name: string; bytes_written: number }>('send_input', { name, data });
   }
 
+  async subscribeChannels(name: string, channels: string[]): Promise<void> {
+    await this.start();
+    await this.requestOk<void>('subscribe_channels', { name, channels });
+  }
+
+  async unsubscribeChannels(name: string, channels: string[]): Promise<void> {
+    await this.start();
+    await this.requestOk<void>('unsubscribe_channels', { name, channels });
+  }
+
   async resizePty(
     name: string,
     rows: number,
@@ -423,6 +435,7 @@ export class AgentRelayClient {
         workspace_alias: input.workspaceAlias,
         priority: input.priority,
         data: input.data,
+        mode: input.mode,
       });
     } catch (error) {
       if (error instanceof AgentRelayProtocolError && error.code === 'unsupported_operation') {
@@ -1154,6 +1167,7 @@ export class HttpAgentRelayClient {
         workspaceAlias: input.workspaceAlias,
         priority: input.priority,
         data: input.data,
+        mode: input.mode,
       }),
     });
   }
@@ -1176,6 +1190,20 @@ export class HttpAgentRelayClient {
     return { name: typeof payload?.name === 'string' ? payload.name : name };
   }
 
+  async subscribeChannels(_name: string, _channels: string[]): Promise<void> {
+    throw new Error(
+      'subscribeChannels is only available via the broker protocol (BrokerAgentRelayClient). ' +
+      'The HTTP API does not support dynamic channel subscription.'
+    );
+  }
+
+  async unsubscribeChannels(_name: string, _channels: string[]): Promise<void> {
+    throw new Error(
+      'unsubscribeChannels is only available via the broker protocol (BrokerAgentRelayClient). ' +
+      'The HTTP API does not support dynamic channel unsubscription.'
+    );
+  }
+
   async setModel(
     name: string,
     model: string,

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

@@ -1,7 +1,2 @@
 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';
-export { onRelay as onAiSdkRelay } from './ai-sdk.js';

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

@@ -74,7 +74,7 @@ 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 } {
+): TConfig & { customTools: RelayTool[]; onSessionCreated: (session: PiSessionLike) => Promise<void> } {
   const customTools = [...(config.customTools ?? []), ...createRelayTools(relay)];
   const originalOnSessionCreated = config.onSessionCreated;
   let unsubscribe: (() => void) | undefined;
@@ -97,9 +97,5 @@ export function onRelay<TConfig extends PiConfigLike>(
         await session.followUp(prompt);
       });
     },
-    cleanup() {
-      unsubscribe?.();
-      unsubscribe = undefined;
-    },
   };
 }

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

@@ -124,16 +124,12 @@ export class Relay {
     }
 
     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;
-        },
-      );
+      this.connectPromise = this.transport.connect().then(() => {
+        this.connected = true;
+      }).catch((error) => {
+        this.connectPromise = undefined;
+        throw error;
+      });
     }
 
     await this.connectPromise;

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

@@ -1,3 +1,59 @@
 export * from './types.js';
 export { Relay } from './core.js';
-export { onPiRelay, onClaudeRelay, onAiSdkRelay } from './adapters/index.js';
+export { onPiRelay, onClaudeRelay } from './adapters/index.js';
+
+import { onRelay as onPiRelay } from './adapters/pi.js';
+import { onRelay as onClaudeRelay } from './adapters/claude-sdk.js';
+import { Relay } from './core.js';
+
+/**
+ * Auto-detect the agent framework and apply the appropriate relay adapter.
+ *
+ * Requires a `framework` discriminator to avoid ambiguous detection.
+ * If you know which framework you're using, prefer importing the
+ * adapter directly: `onPiRelay` or `onClaudeRelay`.
+ *
+ * @param nameOrAgent - Agent name (string) or the agent/config object directly.
+ * @param configOrOptions - Config/options object when first arg is a name.
+ * @param maybeRelay - Optional pre-configured Relay instance.
+ * @returns The augmented agent config or options.
+ */
+export function onRelay(
+  nameOrAgent: string | Record<string, unknown>,
+  configOrOptions?: Record<string, unknown>,
+  maybeRelay?: Relay
+): Record<string, unknown> {
+  const isStringName = typeof nameOrAgent === 'string';
+  const name = isStringName ? nameOrAgent : ((nameOrAgent as Record<string, unknown>).name as string) || 'Agent';
+  const target: unknown = isStringName ? configOrOptions : nameOrAgent;
+  const relay = (isStringName ? maybeRelay : configOrOptions) as Relay | undefined;
+
+  const relayInstance = relay || new Relay(name);
+
+  if (typeof target !== 'object' || target === null) {
+    throw new Error(
+      `onRelay() received a non-object target for ${name}. ` +
+      'Pass the framework config/options object, or use onPiRelay / onClaudeRelay directly.'
+    );
+  }
+
+  const obj = target as Record<string, unknown>;
+
+  // Detect Pi: has customTools or Agent constructor
+  if ('customTools' in obj || obj.constructor?.name === 'Agent') {
+    return onPiRelay(name, target as Parameters<typeof onPiRelay>[1], relayInstance);
+  }
+
+  // Detect Claude SDK: has mcpServers or hooks, or is a plain empty options object
+  if ('mcpServers' in obj || 'hooks' in obj || Object.keys(obj).length === 0) {
+    return onClaudeRelay(name, target as Parameters<typeof onClaudeRelay>[1], relayInstance);
+  }
+
+  throw new Error(
+    `onRelay() could not auto-detect framework for ${name}. ` +
+    'Use the framework-specific adapter instead: onPiRelay or onClaudeRelay.'
+  );
+}
+
+/** Alias for onRelay — spec uses both names */
+export const withRelay = onRelay;

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

@@ -83,113 +83,70 @@ export class RelayTransport {
       return this.agentId;
     }
 
-    let payload: JsonObject;
-    try {
-      payload = await this.sendHttp<JsonObject>(
-        'POST',
-        '/v1/agents',
-        { name: this.agentName, type: 'agent' },
-      );
-    } catch (error) {
-      if (error instanceof RelayConnectionError && error.statusCode === 409) {
-        const agentPayload = await this.sendHttp<JsonObject>(
-          'GET',
-          `/v1/agents/${encodeURIComponent(this.agentName)}`,
-        );
-        const agentData = (agentPayload as any).data ?? agentPayload;
-        this.agentId = String(agentData.id);
-
-        const rotatePayload = await this.sendHttp<JsonObject>(
-          'POST',
-          `/v1/agents/${encodeURIComponent(this.agentName)}/rotate-token`,
-        );
-        const rotateData = (rotatePayload as any).data ?? rotatePayload;
-        this.token = String(rotateData.token);
-        return this.agentId;
+    const payload = await this.sendHttp<{ agent_id: string; token: string }>(
+      'POST',
+      '/v1/agents/register',
+      {
+        name: this.agentName,
+        workspace: this.config.workspace,
       }
-      throw error;
-    }
+    );
 
-    const data = (payload as any).data ?? payload;
-    this.agentId = String(data.id);
-    this.token = String(data.token);
+    this.agentId = payload.agent_id;
+    this.token = payload.token;
     return this.agentId;
   }
 
   async unregisterAgent(): Promise<void> {
-    if (!this.agentId || !this.token) {
+    if (!this.agentId) {
       return;
     }
 
+    const agentId = this.agentId;
     this.agentId = undefined;
-    const agentToken = this.token;
     this.token = undefined;
-    await this.sendHttpAsAgent('POST', '/v1/agents/disconnect', undefined, agentToken);
+    await this.sendHttp('DELETE', `/v1/agents/${agentId}`);
   }
 
   async sendDm(to: string, text: string): Promise<string> {
     await this.ensureRegistered();
-    const payload = await this.sendHttpAsAgent<JsonObject>('POST', '/v1/dm', { to, text });
-    const data = (payload as any).data ?? payload;
-    return String(data.id ?? data.message_id ?? '');
+    const payload = await this.sendHttp<{ message_id: string }>('POST', '/v1/messages/dm', {
+      to,
+      text,
+      from: this.agentName,
+    });
+    return payload.message_id;
   }
 
   async postMessage(channel: string, text: string): Promise<string> {
     await this.ensureRegistered();
-    const payload = await this.sendHttpAsAgent<JsonObject>(
-      'POST',
-      `/v1/channels/${encodeURIComponent(channel)}/messages`,
-      { text },
-    );
-    const data = (payload as any).data ?? payload;
-    return String(data.id ?? data.message_id ?? '');
+    const payload = await this.sendHttp<{ message_id: string }>('POST', '/v1/messages/channel', {
+      channel,
+      text,
+      from: this.agentName,
+    });
+    return payload.message_id;
   }
 
   async reply(messageId: string, text: string): Promise<string> {
     await this.ensureRegistered();
-    const payload = await this.sendHttpAsAgent<JsonObject>(
-      'POST',
-      `/v1/messages/${encodeURIComponent(messageId)}/replies`,
-      { text },
-    );
-    const data = (payload as any).data ?? payload;
-    return String(data.id ?? data.message_id ?? '');
+    const payload = await this.sendHttp<{ message_id: string }>('POST', '/v1/messages/reply', {
+      message_id: messageId,
+      text,
+      from: this.agentName,
+    });
+    return payload.message_id;
   }
 
   async checkInbox(): Promise<Message[]> {
     await this.ensureRegistered();
-    const payload = await this.sendHttpAsAgent<JsonObject>('GET', '/v1/inbox');
-    const data = (payload as any).data ?? payload;
-    const messages: Message[] = [];
-
-    for (const mention of ((data as any).mentions ?? []) as JsonObject[]) {
-      messages.push(this.messageFromPayload(mention));
-    }
-
-    for (const dm of ((data as any).unread_dms ?? []) as JsonObject[]) {
-      const last = (dm as any).last_message as JsonObject | undefined;
-      if (last?.text) {
-        messages.push({
-          sender: String(dm.from ?? dm.agent_name ?? 'unknown'),
-          text: String(last.text),
-          channel: undefined,
-          threadId: typeof dm.conversation_id === 'string' ? dm.conversation_id : undefined,
-          timestamp: typeof last.created_at === 'string' ? undefined : (last.created_at as number | undefined),
-          messageId: typeof last.id === 'string' ? last.id : undefined,
-        });
-      }
-    }
-
-    return messages;
+    const payload = await this.sendHttp<{ messages?: JsonObject[] }>('GET', `/v1/inbox/${this.agentId}`);
+    return (payload.messages ?? []).map((message) => this.messageFromPayload(message));
   }
 
   async listAgents(): Promise<string[]> {
-    const payload = await this.sendHttp<JsonObject>('GET', '/v1/agents');
-    const data = (payload as any).data ?? (payload as any).agents ?? [];
-    if (Array.isArray(data)) {
-      return data.map((a: any) => (typeof a === 'string' ? a : String(a.name ?? a)));
-    }
-    return [];
+    const payload = await this.sendHttp<{ agents?: string[] }>('GET', '/v1/agents');
+    return [...(payload.agents ?? [])];
   }
 
   private async ensureRegistered(): Promise<void> {
@@ -213,71 +170,6 @@ export class RelayTransport {
     }
   }
 
-  private async sendHttpAsAgent<T = unknown>(
-    method: string,
-    path: string,
-    payload?: JsonObject,
-    overrideToken?: string,
-  ): Promise<T> {
-    this.requireConfig();
-
-    const agentToken = overrideToken ?? this.token;
-    if (!agentToken) {
-      throw new RelayConfigError('Agent not registered; no agent token available.');
-    }
-
-    const url = `${this.config.baseUrl}${path}`;
-    const headers: Record<string, string> = {
-      authorization: `Bearer ${agentToken}`,
-    };
-    if (payload !== undefined) {
-      headers['content-type'] = 'application/json';
-    }
-
-    for (let attempt = 1; attempt <= HTTP_RETRY_ATTEMPTS; attempt += 1) {
-      let response: Response;
-      try {
-        response = await fetch(url, {
-          method,
-          headers,
-          body: payload === undefined ? undefined : JSON.stringify(payload),
-        });
-      } catch (error) {
-        if (attempt < HTTP_RETRY_ATTEMPTS) {
-          await sleep(Math.min(2 ** (attempt - 1) * 1_000, WS_RECONNECT_MAX_DELAY_MS));
-          continue;
-        }
-        throw new RelayConnectionError(0, error instanceof Error ? error.message : String(error));
-      }
-
-      if (response.status === 401) {
-        throw new RelayAuthError(await this.errorMessage(response));
-      }
-      if (response.status >= 500 && response.status <= 599) {
-        const message = await this.errorMessage(response);
-        if (attempt < HTTP_RETRY_ATTEMPTS) {
-          await sleep(Math.min(2 ** (attempt - 1) * 1_000, WS_RECONNECT_MAX_DELAY_MS));
-          continue;
-        }
-        throw new RelayConnectionError(response.status, message);
-      }
-      if (response.status >= 400) {
-        throw new RelayConnectionError(response.status, await this.errorMessage(response));
-      }
-      if (response.status === 204) {
-        return undefined as T;
-      }
-
-      const contentType = response.headers.get('content-type') ?? '';
-      if (contentType.includes('application/json')) {
-        return (await response.json()) as T;
-      }
-      return (await response.text()) as T;
-    }
-
-    throw new RelayConnectionError(500, 'Unexpected transport retry failure');
-  }
-
   private async sendHttp<T = unknown>(
     method: string,
     path: string,
@@ -354,7 +246,7 @@ export class RelayTransport {
       return this.wsConnectPromise;
     }
 
-    const url = `${this.wsBaseUrl()}/v1/ws?token=${encodeURIComponent(this.token ?? '')}`;
+    const url = `${this.wsBaseUrl()}/v1/ws/${this.agentId}?token=${encodeURIComponent(this.token ?? '')}`;
     const socket = new WebSocket(url);
 
     this.wsConnectPromise = new Promise<void>((resolve, reject) => {
@@ -437,12 +329,7 @@ export class RelayTransport {
       this.ws?.send(JSON.stringify({ type: 'pong' }));
       return;
     }
-
-    const messageEvents = new Set([
-      'message.created', 'dm.received', 'direct_message.received',
-      'thread.reply', 'message', 'group_dm.received',
-    ]);
-    if (!messageEvents.has(payload.type as string) || !this.messageCallback) {
+    if (payload.type !== 'message' || !this.messageCallback) {
       return;
     }
 
@@ -450,40 +337,22 @@ export class RelayTransport {
   }
 
   private messageFromPayload(payload: JsonObject): Message {
-    const m = (typeof payload.message === 'object' && payload.message !== null)
-      ? (payload.message as JsonObject)
-      : payload;
-
-    const sender = String(
-      m.sender ?? m.agent_name ?? m.from ?? m.agentName
-      ?? payload.agent_name ?? payload.from ?? 'unknown',
-    );
-    const text = String(m.text ?? '');
-    const channel = String(
-      m.channel ?? m.channel_name ?? m.channelName ?? payload.channel ?? payload.channel_name ?? '',
-    ) || undefined;
-    const threadId = String(
-      m.thread_id ?? m.threadId ?? m.conversation_id ?? m.conversationId ?? payload.thread_id ?? '',
-    ) || undefined;
-    const rawTs = m.timestamp ?? m.created_at ?? m.createdAt ?? payload.timestamp;
-    const timestamp = typeof rawTs === 'number' ? rawTs : undefined;
-    const messageId = String(
-      m.id ?? m.message_id ?? m.messageId ?? payload.message_id ?? '',
-    ) || undefined;
-
-    return { sender, text, channel, threadId, timestamp, messageId };
+    return {
+      sender: String(payload.sender ?? ''),
+      text: String(payload.text ?? ''),
+      channel: typeof payload.channel === 'string' ? payload.channel : undefined,
+      threadId: typeof payload.thread_id === 'string' ? payload.thread_id : undefined,
+      timestamp: typeof payload.timestamp === 'number' ? payload.timestamp : undefined,
+      messageId: typeof payload.message_id === 'string' ? payload.message_id : undefined,
+    };
   }
 
   private async errorMessage(response: Response): Promise<string> {
-    const text = await response.text().catch(() => '');
     try {
-      const payload = JSON.parse(text) as { message?: string; error?: { message?: string } };
-      if (typeof payload.error === 'object' && payload.error?.message) {
-        return payload.error.message;
-      }
+      const payload = (await response.json()) as { message?: string };
       return payload.message ?? response.statusText ?? 'Request failed';
     } catch {
-      return text || response.statusText || 'Request failed';
+      return (await response.text()) || response.statusText || 'Request failed';
     }
   }
 }

package/packages/sdk/src/http.ts

@@ -0,0 +1,96 @@
+/**
+ * Lightweight HTTP client for Relaycast API — safe for bundlers (Vite, Rollup, Webpack).
+ * No native dependencies, no broker binary, no process spawning.
+ *
+ * Usage:
+ *   import { RelayCast, createWorkspace, registerAgent } from '@agent-relay/sdk/http';
+ */
+
+// Re-export the HTTP-safe parts of @relaycast/sdk
+export { RelayCast, RelayError } from '@relaycast/sdk';
+export type { RelayCastOptions, CreateWorkspaceResponse } from '@relaycast/sdk';
+
+// Re-export useful protocol types from the SDK
+export type { AgentSpec, AgentRuntime } from './protocol.js';
+
+const DEFAULT_BASE_URL = 'https://api.relaycast.dev';
+
+interface CreateWorkspaceResult {
+  workspace_id: string;
+  api_key: string;
+}
+
+interface RegisterAgentResult {
+  name: string;
+  token: string;
+}
+
+/**
+ * Create a new Relaycast workspace using plain fetch.
+ * This function has zero dependencies beyond the Fetch API.
+ *
+ * @param name - Human-readable workspace name
+ * @param baseUrl - API base URL (defaults to https://api.relaycast.dev)
+ * @returns The workspace ID and API key
+ */
+export async function createWorkspace(
+  name: string,
+  baseUrl: string = DEFAULT_BASE_URL,
+): Promise<CreateWorkspaceResult> {
+  const url = `${baseUrl}/v1/workspaces`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new Error(
+      `Failed to create workspace (HTTP ${response.status}): ${body}`,
+    );
+  }
+
+  const body = (await response.json()) as
+    | CreateWorkspaceResult
+    | { ok: boolean; data: CreateWorkspaceResult };
+  // The API wraps responses in { ok, data } — unwrap transparently
+  return 'data' in body && body.data ? body.data : body as CreateWorkspaceResult;
+}
+
+/**
+ * Register an agent in a workspace using plain fetch.
+ * This function has zero dependencies beyond the Fetch API.
+ *
+ * @param apiKey - Workspace API key
+ * @param name - Agent name to register
+ * @param baseUrl - API base URL (defaults to https://api.relaycast.dev)
+ * @returns The registered agent name and token
+ */
+export async function registerAgent(
+  apiKey: string,
+  name: string,
+  baseUrl: string = DEFAULT_BASE_URL,
+): Promise<RegisterAgentResult> {
+  const url = `${baseUrl}/v1/agents`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ name }),
+  });
+
+  if (!response.ok) {
+    const errBody = await response.text().catch(() => '');
+    throw new Error(
+      `Failed to register agent (HTTP ${response.status}): ${errBody}`,
+    );
+  }
+
+  const body = (await response.json()) as
+    | RegisterAgentResult
+    | { ok: boolean; data: RegisterAgentResult };
+  return 'data' in body && body.data ? body.data : body as RegisterAgentResult;
+}

package/packages/sdk/src/protocol.ts

@@ -25,6 +25,8 @@ export interface AgentSpec {
   restart_policy?: RestartPolicy;
 }
 
+export type MessageInjectionMode = 'wait' | 'steer';
+
 export interface RelayDelivery {
   delivery_id: string;
   event_id: string;
@@ -35,6 +37,7 @@ export interface RelayDelivery {
   body: string;
   thread_id?: string;
   priority?: number;
+  injection_mode?: MessageInjectionMode;
 }
 
 export interface ProtocolEnvelope<TPayload> {
@@ -64,6 +67,7 @@ export type SdkToBroker =
         workspace_alias?: string;
         priority?: number;
         data?: Record<string, unknown>;
+        mode?: MessageInjectionMode;
       };
     }
   | {
@@ -74,6 +78,14 @@ export type SdkToBroker =
       type: 'send_input';
       payload: { name: string; data: string };
     }
+  | {
+      type: 'subscribe_channels';
+      payload: { name: string; channels: string[] };
+    }
+  | {
+      type: 'unsubscribe_channels';
+      payload: { name: string; channels: string[] };
+    }
   | {
       type: 'set_model';
       payload: { name: string; model: string; timeout_ms?: number };
@@ -221,6 +233,8 @@ export type BrokerEvent =
       target: string;
       body: string;
       thread_id?: string;
+      mode?: MessageInjectionMode;
+      injection_mode?: MessageInjectionMode;
     }
   | {
       kind: 'worker_stream';
@@ -280,6 +294,16 @@ export type BrokerEvent =
       delivery_id: string;
       event_id: string;
     }
+  | {
+      kind: 'channel_subscribed';
+      name: string;
+      channels: string[];
+    }
+  | {
+      kind: 'channel_unsubscribed';
+      name: string;
+      channels: string[];
+    }
   | {
       kind: 'worker_ready';
       name: string;