agent-relay 3.2.4 → 3.2.6

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "3.2.4",
+  "version": "3.2.6",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -64,6 +64,11 @@
       "types": "./dist/communicate/adapters/claude-sdk.d.ts",
       "import": "./dist/communicate/adapters/claude-sdk.js",
       "default": "./dist/communicate/adapters/claude-sdk.js"
+    },
+    "./communicate/adapters/ai-sdk": {
+      "types": "./dist/communicate/adapters/ai-sdk.d.ts",
+      "import": "./dist/communicate/adapters/ai-sdk.js",
+      "default": "./dist/communicate/adapters/ai-sdk.js"
     }
   },
   "files": [
@@ -97,7 +102,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.4",
+    "@agent-relay/config": "3.2.6",
     "@relaycast/sdk": "^0.4.0",
     "@sinclair/typebox": "^0.34.48",
     "ws": "^8.18.3",
@@ -109,6 +114,7 @@
     "@langchain/langgraph": ">=1.2.0",
     "@mariozechner/pi-coding-agent": ">=0.50.0",
     "@openai/agents": ">=0.7.0",
+    "ai": ">=5.0.0",
     "crewai": ">=1.0.0"
   },
   "peerDependenciesMeta": {
@@ -127,6 +133,9 @@
     "@openai/agents": {
       "optional": true
     },
+    "ai": {
+      "optional": true
+    },
     "crewai": {
       "optional": true
     }

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

@@ -0,0 +1,131 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+const adapterModulePath = '../../../communicate/adapters/ai-sdk.js';
+
+async function loadModule(): Promise<any> {
+  return import(adapterModulePath);
+}
+
+class FakeRelay {
+  private callbacks: Array<(message: any) => void | Promise<void>> = [];
+
+  sent: Array<{ to: string; text: string }> = [];
+  posted: Array<{ channel: string; text: string }> = [];
+  inboxMessages: any[] = [];
+
+  async send(to: string, text: string): Promise<void> {
+    this.sent.push({ to, text });
+  }
+
+  async post(channel: string, text: string): Promise<void> {
+    this.posted.push({ channel, text });
+  }
+
+  async inbox(): Promise<any[]> {
+    const messages = [...this.inboxMessages];
+    this.inboxMessages = [];
+    return messages;
+  }
+
+  async agents(): Promise<string[]> {
+    return ['Lead', 'Researcher'];
+  }
+
+  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);
+    }
+  }
+}
+
+test('AI SDK onRelay returns relay tool definitions', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+
+  const session = onRelay({ name: 'AiSdkTester' }, relay);
+  const toolNames = Object.keys(session.tools);
+
+  assert.deepEqual(toolNames, ['relay_send', 'relay_inbox', 'relay_post', 'relay_agents']);
+  assert.equal(typeof session.middleware.transformParams, 'function');
+  assert.equal(typeof session.cleanup, 'function');
+});
+
+test('AI SDK relay tools execute against the relay client', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  relay.inboxMessages = [{ sender: 'Lead', text: 'Check status', messageId: 'msg-1' }];
+
+  const session = onRelay({ name: 'AiSdkTester' }, relay);
+
+  await session.tools.relay_send.execute?.({ to: 'Lead', text: 'Working on it' });
+  await session.tools.relay_post.execute?.({ channel: 'ops', text: 'status update' });
+  const inboxResult = await session.tools.relay_inbox.execute?.({});
+  const agentsResult = await session.tools.relay_agents.execute?.({});
+
+  assert.deepEqual(relay.sent, [{ to: 'Lead', text: 'Working on it' }]);
+  assert.deepEqual(relay.posted, [{ channel: 'ops', text: 'status update' }]);
+  assert.match(String((inboxResult as any).text), /Check status/);
+  assert.deepEqual((agentsResult as any).agents, ['Lead', 'Researcher']);
+});
+
+test('AI SDK middleware appends relay instructions and pending messages to system', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const session = onRelay({ name: 'AiSdkTester', instructions: 'Escalate blockers quickly.' }, relay);
+
+  await relay.emit({ sender: 'Lead', text: 'Need an update', messageId: 'msg-2' });
+
+  const first = await session.middleware.transformParams?.({ params: { system: 'Base system.' } });
+  const second = await session.middleware.transformParams?.({ params: { system: 'Base system.' } });
+
+  assert.match(String(first?.system), /Base system\./);
+  assert.match(String(first?.system), /Use relay_send/);
+  assert.match(String(first?.system), /Escalate blockers quickly\./);
+  assert.match(String(first?.system), /Need an update/);
+  assert.equal(second?.system?.includes('Need an update'), false);
+});
+
+test('AI SDK middleware prepends a synthetic system message for message-array calls', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const session = onRelay({ name: 'AiSdkTester', instructions: 'Escalate blockers quickly.' }, relay);
+
+  await relay.emit({ sender: 'Reviewer', text: 'Need approval on the fix', messageId: 'msg-4' });
+
+  const result = await session.middleware.transformParams?.({
+    params: {
+      system: 'Base system.',
+      messages: [{ role: 'user', content: 'Can you ship this?' }],
+    },
+  });
+
+  assert.equal(Array.isArray(result?.messages), true);
+  assert.equal(result?.messages?.[0]?.role, 'system');
+  assert.match(String(result?.messages?.[0]?.content), /Use relay_send/);
+  assert.match(String(result?.messages?.[0]?.content), /Escalate blockers quickly\./);
+  assert.match(String(result?.messages?.[0]?.content), /Need approval on the fix/);
+  assert.equal(result?.messages?.[1]?.role, 'user');
+  assert.equal(result?.system, 'Base system.');
+  assert.doesNotMatch(String(result?.system), /Use relay_send/);
+  assert.doesNotMatch(String(result?.system), /Need approval on the fix/);
+});
+
+test('AI SDK cleanup unsubscribes from live relay messages', async () => {
+  const { onRelay } = await loadModule();
+  const relay = new FakeRelay();
+  const session = onRelay({ name: 'AiSdkTester' }, relay);
+
+  session.cleanup();
+  await relay.emit({ sender: 'Lead', text: 'Late ping', messageId: 'msg-3' });
+  const result = await session.middleware.transformParams?.({ params: {} });
+
+  assert.equal(String(result?.system).includes('Late ping'), false);
+});

package/packages/sdk/src/__tests__/models.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Model metadata tests.
+ *
+ * Run:
+ *   npm run build && node --test dist/__tests__/models.test.js
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  ModelMetadata,
+  ModelOptions,
+  Models,
+  ReasoningEfforts,
+  getDefaultReasoningEffort,
+  getModelMetadata,
+  getSupportedReasoningEfforts,
+} from '../models.js';
+
+test('codex model options include reasoning effort metadata', () => {
+  const mini = ModelOptions.Codex.find((model) => model.value === Models.Codex.GPT_5_1_CODEX_MINI);
+  const frontier = ModelOptions.Codex.find((model) => model.value === Models.Codex.GPT_5_4);
+
+  assert.deepEqual(mini?.reasoningEfforts, [ReasoningEfforts.MEDIUM, ReasoningEfforts.HIGH]);
+  assert.equal(mini?.defaultReasoningEffort, ReasoningEfforts.HIGH);
+
+  assert.deepEqual(frontier?.reasoningEfforts, [
+    ReasoningEfforts.LOW,
+    ReasoningEfforts.MEDIUM,
+    ReasoningEfforts.HIGH,
+    ReasoningEfforts.XHIGH,
+  ]);
+  assert.equal(frontier?.defaultReasoningEffort, ReasoningEfforts.XHIGH);
+});
+
+test('reasoning helper lookups return codex defaults and supported values', () => {
+  assert.equal(
+    getDefaultReasoningEffort('codex', Models.Codex.GPT_5_1_CODEX_MINI),
+    ReasoningEfforts.HIGH,
+  );
+  assert.equal(
+    getDefaultReasoningEffort('codex', Models.Codex.GPT_5_4),
+    ReasoningEfforts.XHIGH,
+  );
+  assert.deepEqual(
+    getSupportedReasoningEfforts('codex', Models.Codex.GPT_5_1_CODEX_MINI),
+    [ReasoningEfforts.MEDIUM, ReasoningEfforts.HIGH],
+  );
+  assert.equal(getDefaultReasoningEffort('claude', Models.Claude.SONNET), undefined);
+});
+
+test('model metadata is keyed by model id for direct lookup', () => {
+  assert.deepEqual(
+    ModelMetadata.Codex[Models.Codex.GPT_5_1_CODEX_MINI],
+    getModelMetadata('codex', Models.Codex.GPT_5_1_CODEX_MINI),
+  );
+  assert.equal(
+    ModelMetadata.Codex[Models.Codex.GPT_5_1_CODEX_MINI].defaultReasoningEffort,
+    ReasoningEfforts.HIGH,
+  );
+});

package/packages/sdk/src/client.ts

@@ -369,6 +369,19 @@ export class AgentRelayClient {
     return this.requestOk<{ name: string; bytes_written: number }>('send_input', { name, data });
   }
 
+  async resizePty(
+    name: string,
+    rows: number,
+    cols: number
+  ): Promise<{ name: string; rows: number; cols: number }> {
+    await this.start();
+    return this.requestOk<{ name: string; rows: number; cols: number }>('resize_pty', {
+      name,
+      rows,
+      cols,
+    });
+  }
+
   async setModel(
     name: string,
     model: string,

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

@@ -0,0 +1,200 @@
+import { Relay } from '../core.js';
+import { formatRelayMessage, type Message, type MessageCallback } from '../types.js';
+
+const DEFAULT_RELAY_SYSTEM_INSTRUCTIONS = [
+  'You are connected to Agent Relay.',
+  'Use relay_send for direct messages, relay_post for channel updates, relay_agents to inspect who is online, and relay_inbox to fetch buffered messages.',
+  'When relay messages are injected below, treat them as the latest coordination context and respond or delegate as needed.',
+].join(' ');
+
+type JsonObjectSchema = {
+  type: 'object';
+  properties: Record<string, Record<string, unknown>>;
+  required: string[];
+  additionalProperties: boolean;
+};
+
+export type AiSdkToolLike = {
+  description?: string;
+  inputSchema: JsonObjectSchema;
+  execute?: (input: Record<string, string>) => Promise<unknown>;
+};
+
+export type AiSdkTools = Record<string, AiSdkToolLike>;
+
+export type AiSdkMessageLike = {
+  role?: string;
+  content?: unknown;
+  [key: string]: unknown;
+};
+
+export type AiSdkCallParams = {
+  system?: string;
+  messages?: AiSdkMessageLike[];
+  prompt?: string;
+  [key: string]: unknown;
+};
+
+export type AiSdkMiddlewareLike = {
+  transformParams?: (input: { params: AiSdkCallParams }) => Promise<AiSdkCallParams> | AiSdkCallParams;
+};
+
+export 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;
+};
+
+export interface AiSdkRelayOptions {
+  /** Agent name used when registering with Relaycast. */
+  name: string;
+  /** Optional custom instructions appended to the system prompt on every model call. */
+  instructions?: string;
+  /** Disable the default relay instructions if you want to provide your own. */
+  includeDefaultInstructions?: boolean;
+}
+
+export interface AiSdkRelaySession {
+  /** AI SDK-compatible tool map for generateText/streamText. */
+  tools: AiSdkTools;
+  /** AI SDK language model middleware that injects pending relay messages into system. */
+  middleware: AiSdkMiddlewareLike;
+  /** Underlying relay client. */
+  relay: RelayLike;
+  /** Stop live routing and clear any injected-message state. */
+  cleanup: () => void;
+}
+
+function schema(props: Record<string, Record<string, unknown>>, required: string[]): JsonObjectSchema {
+  return { type: 'object', properties: props, required, additionalProperties: false };
+}
+
+function createRelayTools(relay: RelayLike): AiSdkTools {
+  return {
+    relay_send: {
+      description: 'Send a direct message to another relay agent.',
+      inputSchema: schema({ to: { type: 'string' }, text: { type: 'string' } }, ['to', 'text']),
+      async execute(input) {
+        await relay.send(input.to, input.text);
+        return { ok: true, status: `Sent relay message to ${input.to}.` };
+      },
+    },
+    relay_inbox: {
+      description: 'Drain and inspect newly received relay messages.',
+      inputSchema: schema({}, []),
+      async execute() {
+        const messages = await relay.inbox();
+        return {
+          ok: true,
+          messages,
+          text: messages.length === 0 ? 'No new relay messages.' : messages.map(formatRelayMessage).join('\n'),
+        };
+      },
+    },
+    relay_post: {
+      description: 'Post a message to a relay channel.',
+      inputSchema: schema({ channel: { type: 'string' }, text: { type: 'string' } }, ['channel', 'text']),
+      async execute(input) {
+        await relay.post(input.channel, input.text);
+        return { ok: true, status: `Posted relay message to #${input.channel}.` };
+      },
+    },
+    relay_agents: {
+      description: 'List currently online relay agents.',
+      inputSchema: schema({}, []),
+      async execute() {
+        const agents = await relay.agents();
+        return { ok: true, agents, text: agents.join('\n') };
+      },
+    },
+  };
+}
+
+function composeRelayInstructions(pendingMessages: string[], options: AiSdkRelayOptions): string {
+  const sections = [
+    options.includeDefaultInstructions === false ? '' : DEFAULT_RELAY_SYSTEM_INSTRUCTIONS,
+    options.instructions?.trim() ?? '',
+    pendingMessages.length > 0 ? `--- Relay Messages ---\n${pendingMessages.join('\n')}` : '',
+  ].filter((value) => value.length > 0);
+
+  return sections.join('\n\n');
+}
+
+function composeSystemPrompt(baseSystem: string | undefined, pendingMessages: string[], options: AiSdkRelayOptions): string {
+  const sections: string[] = [];
+
+  if (baseSystem && baseSystem.trim().length > 0) {
+    sections.push(baseSystem.trim());
+  }
+
+  const relayInstructions = composeRelayInstructions(pendingMessages, options);
+  if (relayInstructions.length > 0) {
+    sections.push(relayInstructions);
+  }
+
+  return sections.join('\n\n');
+}
+
+function injectSyntheticSystemMessage(
+  messages: AiSdkMessageLike[] | undefined,
+  pendingMessages: string[],
+  options: AiSdkRelayOptions,
+): AiSdkMessageLike[] | undefined {
+  if (!Array.isArray(messages)) {
+    return messages;
+  }
+
+  const relayInstructions = composeRelayInstructions(pendingMessages, options);
+  if (relayInstructions.length === 0) {
+    return messages;
+  }
+
+  return [{ role: 'system', content: relayInstructions }, ...messages];
+}
+
+/**
+ * Create AI SDK tools + middleware for putting a model-driven app on Agent Relay.
+ *
+ * Typical usage pairs the returned `middleware` with `wrapLanguageModel(...)`
+ * from `ai`, and the returned `tools` with `generateText(...)` or `streamText(...)`.
+ */
+export function onRelay(
+  options: AiSdkRelayOptions,
+  relay: RelayLike = new Relay(options.name),
+): AiSdkRelaySession {
+  const tools = createRelayTools(relay);
+  const pendingMessages: string[] = [];
+
+  const unsubscribe = relay.onMessage(async (message) => {
+    pendingMessages.push(formatRelayMessage(message));
+  });
+
+  return {
+    tools,
+    relay,
+    middleware: {
+      async transformParams({ params }): Promise<AiSdkCallParams> {
+        const liveMessages = pendingMessages.splice(0, pendingMessages.length);
+        const hasMessages = Array.isArray(params.messages);
+        const baseSystem = typeof params.system === 'string' ? params.system : undefined;
+        const nextMessages = injectSyntheticSystemMessage(
+          hasMessages ? [...(params.messages ?? [])] : params.messages,
+          liveMessages,
+          options,
+        );
+
+        return {
+          ...params,
+          messages: nextMessages,
+          system: hasMessages ? baseSystem : composeSystemPrompt(baseSystem, liveMessages, options),
+        };
+      },
+    },
+    cleanup() {
+      unsubscribe();
+      pendingMessages.splice(0, pendingMessages.length);
+    },
+  };
+}

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

@@ -4,3 +4,4 @@ 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/index.ts

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

package/packages/sdk/src/models.ts

@@ -11,6 +11,7 @@ export {
   CLIs,
   CLIVersions,
   CLIRegistry,
+  ReasoningEfforts,
   // Model constants
   ClaudeModels,
   CodexModels,
@@ -23,7 +24,11 @@ export {
   CODEX_MODEL_OPTIONS,
   GEMINI_MODEL_OPTIONS,
   CURSOR_MODEL_OPTIONS,
+  ModelMetadata,
   ModelOptions,
+  getDefaultReasoningEffort,
+  getModelMetadata,
+  getSupportedReasoningEfforts,
   // Swarm patterns (type is in workflows/types.ts)
   SwarmPatterns,
   // Types
@@ -33,4 +38,5 @@ export {
   type GeminiModel,
   type CursorModel,
   type ModelOption,
+  type ReasoningEffort,
 } from '@agent-relay/config';

package/packages/sdk/src/protocol.ts

@@ -104,6 +104,11 @@ export type SdkToBroker =
        *  the cache instead of waiting on individual HTTP registrations. */
       type: 'preflight_agents';
       payload: { agents: Array<{ name: string; cli: string }> };
+    }
+  | {
+      /** Resize a PTY agent's terminal dimensions. */
+      type: 'resize_pty';
+      payload: { name: string; rows: number; cols: number };
     };
 
 export interface PendingDeliveryInfo {
@@ -365,6 +370,10 @@ export type BrokerToWorker =
   | {
       type: 'ping';
       payload: { ts_ms: number };
+    }
+  | {
+      type: 'resize_pty';
+      payload: { rows: number; cols: number };
     };
 
 export type WorkerToBroker =

package/packages/sdk/src/workflows/README.md

@@ -67,6 +67,61 @@ result = (
 )
 ```
 
+## Consumer-Facing Apps + AI SDK Communicate Flows
+
+A good production split is:
+
+1. **AI SDK app** handles the user conversation and streaming UI
+2. **Communicate / `onRelay()`** lets that point-person coordinate with specialists over Relay
+3. **Workflows / `runWorkflow()`** take over when a request needs multi-step execution, verification, or handoffs
+
+```typescript
+import { streamText, wrapLanguageModel } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { Relay } from '@agent-relay/sdk/communicate';
+import { onRelay } from '@agent-relay/sdk/communicate/adapters/ai-sdk';
+import { runWorkflow } from '@agent-relay/sdk/workflows';
+
+export async function POST(req: Request) {
+  const { prompt, escalate, repo } = await req.json();
+
+  const relay = new Relay('AppLead');
+  const relaySession = onRelay({
+    name: 'AppLead',
+    instructions: 'You are the customer-facing lead. Keep the user updated and delegate implementation via Relay when needed.',
+  }, relay);
+
+  const model = wrapLanguageModel({
+    model: openai('gpt-4o-mini'),
+    middleware: relaySession.middleware,
+  });
+
+  if (escalate) {
+    const workflow = await runWorkflow('workflows/feature-dev.yaml', {
+      vars: { task: prompt, repo },
+    });
+
+    return Response.json({ status: workflow.status, runId: workflow.runId });
+  }
+
+  return streamText({
+    model,
+    tools: relaySession.tools,
+    system: 'Answer directly when possible; coordinate internally when the task needs specialists.',
+    prompt,
+  }).toUIMessageStreamResponse({
+    onFinish() {
+      relaySession.cleanup();
+      void relay.close();
+    },
+  });
+}
+```
+
+That pattern keeps the user experience snappy while still letting longer Relay workflows run with proper ownership, retries, and verification.
+
+A compact end-to-end example app for this pattern lives in `examples/ai-sdk-relay-helpdesk/`.
+
 ## YAML Format
 
 Workflows are defined as `relay.yaml` files:

package/packages/sdk/tsconfig.build.json

@@ -3,6 +3,11 @@
     "target": "ES2022",
     "module": "ES2022",
     "moduleResolution": "Bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@agent-relay/config": ["../config/dist/index.d.ts"],
+      "@agent-relay/config/*": ["../config/dist/*"]
+    },
     "strict": true,
     "declaration": true,
     "declarationMap": true,

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.4"
+version = "3.2.6"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/shared/cli-registry.yaml

@@ -37,24 +37,38 @@ clis:
         id: "gpt-5.4"
         label: "GPT-5.4 — Latest frontier agentic coding model"
         default: true
+        reasoning_efforts: ["low", "medium", "high", "xhigh"]
+        default_reasoning_effort: "xhigh"
       gpt_5_3_codex:
         id: "gpt-5.3-codex"
         label: "GPT-5.3 Codex — Frontier agentic coding model"
+        reasoning_efforts: ["low", "medium", "high", "xhigh"]
+        default_reasoning_effort: "xhigh"
       gpt_5_3_codex_spark:
         id: "gpt-5.3-codex-spark"
         label: "GPT-5.3 Codex Spark — Ultra-fast coding model"
+        reasoning_efforts: ["low", "medium", "high", "xhigh"]
+        default_reasoning_effort: "xhigh"
       gpt_5_2_codex:
         id: "gpt-5.2-codex"
         label: "GPT-5.2 Codex — Frontier agentic coding model"
+        reasoning_efforts: ["low", "medium", "high", "xhigh"]
+        default_reasoning_effort: "xhigh"
       gpt_5_2:
         id: "gpt-5.2"
         label: "GPT-5.2 — Frontier model, knowledge & reasoning"
+        reasoning_efforts: ["low", "medium", "high", "xhigh"]
+        default_reasoning_effort: "xhigh"
       gpt_5_1_codex_max:
         id: "gpt-5.1-codex-max"
         label: "GPT-5.1 Codex Max — Deep and fast reasoning"
+        reasoning_efforts: ["low", "medium", "high", "xhigh"]
+        default_reasoning_effort: "xhigh"
       gpt_5_1_codex_mini:
         id: "gpt-5.1-codex-mini"
         label: "GPT-5.1 Codex Mini — Cheaper, faster"
+        reasoning_efforts: ["medium", "high"]
+        default_reasoning_effort: "high"
 
   gemini:
     name: "Gemini CLI"