agent-relay 3.2.15 → 3.2.17

package/packages/sdk/src/relay.ts

@@ -33,7 +33,14 @@ import {
   type SendMessageInput,
   type SpawnPtyInput,
 } from './client.js';
-import type { AgentRuntime, BrokerEvent, BrokerStatus, HeadlessProvider, RestartPolicy } from './protocol.js';
+import type {
+  AgentRuntime,
+  BrokerEvent,
+  BrokerStatus,
+  HeadlessProvider,
+  MessageInjectionMode,
+  RestartPolicy,
+} from './protocol.js';
 import {
   followLogs as followLogsFromFile,
   getLogs as getLogsFromFile,
@@ -49,7 +56,13 @@ function isUnsupportedOperation(error: unknown): error is AgentRelayProtocolErro
 
 function buildUnsupportedOperationMessage(
   from: string,
-  input: { to: string; text: string; threadId?: string; data?: Record<string, unknown> }
+  input: {
+    to: string;
+    text: string;
+    threadId?: string;
+    data?: Record<string, unknown>;
+    mode?: MessageInjectionMode;
+  }
 ): Message {
   return {
     eventId: 'unsupported_operation',
@@ -58,6 +71,7 @@ function buildUnsupportedOperationMessage(
     text: input.text,
     threadId: input.threadId,
     data: input.data,
+    mode: input.mode,
   };
 }
 
@@ -70,6 +84,7 @@ export interface Message {
   text: string;
   threadId?: string;
   data?: Record<string, unknown>;
+  mode?: MessageInjectionMode;
 }
 
 export type AgentStatus = 'spawning' | 'ready' | 'idle' | 'exited';
@@ -178,9 +193,15 @@ export interface Agent {
     threadId?: string;
     priority?: number;
     data?: Record<string, unknown>;
+    mode?: MessageInjectionMode;
   }): Promise<Message>;
-  /** Register a callback for PTY output from this agent. Returns an unsubscribe function. */
-  onOutput(callback: AgentOutputCallback): () => void;
+  subscribe(channels: string[]): Promise<void>;
+  unsubscribe(channels: string[]): Promise<void>;
+  /** Register a callback for PTY output from this agent. Returns an unsubscribe function.
+   * @param options.stream — if provided, only invoke callback when the event stream matches (e.g. 'stdout', 'stderr')
+   * @param options.mode — 'chunk' for raw string callbacks, 'structured' for { stream, chunk } callbacks. Auto-detected if omitted.
+   */
+  onOutput(callback: AgentOutputCallback, options?: { stream?: string; mode?: 'chunk' | 'structured' }): () => void;
 }
 
 export interface HumanHandle {
@@ -191,6 +212,7 @@ export interface HumanHandle {
     threadId?: string;
     priority?: number;
     data?: Record<string, unknown>;
+    mode?: MessageInjectionMode;
   }): Promise<Message>;
 }
 
@@ -237,6 +259,11 @@ export interface AgentRelayOptions {
 type OutputListener = {
   callback: AgentOutputCallback;
   mode: 'chunk' | 'structured';
+  stream?: string;
+};
+
+type InternalAgent = Agent & {
+  _setChannels: (channels: string[]) => void;
 };
 
 // ── AgentRelay facade ───────────────────────────────────────────────────────
@@ -253,6 +280,8 @@ export class AgentRelay {
   onDeliveryUpdate: EventHook<BrokerEvent> = null;
   onAgentExitRequested: EventHook<{ name: string; reason: string }> = null;
   onAgentIdle: EventHook<{ name: string; idleSecs: number }> = null;
+  onChannelSubscribed: ((agent: string, channels: string[]) => void) | null = null;
+  onChannelUnsubscribed: ((agent: string, channels: string[]) => void) | null = null;
 
   // ── Public accessors ────────────────────────────────────────────────────
 
@@ -451,6 +480,7 @@ export class AgentRelay {
             threadId: input.threadId,
             priority: input.priority,
             data: input.data,
+            mode: input.mode,
           });
         } catch (error) {
           if (isUnsupportedOperation(error)) {
@@ -470,6 +500,7 @@ export class AgentRelay {
           text: input.text,
           threadId: input.threadId,
           data: input.data,
+          mode: input.mode,
         };
         this.onMessageSent?.(msg);
         return msg;
@@ -579,6 +610,18 @@ export class AgentRelay {
     return client.getStatus();
   }
 
+  async subscribe(opts: { agent: string; channels: string[] }): Promise<void> {
+    const client = await this.ensureStarted();
+    await client.subscribeChannels(opts.agent, opts.channels);
+    this.addAgentChannels(opts.agent, opts.channels);
+  }
+
+  async unsubscribe(opts: { agent: string; channels: string[] }): Promise<void> {
+    const client = await this.ensureStarted();
+    await client.unsubscribeChannels(opts.agent, opts.channels);
+    this.removeAgentChannels(opts.agent, opts.channels);
+  }
+
   getDeliveryState(eventId: string): DeliveryState | undefined {
     return this.deliveryStates.get(eventId);
   }
@@ -841,6 +884,20 @@ export class AgentRelay {
     return typeof candidate === 'number' ? candidate : Date.now();
   }
 
+  private addAgentChannels(name: string, channels: string[]): void {
+    const agent = this.knownAgents.get(name) as InternalAgent | undefined;
+    if (!agent || channels.length === 0) return;
+    const next = [...new Set([...agent.channels, ...channels])];
+    agent._setChannels(next);
+  }
+
+  private removeAgentChannels(name: string, channels: string[]): void {
+    const agent = this.knownAgents.get(name) as InternalAgent | undefined;
+    if (!agent || channels.length === 0) return;
+    const removed = new Set(channels);
+    agent._setChannels(agent.channels.filter((channel) => !removed.has(channel)));
+  }
+
   /** Resolve a target to a channel name. If `to` is `#channel`, use that
    *  channel. If it's a known agent name, use the agent's first channel.
    *  Otherwise fall back to the relay's default channel. */
@@ -863,6 +920,7 @@ export class AgentRelay {
     const listeners = this.outputListeners.get(name);
     if (!listeners) return;
     for (const listener of listeners) {
+      if (listener.stream !== undefined && listener.stream !== stream) continue;
       if (listener.mode === 'structured') {
         (listener.callback as (data: AgentOutputPayload) => void)({ stream, chunk });
       } else {
@@ -960,6 +1018,7 @@ export class AgentRelay {
             to: event.target,
             text: event.body,
             threadId: event.thread_id,
+            mode: event.injection_mode ?? event.mode,
           };
           this.onMessageReceived?.(msg);
           break;
@@ -1020,6 +1079,16 @@ export class AgentRelay {
           this.onAgentReady?.(agent);
           break;
         }
+        case 'channel_subscribed': {
+          this.addAgentChannels(event.name, event.channels);
+          this.onChannelSubscribed?.(event.name, event.channels);
+          break;
+        }
+        case 'channel_unsubscribed': {
+          this.removeAgentChannels(event.name, event.channels);
+          this.onChannelUnsubscribed?.(event.name, event.channels);
+          break;
+        }
         case 'delivery_queued': {
           this.updateDeliveryState(
             event.event_id,
@@ -1083,10 +1152,13 @@ export class AgentRelay {
   private makeAgent(name: string, runtime: AgentRuntime, channels: string[]): Agent {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const relay = this;
-    return {
+    let agentChannels = [...channels];
+    const agent: InternalAgent = {
       name,
       runtime,
-      channels,
+      get channels() {
+        return [...agentChannels];
+      },
       get status(): AgentStatus {
         if (relay.exitedAgents.has(name)) return 'exited';
         if (relay.idleAgents.has(name)) return 'idle';
@@ -1230,6 +1302,7 @@ export class AgentRelay {
             threadId: input.threadId,
             priority: input.priority,
             data: input.data,
+            mode: input.mode,
           });
         } catch (error) {
           if (isUnsupportedOperation(error)) {
@@ -1248,11 +1321,18 @@ export class AgentRelay {
           text: input.text,
           threadId: input.threadId,
           data: input.data,
+          mode: input.mode,
         };
         relay.onMessageSent?.(msg);
         return msg;
       },
-      onOutput(callback: AgentOutputCallback): () => void {
+      async subscribe(channelsToAdd: string[]) {
+        await relay.subscribe({ agent: name, channels: channelsToAdd });
+      },
+      async unsubscribe(channelsToRemove: string[]) {
+        await relay.unsubscribe({ agent: name, channels: channelsToRemove });
+      },
+      onOutput(callback: AgentOutputCallback, options?: { stream?: string; mode?: 'chunk' | 'structured' }): () => void {
         let listeners = relay.outputListeners.get(name);
         if (!listeners) {
           listeners = new Set();
@@ -1260,7 +1340,8 @@ export class AgentRelay {
         }
         const listener: OutputListener = {
           callback,
-          mode: relay.inferOutputMode(callback),
+          mode: options?.mode ?? relay.inferOutputMode(callback),
+          stream: options?.stream,
         };
         listeners.add(listener);
         return () => {
@@ -1270,7 +1351,11 @@ export class AgentRelay {
           }
         };
       },
+      _setChannels(nextChannels: string[]) {
+        agentChannels = [...nextChannels];
+      },
     };
+    return agent;
   }
 
   private createSpawner(cli: string, defaultName: string, runtime: AgentRuntime): AgentSpawner {

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

@@ -515,8 +515,9 @@ const runner = new WorkflowRunner({
   relay: { port: 3000 },         // AgentRelay options (optional)
 });
 
-// Listen to events
+// Listen to events (broker:event fires frequently — filter it out for cleaner output)
 runner.on((event) => {
+  if (event.type === 'broker:event') return;
   console.log(event.type, event);
 });
 
@@ -543,7 +544,9 @@ import { runWorkflow } from "@agent-relay/sdk/workflows";
 const result = await runWorkflow("workflow.yaml", {
   workflow: "deploy",
   vars: { environment: "staging" },
-  onEvent: (event) => console.log(event.type),
+  onEvent: (event) => {
+    if (event.type !== 'broker:event') console.log(event.type);
+  },
 });
 ```
 

package/packages/sdk/src/workflows/api-executor.ts

@@ -0,0 +1,108 @@
+/**
+ * API Executor — calls LLM provider APIs directly via fetch().
+ * Used when agent cli is 'api'. No sandbox, no CLI, no PTY.
+ */
+
+type Provider = 'anthropic' | 'openai' | 'google';
+
+function detectProvider(model: string): Provider {
+  if (model.startsWith('claude')) return 'anthropic';
+  if (model.startsWith('gpt') || model.startsWith('o1') || model.startsWith('o3') || model.startsWith('o4')) return 'openai';
+  if (model.startsWith('gemini')) return 'google';
+  return 'anthropic';
+}
+
+function getApiKey(provider: Provider, envSecrets?: Record<string, string>): string {
+  const envMap: Record<Provider, string[]> = {
+    anthropic: ['ANTHROPIC_API_KEY'],
+    openai: ['OPENAI_API_KEY'],
+    google: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
+  };
+  for (const key of envMap[provider]) {
+    const value = envSecrets?.[key] ?? process.env[key];
+    if (value) return value;
+  }
+  throw new Error(`No API key for "${provider}". Set ${envMap[provider].join(' or ')}.`);
+}
+
+interface ApiResponse {
+  content: string;
+  model: string;
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+async function callAnthropic(apiKey: string, model: string, task: string, maxTokens: number, systemPrompt?: string): Promise<ApiResponse> {
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify({
+      model, max_tokens: maxTokens,
+      ...(systemPrompt ? { system: systemPrompt } : {}),
+      messages: [{ role: 'user', content: task }],
+    }),
+  });
+  if (!res.ok) throw new Error(`Anthropic API error (${res.status}): ${await res.text()}`);
+  const data = await res.json() as { content: Array<{ type: string; text?: string }>; model: string; usage?: { input_tokens: number; output_tokens: number } };
+  return {
+    content: data.content.filter(c => c.type === 'text').map(c => c.text ?? '').join(''),
+    model: data.model,
+    usage: data.usage ? { inputTokens: data.usage.input_tokens, outputTokens: data.usage.output_tokens } : undefined,
+  };
+}
+
+async function callOpenAI(apiKey: string, model: string, task: string, maxTokens: number, systemPrompt?: string): Promise<ApiResponse> {
+  const messages: Array<{ role: string; content: string }> = [];
+  if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });
+  messages.push({ role: 'user', content: task });
+  const res = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'authorization': `Bearer ${apiKey}` },
+    body: JSON.stringify({ model, max_tokens: maxTokens, messages }),
+  });
+  if (!res.ok) throw new Error(`OpenAI API error (${res.status}): ${await res.text()}`);
+  const data = await res.json() as { choices: Array<{ message: { content: string } }>; model: string; usage?: { prompt_tokens: number; completion_tokens: number } };
+  return {
+    content: data.choices[0]?.message?.content ?? '',
+    model: data.model,
+    usage: data.usage ? { inputTokens: data.usage.prompt_tokens, outputTokens: data.usage.completion_tokens } : undefined,
+  };
+}
+
+async function callGoogle(apiKey: string, model: string, task: string, maxTokens: number, systemPrompt?: string): Promise<ApiResponse> {
+  const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-goog-api-key': apiKey },
+    body: JSON.stringify({
+      ...(systemPrompt ? { systemInstruction: { parts: [{ text: systemPrompt }] } } : {}),
+      contents: [{ parts: [{ text: task }] }],
+      generationConfig: { maxOutputTokens: maxTokens },
+    }),
+  });
+  if (!res.ok) throw new Error(`Google API error (${res.status}): ${await res.text()}`);
+  const data = await res.json() as { candidates: Array<{ content: { parts: Array<{ text: string }> } }>; usageMetadata?: { promptTokenCount: number; candidatesTokenCount: number } };
+  return {
+    content: data.candidates[0]?.content?.parts?.map(p => p.text).join('') ?? '',
+    model,
+    usage: data.usageMetadata ? { inputTokens: data.usageMetadata.promptTokenCount, outputTokens: data.usageMetadata.candidatesTokenCount } : undefined,
+  };
+}
+
+const PROVIDER_CALLERS = { anthropic: callAnthropic, openai: callOpenAI, google: callGoogle } as const;
+
+export interface ApiExecutorOptions {
+  envSecrets?: Record<string, string>;
+  defaultModel?: string;
+  defaultMaxTokens?: number;
+  skills?: string;
+}
+
+export async function executeApiStep(model: string, task: string, options: ApiExecutorOptions = {}): Promise<string> {
+  const resolvedModel = model || options.defaultModel || 'claude-sonnet-4-20250514';
+  const maxTokens = options.defaultMaxTokens ?? 4096;
+  const provider = detectProvider(resolvedModel);
+  const apiKey = getApiKey(provider, options.envSecrets);
+  const response = await PROVIDER_CALLERS[provider](apiKey, resolvedModel, task, maxTokens, options.skills);
+  return response.content;
+}
+
+export { detectProvider, getApiKey };

package/packages/sdk/src/workflows/builder.ts

@@ -23,6 +23,7 @@ import type {
 import { WorkflowRunner, type WorkflowEventListener, type VariableContext, type StepExecutor } from './runner.js';
 import { formatDryRunReport } from './dry-run-format.js';
 import { createDefaultEventLogger, type LogLevel } from './default-logger.js';
+import { runInCloud, type CloudRunOptions } from './cloud-runner.js';
 
 // ── Option types for the builder API ────────────────────────────────────────
 
@@ -42,6 +43,8 @@ export interface AgentOptions {
   interactive?: boolean;
   /** Agent preset: 'lead' (interactive PTY), 'worker' | 'reviewer' | 'analyst' (non-interactive subprocess). */
   preset?: AgentPreset;
+  /** Skills to make available to the agent (for API-mode agents). */
+  skills?: string;
 }
 
 /** Options for agent steps (default). */
@@ -111,6 +114,18 @@ export interface WorkflowRunOptions {
   logLevel?: LogLevel;
   /** Renderer: "listr" for listr2 UI, "default" for console logger, false to disable. */
   renderer?: 'listr' | 'default' | false;
+  /** Run the workflow in the cloud instead of locally. */
+  cloud?: boolean;
+  /** Cloud API base URL (or set CLOUD_API_URL env var). */
+  cloudApiUrl?: string;
+  /** Cloud API authentication token (or set CLOUD_API_TOKEN env var). */
+  cloudApiToken?: string;
+  /** Environment secrets to forward to cloud agents. */
+  envSecrets?: Record<string, string>;
+  /** Polling interval in ms for cloud run status checks. */
+  cloudPollIntervalMs?: number;
+  /** Callback invoked when the cloud run status changes. */
+  onCloudStatusChange?: (status: string, runId: string) => void;
 }
 
 // ── WorkflowBuilder ─────────────────────────────────────────────────────────
@@ -177,6 +192,13 @@ export class WorkflowBuilder {
 
   /** Set the relay channel for agent communication. */
   channel(ch: string): this {
+    const CHANNEL_RE = /^[a-z0-9][a-z0-9-]*$/;
+    if (!CHANNEL_RE.test(ch)) {
+      throw new Error(
+        `Invalid channel name "${ch}". Channel names must be lowercase alphanumeric and hyphens, starting with a letter or number. ` +
+        `Fix: use .toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')`
+      );
+    }
     this._channel = ch;
     return this;
   }
@@ -229,6 +251,7 @@ export class WorkflowBuilder {
     if (options.channels !== undefined) def.channels = options.channels;
     if (options.preset !== undefined) def.preset = options.preset;
     if (options.interactive !== undefined) def.interactive = options.interactive;
+    if (options.skills !== undefined) def.skills = options.skills;
 
     if (
       options.model !== undefined ||
@@ -365,6 +388,7 @@ export class WorkflowBuilder {
       cwd: options.cwd,
       relay: options.relay,
       executor: options.executor,
+      envSecrets: options.envSecrets,
     });
 
     // Auto-detect DRY_RUN env var so existing scripts get dry-run for free
@@ -376,6 +400,22 @@ export class WorkflowBuilder {
       return report;
     }
 
+    // Cloud execution path — submit to remote API and poll for completion
+    if (options.cloud) {
+      const cloudApiUrl = options.cloudApiUrl ?? process.env.CLOUD_API_URL;
+      const cloudApiToken = options.cloudApiToken ?? process.env.CLOUD_API_TOKEN;
+      if (!cloudApiUrl) throw new Error('cloud: true requires cloudApiUrl or CLOUD_API_URL env var');
+      if (!cloudApiToken) throw new Error('cloud: true requires cloudApiToken or CLOUD_API_TOKEN env var');
+      return runInCloud(config, {
+        cloudApiUrl,
+        cloudApiToken,
+        envSecrets: options.envSecrets,
+        pollIntervalMs: options.cloudPollIntervalMs,
+        timeoutMs: this._timeoutMs,
+        onStatusChange: options.onCloudStatusChange,
+      });
+    }
+
     // Wire up default console logger unless explicitly disabled
     // renderer: "listr" owns the terminal — skip console logger to avoid garbled output
     // renderer: false implies no output at all

package/packages/sdk/src/workflows/cloud-runner.ts

@@ -0,0 +1,56 @@
+/**
+ * Cloud workflow runner — submits workflows to AgentWorkforce cloud API
+ * and polls for completion.
+ */
+import type { RelayYamlConfig, WorkflowRunRow, WorkflowRunStatus } from './types.js';
+
+export interface CloudRunOptions {
+  cloudApiUrl: string;
+  cloudApiToken: string;
+  envSecrets?: Record<string, string>;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  onStatusChange?: (status: WorkflowRunStatus, runId: string) => void;
+}
+
+export async function runInCloud(config: RelayYamlConfig, options: CloudRunOptions): Promise<WorkflowRunRow> {
+  const { cloudApiUrl, cloudApiToken, envSecrets, pollIntervalMs = 3000, timeoutMs = 1800000 } = options;
+  const baseUrl = cloudApiUrl.replace(/\/$/, '');
+
+  const { stringify: stringifyYaml } = await import('yaml');
+  const yamlStr = stringifyYaml(config);
+
+  const submitRes = await fetch(`${baseUrl}/api/v1/workflows/run`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${cloudApiToken}` },
+    body: JSON.stringify({ workflow: yamlStr, fileType: 'yaml' as const, ...(envSecrets ? { envSecrets } : {}) }),
+  });
+  if (!submitRes.ok) throw new Error(`Cloud submit failed (${submitRes.status}): ${await submitRes.text()}`);
+
+  const { runId } = (await submitRes.json()) as { runId: string; sandboxId: string; status: string };
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus: WorkflowRunStatus = 'pending';
+
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, pollIntervalMs));
+    const statusRes = await fetch(`${baseUrl}/api/v1/workflows/runs/${runId}`, {
+      headers: { 'Authorization': `Bearer ${cloudApiToken}` },
+    });
+    if (!statusRes.ok) continue;
+
+    const data = (await statusRes.json()) as { runId: string; status: WorkflowRunStatus; error?: string; createdAt?: string; updatedAt?: string };
+    if (data.status !== lastStatus) { lastStatus = data.status; options.onStatusChange?.(lastStatus, runId); }
+
+    if (data.status === 'completed' || data.status === 'failed') {
+      return {
+        id: runId, workspaceId: '', workflowName: config.name ?? 'cloud-workflow',
+        pattern: (config.swarm?.pattern as any) ?? 'dag', status: data.status, config,
+        startedAt: data.createdAt ?? new Date().toISOString(),
+        completedAt: data.updatedAt ?? new Date().toISOString(),
+        error: data.error, createdAt: data.createdAt ?? new Date().toISOString(),
+        updatedAt: data.updatedAt ?? new Date().toISOString(),
+      };
+    }
+  }
+  throw new Error(`Cloud workflow timed out after ${timeoutMs}ms (runId: ${runId})`);
+}

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

@@ -26,3 +26,5 @@ export { WorkflowTrajectory, type StepOutcome } from './trajectory.js';
 export { formatDryRunReport } from './dry-run-format.js';
 export { createWorkflowRenderer, type WorkflowRenderer } from './listr-renderer.js';
 export { createDefaultEventLogger } from './default-logger.js';
+export { executeApiStep, type ApiExecutorOptions } from './api-executor.js';
+export type { CloudRunOptions } from './cloud-runner.js';

package/packages/sdk/src/workflows/run.ts

@@ -1,6 +1,7 @@
 import type { AgentRelayOptions } from '../relay.js';
 import type { DryRunReport, TrajectoryConfig, WorkflowRunRow } from './types.js';
 import { WorkflowRunner, type WorkflowEventListener, type VariableContext } from './runner.js';
+import { createDefaultEventLogger } from './default-logger.js';
 import { formatDryRunReport } from './dry-run-format.js';
 
 /**
@@ -70,6 +71,10 @@ export async function runWorkflow(
     return report;
   }
 
+  // Attach default console logger so callers get progress output without
+  // needing to wire up their own handler.
+  runner.on(createDefaultEventLogger('normal'));
+
   if (options.onEvent) {
     runner.on(options.onEvent);
   }