@aseity/agent-ui-protocol

Shared Zod schemas and TypeScript types for agent UI event streams and interaction responses.

pnpm add @aseity/agent-ui-protocol zod

import {
  UIEvent,
  type UIEvent as UIEventType,
} from '@aseity/agent-ui-protocol';

The package is intended to be consumed by both the API and UI so the streaming event and interaction contracts stay aligned.

Persisted assistant messages in SessionMessages may include an optional error using the same ProtocolError shape as turn_end: code, message, and optional max_attempts. An empty message is valid and is preserved during parsing. Messages without error remain valid; parsing does not invent a failure reason.

session_event optionally carries current_turn (or null when idle): { turnId, status, pendingInteractions: [{ interactionId, data }] }. Its status is running or a TurnStopStatus; hosts map waiting and stopping to running. Interaction data uses InteractionRequestData. The event type list is unchanged. TurnStopStatus and historical TurnStatus now also accept interrupted.

Workspace artifacts

The host emits turn_artifacts after collecting a turn's workspace artifacts and before turn_end. The event name, turn identity and collection timing are unchanged:

{
  type: 'turn_artifacts',
  turn_id: 'turn_1',
  artifacts: [
    { entryPath: 'reports/index.html', artifactType: 'webpage' },
    { entryPath: 'slides/index.html', artifactType: 'presentation' },
  ],
}

ArtifactReference contains a nonempty entryPath and an artifactType of document, webpage, presentation, spreadsheet or image. The host supplies the full relative entry path within the session workspace. Identity is scoped to the session: the same path in another session identifies a different artifact. Paths are kept intact; matching filenames in different directories are distinct.

The store replaces the referenced turn's collection and deduplicates by full entryPath, retaining the last reference for a repeated path. An empty array clears that turn's collection. The same path can appear independently in multiple turns. AssistantMessage.artifacts and SessionTurnSummary.artifacts preserve these references through history loading and pagination, including turns with no assistant text. Hydration applies the same per-turn deduplication as event replay.

References identify current workspace files, not library entries or content snapshots. The host resolves content and access permissions; the SDK does not save files to a library or define preview routes.

Migrating from 0.6.x

Upgrade @aseity/agent-ui-protocol and @aseity/agent-chat-react together to 0.7.0. Replace { id } in events and historical turn summaries with { entryPath, artifactType }; the old shape is no longer supported. Attachments and other message fields are unchanged.

The SDK's transport reads history afresh on every listMessages call and has no persistent history cache or cache format version. Hosts that cache history must bump their own cache/projection format version and discard old { id } data before hydrating the store, including when protocol validation is disabled. The default transport validation rejects legacy references; it does not migrate them. Harnex must upgrade its server history projection and client cache together.