Channel Client

Add a Swarmd channel to a TypeScript website with automatic OAuth, typed lifecycle events, HITL handling, and conversation continuity.

TypeScript Channel Client

@swarmd/channel-client is the recommended way to connect a website, bot, or backend service to an agent through a Swarmd channel. It wraps the Conversation REST API and handles:

• OAuth2 client-credentials exchange, token caching, and refresh
• deriving channelId from the standard channel-{channelId} client ID
• conversation creation and follow-up message continuity
• the send fast path and background polling
• typed lifecycle events for working, hitl-held, and terminal outcomes
• cancellation with AbortSignal
• text and artifact reply extraction
• structured authentication, API, and polling errors

clientSecret is a server credential. Use this library in a Node.js server, API route, server action, worker, or other trusted backend. The client refuses to initialize when it detects a browser. Never put the secret in a NEXT_PUBLIC_*, VITE_*, or other client-exposed environment variable.

Install

npm install @swarmd/channel-client

Node.js 18 or later is supported. The package has no runtime dependencies and uses the built-in Fetch API.

Before You Start

In the Swarmd dashboard:

1. Create a channel for the website or service.
2. Save the returned clientId and clientSecret. The secret is shown only when the channel is created.
3. Subscribe the channel to the agent it should invoke.
4. Copy the subscribed agent’s agentId.

See Your First Agent for the API-based setup.

Configure server-only environment variables:

SWARMD_CHANNEL_CLIENT_ID=channel-d4ac7a03-e833-434f-badc-c2833e0b10af
SWARMD_CHANNEL_CLIENT_SECRET=replace-me
SWARMD_AGENT_ID=4a411d26-dec0-4553-a164-96ccecf0ecb9

The client derives channelId from clientId. If your OAuth client does not use the standard channel-{channelId} form, also pass the channel UUID as channelId.

Quick Start

Create one reusable client on the server:

// lib/swarmd.ts — server-only module
import { SwarmdChannelClient } from '@swarmd/channel-client';

export const swarmd = new SwarmdChannelClient({
  clientId: process.env.SWARMD_CHANNEL_CLIENT_ID!,
  clientSecret: process.env.SWARMD_CHANNEL_CLIENT_SECRET!,
});

Start a conversation and wait for the first reply:

import { extractReply } from '@swarmd/channel-client';
import { swarmd } from './lib/swarmd';

const state = await swarmd.startAndSend(
  process.env.SWARMD_AGENT_ID!,
  'Shortlist the top three candidates for JR-1007.',
);

console.log(state.contextId);       // persist for follow-up turns
console.log(state.aggregateState); // COMPLETED, REJECTED, FAILED, or CANCELED
console.log(extractReply(state));   // agent prose, including artifact output

startAndSend creates a conversation, sends the message, and polls if the relay has not completed during its early-return window.

Complete Next.js Example

This example starts with a standard TypeScript Next.js application and ends with a browser chat connected to a Swarmd channel.

1. Create the project

npx create-next-app@latest swarmd-chat --typescript --app
cd swarmd-chat
npm install @swarmd/channel-client

The example uses this structure:

swarmd-chat/
├── app/
│   ├── api/chat/route.ts
│   └── page.tsx
├── lib/
│   └── swarmd.ts
└── .env.local

2. Connect the channel

Create a channel in Swarmd, subscribe it to the agent your website should invoke, and copy:

• the channel clientId
• the channel clientSecret
• the subscribed agent’s agentId

Add them to .env.local. These variables deliberately have no NEXT_PUBLIC_ prefix, so Next.js keeps them on the server:

SWARMD_CHANNEL_CLIENT_ID=channel-d4ac7a03-e833-434f-badc-c2833e0b10af
SWARMD_CHANNEL_CLIENT_SECRET=replace-me
SWARMD_AGENT_ID=4a411d26-dec0-4553-a164-96ccecf0ecb9

3. Create the server-side client

// lib/swarmd.ts
import 'server-only';
import { SwarmdChannelClient } from '@swarmd/channel-client';

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

export const swarmd = new SwarmdChannelClient({
  clientId: required('SWARMD_CHANNEL_CLIENT_ID'),
  clientSecret: required('SWARMD_CHANNEL_CLIENT_SECRET'),
});

export const swarmdAgentId = required('SWARMD_AGENT_ID');

Exporting one client lets every request share the OAuth token cache.

4. Add the server route

The browser sends only the user’s message and its current contextId. The route creates the conversation on the first turn and reuses it on later turns.

// app/api/chat/route.ts
import { extractReply, SwarmdApiError } from '@swarmd/channel-client';
import { NextResponse } from 'next/server';
import { swarmd, swarmdAgentId } from '@/lib/swarmd';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const body = await request.json() as {
    message?: string;
    contextId?: string;
  };
  const message = body.message?.trim();

  if (!message) {
    return NextResponse.json(
      { error: 'message is required' },
      { status: 400 },
    );
  }

  try {
    const contextId = body.contextId ?? (
      await swarmd.createConversation(swarmdAgentId, {
        signal: request.signal,
      })
    ).contextId;

    const state = await swarmd.sendAndWait(contextId, message, {
      signal: request.signal,
      timeoutMs: 5 * 60_000,
    });

    return NextResponse.json({
      contextId,
      aggregateState: state.aggregateState,
      reply: extractReply(state),
      relayReason: state.latestTask?.metadata?.relay_reason,
    });
  } catch (error) {
    if (error instanceof SwarmdApiError) {
      return NextResponse.json(
        {
          error: 'Swarmd rejected the request',
          status: error.status,
          details: error.body,
        },
        { status: error.status },
      );
    }
    throw error;
  }
}

5. Call the route from the browser

// app/page.tsx
'use client';

import { FormEvent, useState } from 'react';

interface ChatReply {
  contextId: string;
  aggregateState: string;
  reply?: string;
  relayReason?: string;
}

export default function Home() {
  const [contextId, setContextId] = useState<string>();
  const [message, setMessage] = useState('');
  const [reply, setReply] = useState('');
  const [status, setStatus] = useState('Ready');

  async function send(event: FormEvent) {
    event.preventDefault();
    setStatus('Agent is working');

    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message, contextId }),
    });
    const result = await response.json() as ChatReply & { error?: string };

    if (!response.ok) {
      setStatus(result.error ?? 'Request failed');
      return;
    }

    setContextId(result.contextId);
    setReply(result.reply ?? 'No text reply');
    setStatus(result.aggregateState);
    setMessage('');
  }

  return (
    <main>
      <form onSubmit={send}>
        <input
          value={message}
          onChange={event => setMessage(event.target.value)}
          placeholder="Ask the agent..."
        />
        <button disabled={!message.trim()}>Send</button>
      </form>

      <p>Status: {status}</p>
      {reply && <p>{reply}</p>}
    </main>
  );
}

Run the project:

npm run dev

The first message creates a durable conversation. The response returns its contextId, and the component includes that ID in subsequent messages so the agent retains the conversation history.

This compact example keeps the /api/chat request open while the SDK polls. That is suitable for ordinary flows. If an approval may take minutes or hours, return the initial sendMessage state to the browser and expose a separate state endpoint, as shown in the split send-and-poll flow below.

Handle Lifecycle Events

For most integrations, onEvent is the idiomatic way to react to progress. Events are a discriminated union, so TypeScript narrows the available fields inside each case.

import type { ConversationEvent } from '@swarmd/channel-client';

function handleEvent(event: ConversationEvent) {
  switch (event.type) {
    case 'working':
      console.log('The agent is working');
      break;

    case 'hitl-held':
      console.log('Waiting for human review:', event.reason);
      break;

    case 'completed':
      console.log('Agent reply:', event.reply);
      break;

    case 'rejected':
      console.log('The reviewer rejected the action:', event.reason);
      break;

    case 'failed':
      console.error('The agent flow failed:', event.reason);
      break;

    case 'canceled':
      console.log('The conversation was canceled');
      break;

    default: {
      // Makes this switch fail type-checking if a future SDK version adds
      // an event and the application has not handled it.
      const exhaustive: never = event;
      return exhaustive;
    }
  }
}

const finalState = await swarmd.sendAndWait(contextId, message, {
  onEvent: handleEvent,
});

The callback fires for the initial send response and whenever the lifecycle event changes. Repeated polls in the same state are de-duplicated. Applications do not need to interpret HTTP 200 versus 202, inspect task status, or decide when polling should stop. Use the lower-level onState callback if you need every state snapshot instead.

Event	Useful fields	Meaning
working	state, contextId	The conversation is starting or executing
hitl-held	reason, state	A reviewer or caller must provide input
completed	reply, state	The flow completed and the reply was extracted
rejected	reason, state	A reviewer declined the held action
failed	reason, state	A policy or upstream error ended the flow
canceled	state	The caller canceled the flow

Every event includes the original ConversationState as event.state, so uncommon metadata and per-task progress remain available without weakening the common API.

Async event stream

Use sendEvents when events fit more naturally into an async pipeline or an SSE/WebSocket handler:

for await (const event of swarmd.sendEvents(contextId, message, {
  pollIntervalMs: 2_000,
  timeoutMs: 30 * 60_000,
})) {
  switch (event.type) {
    case 'working':
    case 'hitl-held':
      await publishProgressToBrowser(event);
      break;
    case 'completed':
      await publishReplyToBrowser(event.reply);
      break;
    case 'rejected':
    case 'failed':
    case 'canceled':
      await publishTerminalOutcomeToBrowser(event);
      break;
  }
}

The iterable ends automatically after a terminal event. watchConversation(contextId) provides the same event stream without sending a new message, which is useful when resuming a persisted conversation.

The package deliberately does not expose a React hook that talks directly to Swarmd: doing so would place the channel secret in the browser bundle. A React application should consume its own API route, SSE stream, or WebSocket and map these server-side lifecycle events into component state.

Split Send and Poll Flow

Use the low-level methods when your frontend needs to show WORKING or HITL_HELD immediately.

const created = await swarmd.createConversation(agentId);

const { state, pending } = await swarmd.sendMessage(
  created.contextId,
  'Apply the shortlist decision.',
);

if (!pending) {
  // state is already terminal
  return state;
}

const final = await swarmd.waitForTerminal(created.contextId, {
  pollIntervalMs: 2_000,
  maxPollIntervalMs: 10_000,
  timeoutMs: 30 * 60_000,
  onState(state) {
    if (state.aggregateState === 'HITL_HELD') {
      // Notify your UI, log progress, or persist resumable state.
      console.log(state.latestTask?.metadata?.relay_reason);
    }
  },
});

sendMessage uses aggregateState, not only the HTTP status, to decide whether work is pending. waitForTerminal stops on COMPLETED, REJECTED, FAILED, or CANCELED.

Handling UI States

aggregateState	Terminal	Suggested UI
UNKNOWN	No	Starting
WORKING	No	Agent is working
HITL_HELD	No	Waiting for human review
COMPLETED	Yes	Render extractReply(state)
REJECTED	Yes	Review was declined
FAILED	Yes	Request failed; inspect latestTask.metadata
CANCELED	Yes	Request was canceled

For HITL_HELD, inspect state.latestTask?.metadata?.relay_reason:

• HITL_HELD means a policy or action needs reviewer approval.
• HITL_HELD_AGENT_INPUT_REQUIRED means the agent requested human input.

Approval happens in Swarmd or through the approval API. The channel client continues polling and observes the result. Approval normally leads to COMPLETED; rejection leads to REJECTED.

Conversation Continuity

Create a conversation once per chat session and reuse its contextId:

const conversation = await swarmd.createConversation(agentId);

await swarmd.sendAndWait(conversation.contextId, 'Show open roles.');
await swarmd.sendAndWait(conversation.contextId, 'Only roles in London.');

The conversation remains durable on the relay. Store the contextId if polling must resume after a tab closes or a process restarts:

const state = await swarmd.getConversationState(savedContextId);
const final = state.aggregateState === 'WORKING'
  ? await swarmd.waitForTerminal(savedContextId)
  : state;

For long histories:

const page = await swarmd.listMessages(contextId, { page: 0, size: 50 });

Custom Messages and Cancellation

Send structured A2A parts instead of plain text:

await swarmd.sendMessage(contextId, '', {
  parts: [
    { kind: 'text', text: 'Review this application' },
    { kind: 'data', data: { applicationId: 'APP-001' } },
  ],
});

Cancel local waiting with an AbortSignal:

const controller = new AbortController();

const result = swarmd.waitForTerminal(contextId, {
  signal: controller.signal,
});

controller.abort(new Error('User left the page'));
await result;

This stops the local request or poll loop; it does not cancel server-side agent work.

Errors

import {
  SwarmdApiError,
  SwarmdAuthenticationError,
  SwarmdPollingTimeoutError,
} from '@swarmd/channel-client';

try {
  await swarmd.sendAndWait(contextId, message);
} catch (error) {
  if (error instanceof SwarmdAuthenticationError) {
    // Invalid client ID/secret or token endpoint configuration.
  } else if (error instanceof SwarmdPollingTimeoutError) {
    // Work is durable. Save error.contextId and resume polling later.
  } else if (error instanceof SwarmdApiError) {
    console.error(error.status, error.body);
    // A 400/403 body can include relay_reason: POLICY_BLOCKED.
  }
}

The client caches OAuth tokens until 30 seconds before expiry. If an API request returns 401, it clears the cached token, obtains a fresh token, and retries that request once.

Configuration

const swarmd = new SwarmdChannelClient({
  clientId: 'channel-d4ac7a03-e833-434f-badc-c2833e0b10af',
  clientSecret: '...',

  // Optional:
  channelId: 'd4ac7a03-e833-434f-badc-c2833e0b10af',
  baseUrl: 'https://api.swarmd.ai',
  tokenUrl: 'https://auth.swarmd.ai/realms/swarmd/protocol/openid-connect/token',
  scope: 'mcp:call',
});

Only override URLs or scope for a Swarmd environment whose operator supplied different values.

Method Reference

Method	Purpose
createConversation(agentId)	Start a durable conversation
sendMessage(contextId, text, options?)	Send one turn; return { state, pending }
getConversationState(contextId)	Read the current state once
waitForTerminal(contextId, options?)	Poll until a terminal aggregate
sendAndWait(contextId, text, options?)	Send a turn and poll when needed
startAndSend(agentId, text, options?)	Create, send, and poll in one call
sendEvents(contextId, text, options?)	Send and stream typed lifecycle events
watchConversation(contextId, options?)	Stream events for existing work
listMessages(contextId, options?)	Read paginated history
clearToken()	Force a fresh OAuth token on the next request

Legacy JSON-RPC Integrations

The Hotels demo originally implemented message/send and tasks/get directly over the channel JSON-RPC endpoint. It now consumes this SDK through the repository-local dependency file:../../sdks/typescript/packages/channel-client, so its deployed container continuously validates the same Conversation REST implementation customers receive. The Prismforce integration established the newer model: one stable contextId, aggregate state, and a state poll endpoint.

@swarmd/channel-client follows that model. Existing JSON-RPC integrations can remain in place, but new website integrations should use this library. See Frontend Integration (JSON-RPC — legacy) when maintaining an older integration.