Connecting a host

Each adapter returns a ChatHost (pick a host), so the page code stays the same wherever the agent runs:

<ChatProvider host={host}>
  <SessionList activeId={id} onSelect={setId} onNewSession={create} />
  <HostTranscript sessionId={id} />
  <HostInteractions sessionId={id} />
  <HostComposer sessionId={id} />
</ChatProvider>

Every adapter carries zidane's StreamEvents and merges them as the apps do. A markdown event with streaming: true, or a thinking event, extends the open block. Any other event is its own row. The reducer is applyLiveEvent from zidane-ui/adapters, built on zidane/chat/pure. The adapters keep their transcripts in the session stream store (SessionStreamStore from zidane-ui/chat/headless), the one the desktop app runs on. createSessionStreams wraps it with what a client of many concurrent sessions needs: per-session subscriptions, smooth streaming per (session, owner) on an injected frame scheduler, lazy scrollback (loadEarlier) and run-end compaction. Feed it a client's signals with apply and hand transcript(sessionId) to the components.

Runnable examples (scripted provider, no API key): examples/ui-in-process, examples/ui-sse, examples/ui-server.

In React, wrap once in SessionStreamsProvider streams={streams} (zidane-ui/chat) and read one session at a time: useSessionEvents, useSessionRunning, useSessionPage, useSessionRetry, useSessionFallbackModel, useSessionSystemMd, useSessionEventsSelector and useSessionEdits (the events that carry a file edit) subscribe to that session only, so a token on one session leaves the others' readers alone. useSessionStreamActions returns the store's writes as stable functions (createSessionStreamActions), and the usePeek… hooks read without subscribing, for event handlers.

In the page or a Web Worker#

createRunHost keeps sessions, transcripts and pending questions in memory and calls your run once per prompt. The host echoes the prompt, so run does not emit it.

import { createRunHost } from 'zidane-ui/adapters'

const host = createRunHost({
  async run({ prompt, emit, ask, signal }) {
    emit({ kind: 'markdown', text: 'Looking ', streaming: true })
    emit({ kind: 'markdown', text: 'it up.', streaming: true })
    emit({ kind: 'tool', tool: 'lookup', callId: 'c1', text: 'lookup(…)', input: { query: prompt } })
    emit({ kind: 'tool-result', tool: 'lookup', callId: 'c1', text: 'found it' })
    const answer = await ask(question) // an InteractionRequest; null when dismissed
    if (!signal.aborted)
      emit({ kind: 'markdown', text: answer ? 'Thanks.' : 'Never mind.', streaming: true })
  },
})

A follow-up waits for the current run to end, then runs as the next prompt. If run throws, the transcript gets an error row and the session ends with status error. Other options: sessions, transcripts (initial data), models, newId. The returned host also has restore(session, events), which adds a saved session with its history at the top of the list.

To keep the work off the main thread, run the same function in a Web Worker:

// agent.worker.ts
import { exposeRunHost } from 'zidane-ui/adapters'

exposeRunHost(run)

// main.ts
import { createWorkerHost } from 'zidane-ui/adapters'

const host = createWorkerHost(new Worker(new URL('./agent.worker.ts', import.meta.url), { type: 'module' }))

zidane's agent runtime does not load in a browser (sessions use AsyncLocalStorage, execution contexts use the file system), and a provider key does not belong in a page. So run is scripted or calls an API that you proxy. For a real agent, use a server adapter below.

Worker protocol#

The messages are plain postMessage objects, each with v: 1 and a type. A side that receives another version drops the message and logs a warning. Types: ToWorker, FromWorker from zidane-ui/adapters.

Your server, over HTTP and SSE#

createSseHandler is a Web-standard (request: Request) => Promise<Response> for Bun.serve, Deno, Hono or any fetch server. It runs createChatHost from zidane/chat (the engine of zidane-server and both apps) and streams its events to each watching client.

import { createLocalEnvironment, createSseHandler } from 'zidane-ui/server'
import { demoTools } from 'zidane-ui/server/testing'
import { anthropic } from 'zidane/providers'

const handler = createSseHandler({
  environment: createLocalEnvironment({ provider: anthropic(), tools: demoTools }),
  cwd: '/srv/agent-workspace',
  basePath: '/api/chat',
  authorize: request => isSignedIn(request),
})

Bun.serve({ port: 4380, idleTimeout: 0, fetch: handler })

environment is one of:

createScriptedProvider() from zidane-ui/server/testing is an offline, deterministic provider for demos and tests. It calls lookup once, then answers with the result.

In the browser:

import { createSseHost } from 'zidane-ui/adapters'

const host = createSseHost({ baseUrl: '/api/chat', headers: () => ({ authorization: `Bearer ${token()}` }) })

The client streams with fetch, so headers reach the stream request too. A transcript hydrates when first watched, then streams. After a drop it reconnects with Last-Event-ID, from 500 ms (reconnectMs) doubling to 10 s. A stream closes one second after nothing watches it.

The handler sets no CORS headers. Serve the page from the same origin, or proxy the requests as the example does.

SSE protocol#

This is version 1. Every response carries X-Zidane-Chat-Protocol: 1. Paths are relative to basePath, and bodies are JSON. Types: HydrateResponse, SendBody, StreamRecord, AnswerBody from zidane-ui/adapters.

Each stream record has id: <epoch>:<seq>, event: <type> and one data: line of JSON. seq counts one session's records from 1; epoch identifies the server process.

The handler keeps each watched session's transcript and its last replayLimit records in memory, and rebuilds history from the store with eventsFromTurns. It uploads attachments with a base64 data: URL and drops others. model (provider/model) applies to the session before sending.

Security#

The SSE handler runs the agent and its tools on your server, as the server's user.

• authorize runs first on every request. Make sure that it checks a session cookie or a bearer token. Use () => true only on a server bound to 127.0.0.1 that nobody else can reach.
• Every session runs in cwd. Clients cannot pick a directory. Point cwd at a directory that the agent is allowed to change, and give it only the tools it needs (demoTools is one read-only lookup).
• Every authorized user sees every session. To scope sessions per user, use one handler per tenant, or a store keyed by user.
• Put HTTPS in front and disable proxy response buffering (the handler sets X-Accel-Buffering: no for nginx).

zidane-server, over WebSocket#

createServerHost speaks zidane-server's protocol (JSON-RPC 2.0 over one WebSocket) through zidane's browser client, createServerClient (zidane/ipc/browser, re-exported here). It runs wherever a WebSocket does: a page, a worker, Node, Bun.

import { createServerHost } from 'zidane-ui/adapters'

const host = createServerHost({ url: 'wss://agent.example.com', token: 'zds_…' })
await host.ready

Other options: cwd (default: the server's first workspace root), appVersion (default 'web', shown in the server logs), WebSocket, fetch, reconnect ({ initialMs, maxMs }, default 500 doubling to 15 s, or false), heartbeatMs (default 20 s), connectTimeoutMs (default 10 s), onError. Or pass client, a createServerClient(…) to share with other hosts on the same server. The returned host also has client, connection (a readable store of the connection's state), refresh() (reads the session list again) and close().

Mint a token with the narrowest scope the page needs (chat to chat and answer tool approvals, admin for everything) and add the page's origin to the allowlist, which starts empty (an unlisted Origin gets a 403). Server clients compares it with the other clients.

zidane-server token create --name web --scope chat
ZIDANE_SERVER_ALLOWED_ORIGINS=https://app.example.com zidane-server start

Limits#

Tool approvals have their own host (ApprovalsHost, approvals). Only zidane-server has one: createServerApprovalsHost.

Reference#

zidane-ui/adapters, zidane-ui/server, zidane/chat.