Chat UI: client, useChat & AG-UI

The server already exposes every agent over REST and SSE. What is left is the client half, and there is no single right answer: some apps want a typed client, some already run useChat, some plug into an existing AG-UI surface. All three read the same stream.

One concern is shared by all of them and is worth stating up front. A durable tool can return an internal sentinel instead of a result — the run suspended for approval, or a guard blocked the call. Those carry internal fields and are not a wire contract, so they must never reach a browser verbatim. The masking that replaces them lives in one helper shared by the live stream and by history reconstruction, so the two cannot drift.

GnlClient wraps the server's endpoints: listAgents, run, resume (same runId plus approvals — the suspended tool is released), stream as an async generator, streamTo with handler callbacks, plus listRuns and getRun for the journal timeline. It is framework-agnostic; @gnldev/client/react adds hooks.

import { GnlClient } from '@gnldev/client';

const client = new GnlClient({
  baseUrl: 'http://localhost:3000/api',
  headers: { authorization: `Bearer ${token}` },
});

const { runId } = await client.run('support', { prompt: 'Where is my order?' });

for await (const ev of client.stream('support', { runId, prompt: 'and the refund?' })) {
  if (ev.event === 'text-delta') process.stdout.write(ev.data.text);
}

// an approval came back from the operator — same runId, the suspended tool is released
await client.resume('support', runId, { 'call-7': true });

The React entry point exposes useGnlAgent and a useChat hook built on the client's own accumulator, so message state is assembled for you.

import { useChat, useGnlAgent } from '@gnldev/client/react';

const { messages, send, streaming } = useChat(client, 'support');

If your UI already runs the AI SDK's useChat (v5), this package speaks its protocol. toUIMessageStreamResponse turns a durable run into a UI message stream, and createChatRoute gives you the endpoint in one line.

toUIMessages is the other half: it rebuilds the message history from the journal, so a page reload does not lose the conversation — the transcript is reconstructed from what actually happened, not from client-side state. An interrupt surfaces as a data-gnl-interrupt chunk, which is how the UI knows to render an approval prompt instead of a result.

import { createChatRoute, toUIMessages } from '@gnldev/chat-adapter';

app.route('/chat', createChatRoute(config, { agent: 'support' }));

// restore the conversation after a reload — rebuilt from the journal
const history = await toUIMessages(journal, runId);

AG-UI is the protocol CopilotKit and several other front-ends speak. createAguiRoute exposes a single endpoint an AG-UI HttpAgent can post to; pipeAguiStream is the lower-level piece, converting the run's stream into AG-UI events. The package defines the event types itself and takes no @ag-ui/* dependency.

import { createAguiRoute } from '@gnldev/agui';

app.route('/agui', createAguiRoute(config));
// POST /agui/agents/support/run — an AG-UI HttpAgent can consume this directly