@agent-os/ag-ui

Purpose

Framework-neutral AG-UI wire projection for typed agentOS runtime events and AgentSchema tool declarations.

Public API Status

0.5.x active development. Public exports are listed in PUBLIC_API.md to prevent accidental exports; they are not frozen.

Invariant

AG-UI frames are edge protocol projections. They never write ledger facts, replace agentOS tool algebra, or become runtime source truth.

Minimal Usage

Decode AG-UI run input at unknown boundaries with the package-owned Effect Schema:

import { AgUiRunAgentInputSchema, decodeAgUiRunAgentInput } from "@agent-os/ag-ui";

Project committed ledger events into AG-UI frames or cursor-preserving envelopes through owner-owned safe event projectors:

import { projectLedgerEventsToAgUiFrames, decodeLedgerEventToAgUiEnvelope } from "@agent-os/ag-ui";

agentOS-owned events enter AG-UI through package-owned SafeLedgerEvent projectors from @agent-os/runtime-protocol, @agent-os/workspace-job, and @agent-os/workspace-op. Product-owned events must provide their own safeEventProjectors; AG-UI does not select raw ledger payload fields.

Use projectToolToAgUiTool to expose AG-UI tool declarations generated from AgentSchema.projections.agUi.

Use projectAgUiFramesToActivities for a neutral activity feed. React and Svelte adapters consume that projection without parsing ledger payloads.

Verification

cd packages/wire-adapters/ag-ui
vp test run