@zaby-ai/aiui-core

Core protocol types, event definitions, schemas, surface contracts, and transport helpers for the AIUI ecosystem. AIUI combines streaming agent events with a validated, declarative runtime UI model.

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 | | registry/ | Versioned component, action, entity, view, permission, and catalog definitions | | surfaces/ | Surface compiler, sequenced store, data binding, JSON Patch state, and legacy normalization | | workspace/ | Host-controlled workspace intents, results, capabilities, snapshots, and deterministic shell state | | 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!',
};

Wire Contract

AIUI event streams use stable uppercase event names for lifecycle, text, reasoning, tools, state, activity, and control messages. Product capabilities are additive typed events on the same transport.

EventType values are the canonical 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 are represented on run-finished events:

{
  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',
        },
      },
    ],
  },
}

Native Human Intervention

AIUI uses HUMAN_INPUT_REQUESTED and HUMAN_INPUT_RESOLVED for durable human-in-the-loop workflows. The request envelope owns lifecycle correlation, response validation, actions, policy hints, and an opaque application subject. Applications retain ownership of the subject type and data.

An interrupted run emits the request before finishing with outcome.type: "interrupt". A later resolution carries the same requestId, an idempotent decisionId, and an optional backend receipt. Existing interruption objects can be converted with toHumanInputRequest.

const event: HumanInputRequestedEvent = {
  type: EventType.HUMAN_INPUT_REQUESTED,
  request: {
    requestId: 'approval-1',
    runId: 'run-1',
    threadId: 'thread-1',
    turnId: 'turn-1',
    parentMessageId: 'assistant-1',
    kind: 'approval',
    status: 'pending',
    title: 'Review proposed effect',
    subject: {
      type: 'com.example.proposed-effect',
      referenceId: 'effect-1',
      revision: 'rev-1',
      data: { preview: 'Application-owned declarative data' },
    },
    responseSchema: { type: 'object' },
    actions: [
      { id: 'approve', label: 'Approve', intent: 'approve' },
      { id: 'reject', label: 'Reject', intent: 'reject' },
    ],
    policy: { mode: 'ask', requiresExplicitResponse: true },
    createdAt: new Date().toISOString(),
  },
};

Runtime Catalogs

AIUI_BASIC_CATALOG_MANIFEST contains 18 domain-neutral primitives for content, media, layout, collections, navigation, input, actions, and feedback. A surface references an exact catalog version and declares a component tree, bindings, events, and sequenced state patches. SurfaceCompiler rejects unsupported catalogs, invalid props, undeclared actions, unsafe bindings, slot violations, duplicate nodes, cycles, and unreachable nodes before render. Catalog dependencies are resolved as one complete version graph so every selected version satisfies every consumer.

Universal catalogs define domain-neutral behavior only. Application kits extend catalog manifests with schemas and actions; they do not modify the core protocol or add application branches to the renderer. Capability adapters return structured data and action results, never React elements.

Consequential actions carry explicit effect, reversibility, approval, scope, idempotency, and audit policy. Irreversible external actions always require approval before provider execution. JSON Pointer writes reject prototype-mutation tokens and preserve array structure. Custom executable views are outside the declarative catalog and require a separate sandbox contract.

Web Workspace Runtime

The workspace protocol lets an agent request a view while the host remains authoritative over policy, placement, focus, rendering, and dismissal. An intent is a request, not permission to execute code or access a resource. Hosts validate the intent, apply local policy, and return the actual correlated result.

The custom event names are stable:

| Event | Purpose | |---|---| | aiui.workspace.capabilities | Host-supported versions, view kinds, placements, features, and limits | | aiui.workspace.intent | Correlated agent request to present, open, focus, dismiss, resize, or attach | | aiui.workspace.intent.result | Host acceptance, completion, rejection, or failure | | aiui.workspace.state | Validated deterministic workspace snapshot |

import type { WorkspaceHostCapabilities } from '@zaby-ai/aiui-core';

const capabilities: WorkspaceHostCapabilities = {
  protocolVersions: ['v1'],
  viewKinds: ['aiui.resource', 'aiui.environment.terminal'],
  regions: ['sidePanel'],
  modes: ['tab'],
  features: ['tabs', 'resourceOpen', 'environmentAttach', 'stateSnapshots'],
  maxOpenSurfaces: 8,
};

A server can request a host-rendered resource without naming a renderer implementation:

const intentId = await session.requestWorkspaceIntent({
  type: 'workspace.resource.open',
  resource: { resourceId: 'artifact-1', type: 'aiui.document' },
  viewKind: 'aiui.resource',
  reuseKey: 'artifact:1',
  presentation: { region: 'sidePanel', mode: 'tab', focus: 'request' },
});

React hosts pair WorkspaceProvider with WorkspaceShell or AgentWorkspace, register trusted view implementations, and return intent results to the agent transport. Resource adapters resolve WorkspaceResourceReference values into host-approved payloads. Environment adapters may attach only to an existing WorkspaceEnvironmentReference and must dispose their session when its surface closes.

Existing surface.create.display values remain renderer hints for declarative surfaces. Workspace intents are the separate host-shell lifecycle contract for tabs, focus, panel layout, resources, and environment attachment.

Environment provisioning, permission elevation, signed custom-app execution, privileged iframe bridges, CSP negotiation, and network permission manifests are outside this browser milestone.

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