@zaby-ai/aiui-react

React agents, hooks, and UI components for AIUI streams and declarative surfaces.

Use this package when a tenant application needs to connect to Zaby agent runtime streams from the browser with a disposable runtime token. Token minting stays on your server; the browser only receives a short-lived runtime token and keeps it in memory.

Install

npm install @zaby-ai/aiui-react @zaby-ai/aiui-core

Install The shadcn Adapter

AIUI owns behavior and normalized component contracts; your application owns the rendered components and theme. After initializing shadcn in the application, install the AIUI adapter from the public registry:

npx shadcn@latest add https://raw.githubusercontent.com/ZABY-AI/aiui-react/main/registry/dist/aiui.json

Wrap the AIUI experience with the generated provider:

import { AiuiProvider } from '@/components/aiui';

export function App() {
  return <AiuiProvider><AgentScreen /></AiuiProvider>;
}

The generated adapter imports shadcn components from your application. It does not add shadcn as an AIUI runtime or peer dependency, so upgrades and visual customization stay under application control. Partial custom adapters are also supported through AiuiComponentsProvider; omitted primitives use the accessible fallback set. Import @zaby-ai/aiui-react/styles.css for AIUI layout and fallback structure.

Disposable Token Runtime

ZabyRuntimeAgent is a Zaby disposable-token runtime adapter that consumes AIUI-compatible streams from Zaby. It is not a replacement for every upstream AIUI client transport; it focuses on Zaby tenant applications using runtime tokens.

Production contract:

• runtimeToken must call your backend token route, not Zaby tenant APIs directly.
• Store the returned token in memory only. Do not put runtime tokens in localStorage, sessionStorage, cookies, URLs, logs, or analytics events.
• Your backend calls the Zaby provisioning API with a tenant provisioning API key.
• Rotate before expiry by sending the previous token, or by sending uniqueId plus tokenFamilyId from your backend session.
• Never expose tenant API keys, provisioning API keys, Cloudflare secrets, or signing secrets to the browser.

Customer backend route:

import { Zaby } from '@zaby-ai/sdk';

const zaby = new Zaby({ apiKey: process.env.ZABY_PROVISIONING_API_KEY! });

app.post('/api/zaby/runtime-token', requireUser, async (req, res) => {
  const token = await zaby.runtimeTokens.create({
    externalAppId: process.env.ZABY_EXTERNAL_APP_ID!,
    deploymentId: process.env.ZABY_AGENT_DEPLOYMENT_ID!,
    uniqueId: req.user.id,
    externalConversationId: req.body.conversationId,
    quotaPolicyId: req.user.runtimeQuotaPolicyId,
    metadata: { plan: req.user.plan },
  });

  res.json({
    token: token.token,
    expiresAt: token.expiresAt,
    tokenFamilyId: token.tokenFamilyId,
    rotateAfterSeconds: token.rotateAfterSeconds,
  });
});

import { useAgentChat, ZabyRuntimeAgent } from '@zaby-ai/aiui-react';

let runtimeTokenCache: {
  expiresAt: string;
  token: string;
  tokenFamilyId?: string;
} | null = null;

async function getRuntimeToken() {
  if (runtimeTokenCache) {
    const expiresAt = new Date(runtimeTokenCache.expiresAt).getTime();
    if (expiresAt - Date.now() > 120_000) return runtimeTokenCache.token;
  }

  const response = await fetch('/api/zaby/runtime-token', { method: 'POST' });
  if (!response.ok) throw new Error('Unable to mint runtime token');
  runtimeTokenCache = await response.json();
  return runtimeTokenCache.token;
}

const agent = new ZabyRuntimeAgent({
  baseUrl: process.env.NEXT_PUBLIC_ZABY_API_BASE_URL,
  runtimeToken: getRuntimeToken,
  threadId: crypto.randomUUID(),
});

export function AgentChat() {
  const chat = useAgentChat({ agent });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const form = new FormData(event.currentTarget);
        void chat.sendMessage(String(form.get('message') ?? ''));
        event.currentTarget.reset();
      }}
    >
      <ol>
        {chat.messages.map((message) => (
          <li key={message.id}>{message.content}</li>
        ))}
      </ol>
      <input name="message" />
      <button type="submit" disabled={chat.isLoading}>Send</button>
    </form>
  );
}

ZabyRuntimeAgent performs two browser-safe requests:

1. POST /api/v1/agent-runtime/runs with Authorization: Bearer <runtime-token>
2. GET /api/v1/agent-runtime/runs/{runId}/aiui with Accept: text/event-stream

The default API origin is https://genapi.zaby.io. Pass baseUrl when your tenant deployment uses a different configured gateway.

Custom Run Payloads

By default, the agent sends the latest user message plus full AIUI run context:

new ZabyRuntimeAgent({
  runtimeToken,
  createRunPayload: (input) => ({
    input: {
      message: input.messages.at(-1)?.content,
      messages: input.messages,
      state: input.state,
      tools: input.tools,
      context: input.context,
      forwardedProps: input.forwardedProps,
    },
    metadata: { source: 'tenant-app' },
  }),
});

Declarative Surfaces

SurfaceProvider owns the sequenced surface store and a trusted AiuiRendererRegistry. The built-in AIUI_BASIC_RENDERER_CATALOG provides renderers for every component in [email protected]; application kits register additional exact-version catalogs explicitly.

Renderer catalogs compose through declared manifest dependencies. A kit can reuse universal primitives and add its own trusted definitions without changing SurfaceRenderer or adding a component-type switch. Data bindings update local view state, while declared events are validated against the resolved action schema before emitting typed SurfaceAction objects with correlation IDs.

Image, audio, video, and poster URLs are denied by default. Provide SurfaceProvider.resolveMediaUrl to translate a declared media reference into a host-approved URL after applying scheme, origin, authorization, and proxy policy. Raw agent-provided URLs are never assigned directly to browser media elements.

Universal catalogs remain domain-neutral. Capability adapters provide structured data and actions rather than React elements. Consequential actions must be policy-checked and approved before execution. Arbitrary executable views are intentionally outside this declarative renderer and require a separate sandbox contract.

Native Human Intervention

useAgentChat handles canonical human-input requests, existing interruption events, interrupted run outcomes, reconnect replay, backend resolutions, and receipts. Requests are projected into their originating assistant message using parentMessageId; replay updates by requestId instead of appending another card.

const {
  pendingHumanInputs,
  submitHumanInput,
} = useAgentChat({ agent });

await submitHumanInput({
  requestId: pendingHumanInputs[0].request.requestId,
  decision: 'approve',
});

HttpAgent accepts humanInputUrl. ZabyRuntimeAgent accepts humanInputPath. Both submit the response through the agent runtime; they do not execute application mutations.

HumanInterventionCard renders approval-first actions through the consumer component adapter. Supply renderSubject for a trusted application preview. Unknown subjects fall back to inert declarative data. Backend receipts render inside the same card and conversation turn.

Frontend-registered actions may declare an ActionPolicy. Actions with approval: "always" are never executed at tool-call completion. Conditional actions default to requesting human input unless the host policy evaluator explicitly allows execution.

Progressive Smart Links

AiuiLinkProvider enriches HTTP(S) links across user messages, assistant responses, tool results, citations, sources, blocks, and workspace content. Links render immediately with a hostname and icon fallback; bare URLs upgrade to a resolved page title and approved favicon without delaying streaming. Explicit Markdown labels remain unchanged.

<AiuiLinkProvider
  resolver={(url, { source, signal }) => metadataClient.resolve({ url, source, signal })}
  allowUrl={(url) => url.protocol === 'https:'}
  resolveFaviconUrl={(url) => mediaProxy.approve(url)}
  onNavigate={(url, context, event) => {
    event.preventDefault();
    workspace.openBrowser({ url, source: context.source });
  }}
>
  <Chat agent={agent} />
</AiuiLinkProvider>

The React package never scrapes destination pages. Implement metadata retrieval on a trusted host service with redirect limits, response-size limits, DNS rebinding defenses, and blocking for loopback, private, link-local, reserved, and cloud metadata-service addresses. Do not forward cookies or ambient authorization. Favicon URLs remain untrusted until resolveFaviconUrl approves or proxies them. Without a provider, smart links remain ordinary network-free anchors.

Known file URLs are classified synchronously from their pathname and render with an authoritative file-family icon before metadata resolves. Built-in families cover PDF, documents, spreadsheets, presentations, archives, images, audio, video, source/configuration files, and text. Bare file URLs display their decoded filename; explicit labels remain unchanged. Query strings and fragments do not affect classification, and unknown extensions remain ordinary links.

Applications can extend or override classification with classifyFile. Return undefined to delegate to built-ins, an AiuiFileLinkInfo object to override, or null to explicitly treat the URL as a webpage:

<AiuiLinkProvider
  classifyFile={(url) => url.pathname.endsWith('.zaby')
    ? { family: 'file', extension: 'zaby', filename: 'Agent package' }
    : undefined}
>
  <Chat agent={agent} />
</AiuiLinkProvider>

Web Workspace Runtime

The web workspace keeps navigation, conversation, and host-rendered app views mounted as one accessible shell. Agents request views through validated intents; the host owns authorization, renderer registration, URL policy, focus, placement, dismissal, and every consequential action. A requested view never grants code execution or provider access.

Hosts advertise capabilities over aiui.workspace.capabilities, receive aiui.workspace.intent, return aiui.workspace.intent.result, and may restore aiui.workspace.state snapshots.

import {
  AgentWorkspace,
  WorkspaceProvider,
  createWebWorkspaceRegistry,
  createWorkspaceHostPolicy,
} from '@zaby-ai/aiui-react';
import '@zaby-ai/aiui-react/styles.css';

const registry = createWebWorkspaceRegistry()
  .registerResourceAdapter(resourceAdapter)
  .registerEnvironmentAdapter(environmentAdapter);

const policy = createWorkspaceHostPolicy({ allowEnvironmentAttach: true });

export function AgentScreen() {
  return (
    <WorkspaceProvider capabilities={capabilities} registry={registry} policy={policy}>
      <AgentWorkspace
        navigation={<AppNavigation />}
        title="Current task"
        messages={<Conversation />}
        draft={draft}
        onDraftChange={setDraft}
        onDictate={speechInput.toggle}
        dictationState={speechInput.state}
        onSend={sendMessage}
      />
    </WorkspaceProvider>
  );
}

A resource adapter resolves a typed reference to text, bytes, structured data, or a host-approved URL and may implement revision-aware writes. An environment adapter attaches an existing terminal/browser/preview session, exposes only declared commands and typed events, honors abort signals, and disposes exactly once when released. Register overlapping adapters only when resolution remains unambiguous.

The built-in trusted views cover declarative surfaces, resources, review diffs, tasks, terminal sessions, browser/preview sessions, and a safe unsupported-view fallback. WorkspaceShell provides sibling navigation, conversation, persistent summary rail, and artifact panel regions. AgentWorkspace composes the task header, persistent message viewport, tool and source disclosures, outputs, background activity, attachments, access/runtime controls, and composer.

The summary rail groups outputs, background processes, and sources while the independent artifact panel opens and closes. Pass summaryRail to replace the built-in WorkspaceSummaryRail with an application-specific summary. Speech input is host-controlled: onDictate toggles the host STT adapter, while dictationState drives accessible idle, listening, processing, and error states. AIUI does not send microphone audio or choose a transcription provider.

Existing surface.create.display remains a hint for rendering a declarative surface. Workspace intents separately control host shell lifecycle such as open, reuse, focus, panel layout, and close.

This milestone attaches only host-created environments. Environment provisioning, permission elevation, signed custom-app execution, privileged iframe bridges, CSP negotiation, and network permission manifests remain a later isolated runtime.

Exports

• ZabyRuntimeAgent for disposable-token Zaby runtime streams
• HttpAgent for direct AIUI-compatible HTTP/SSE endpoints
• useAgentChat for React chat state, streaming messages, tools, UI blocks, activities, and state deltas
• applyStateDelta for JSON Patch state updates
• Chat UI components: Chat, InputArea, MessageList, and AiuiBlockRenderer
• Surface runtime: SurfaceProvider, SurfaceRenderer, AiuiRendererRegistry, and AIUI_BASIC_RENDERER_CATALOG
• Web workspace: WorkspaceProvider, WorkspaceShell, AgentWorkspace, trusted workspace views, policies, registries, and adapters

Scripts

npm test
npm run lint
npm run build

License

MIT