@zaby-ai/aiui-core

Core protocol types, event definitions, Zod schemas, and transport helpers for the AIUI ecosystem. The wire contract is AG-UI-compatible by default, while Zaby-specific UI, voice, task, form, and collaboration events are exposed as additive extensions.

This package is server-safe: it has no React or DOM runtime dependency.

Install

npm install @zaby-ai/aiui-core

What's Inside

| Module | Description | |---|---| | events | Canonical EventType enum, typed event interfaces, legacy event-name normalizers, JSON Patch state delta schemas, and interrupt outcome types | | schema | Zod schemas for runtime validation of every protocol event | | protocol/ | Streaming helpers — SSE encoder/decoder, compact wire format, event transforms, signature verification, LiveKit bridge | | capabilities/ | Domain types — voice/TTS/STT, forms, canvas, blackboard, slides, assessments, whiteboards, tasks, research, playground, UI blocks | | sync/ | Collaborative state sync primitives | | client/ | Client-side protocol utilities | | devtools/ | Inspector log, metric, and trace event types |

Quick Start

import { EventType, type TextMessageContentEvent } from '@zaby-ai/aiui-core';

const event: TextMessageContentEvent = {
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: 'msg-1',
  delta: 'Hello, world!',
};

AG-UI Compatibility

@zaby-ai/aiui-core supports two protocol surfaces:

• Strict AG-UI events compatible with @ag-ui/[email protected].
• Zaby AIUI extension events for reusable UI blocks, voice, forms, tasks, research, playground, and other product-specific surfaces.

Use toAguiCoreEvent(event) when a consumer needs a strict upstream AG-UI stream. It returns null for Zaby-only extension events.

EventType values use canonical AG-UI-style wire names:

EventType.RUN_STARTED; // "RUN_STARTED"
EventType.TEXT_MESSAGE_CONTENT; // "TEXT_MESSAGE_CONTENT"
EventType.STATE_DELTA; // "STATE_DELTA"

Legacy AIUI event names such as TextMessageContent are normalized by normalizeEventType, normalizeEvent, and the SSE decoder:

import { EventDecoder, normalizeEvent } from '@zaby-ai/aiui-core';

normalizeEvent({ type: 'TextMessageContent', messageId: 'm1', delta: 'hi' });

const decoder = new EventDecoder();
const events = decoder.decodeAll('data: {"type":"TextMessageContent","messageId":"m1","delta":"hi"}\n\n');

State deltas use JSON Patch operations:

import { EventType, type StateDeltaEvent } from '@zaby-ai/aiui-core';

const delta: StateDeltaEvent = {
  type: EventType.STATE_DELTA,
  delta: [
    { op: 'replace', path: '/status', value: 'ready' },
    { op: 'remove', path: '/draft' },
  ],
};

Interrupt outcomes follow the AG-UI run-finished object shape:

{
  type: EventType.RUN_FINISHED,
  runId: 'run_123',
  threadId: 'thread_456',
  outcome: {
    type: 'interrupt',
    interrupts: [
      {
        id: 'approval_1',
        reason: 'Tenant approval is required before running this tool.',
        metadata: {
          type: 'tool_approval',
          toolName: 'search',
        },
      },
    ],
  },
}

Scripts

npm run build   # Build CJS + ESM + .d.ts via tsup
npm run dev     # Watch mode
npm run lint    # Type-check with tsc --noEmit

License

MIT