Skip to content

feat(ag-ui): @cacheplane/ag-ui adapter wrapping @ag-ui/client#139

Merged
blove merged 7 commits into
mainfrom
feat/ag-ui-adapter
Apr 27, 2026
Merged

feat(ag-ui): @cacheplane/ag-ui adapter wrapping @ag-ui/client#139
blove merged 7 commits into
mainfrom
feat/ag-ui-adapter

Conversation

@blove
Copy link
Copy Markdown
Contributor

@blove blove commented Apr 27, 2026

Summary

  • New `@cacheplane/ag-ui` library: `toAgent(source: AbstractAgent): Agent` primitive + `provideAgUiAgent({ url })` DI convenience.
  • Pure-function reducer (`libs/ag-ui/src/lib/reducer.ts`) maps AG-UI `BaseEvent`s into Agent contract signals + `events$`. 15 table-driven tests cover every variant.
  • Conformance-tested against `runAgentConformance` from `@cacheplane/chat` — same suite the LangGraph adapter passes.
  • Scope: messages + lifecycle + tool calls + state. `interrupt`, `subagents`, `history` deferred.
  • Cockpit demo `cockpit/ag-ui/streaming/angular/` mirrors the langgraph streaming cockpit.

Motivation

Validates the chat-runtime decoupling shipped in #131..#138 by adding a second adapter on a fundamentally different protocol. `@cacheplane/chat` remains independent of both adapters.

Notable adaptations from plan

  • `@ag-ui/client@0.0.52`'s `AbstractAgent` exposes `subscribe({ onEvent, onRunFailed })` and `run(input)` (not `agent()` + signal-on-runAgent as the plan sketched). Adapter calls `source.addMessage()` for optimistic user-message sync, then `source.runAgent()`. `stop()` calls `source.abortRun()`.
  • Reducer uses `as unknown as` casts around per-event field access — Zod-inferred BaseEvent narrowing doesn't compose with TS type assertions otherwise.

Test Plan

  • `nx run-many -t lint,test,build -p chat,langgraph,ag-ui` passes
  • Dep graph: `chat` independent; both `langgraph` and `ag-ui` point to `chat` only
  • Reducer 15 tests + toAgent 5 tests + conformance suite + provideAgUiAgent 5 tests — all green
  • Cockpit demo renders against a live AG-UI backend (manual; relative `/agent` URL needs proxy/rewrite configuration per environment)

Design + plan

  • Spec: `docs/superpowers/specs/2026-04-27-ag-ui-adapter-design.md`
  • Plan: `docs/superpowers/plans/2026-04-27-ag-ui-adapter.md`

🤖 Generated with Claude Code

blove and others added 7 commits April 27, 2026 09:28
New @cacheplane/ag-ui package wraps @ag-ui/client AbstractAgent into
the runtime-neutral Agent contract. Scope B: messages + lifecycle +
tool calls + state. toAgent(source) primitive + provideAgUiAgent({url})
DI convenience. Pure-function reducer; conformance test against shared
suite. Cockpit demo proves end-to-end decoupling.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
6 tasks: scaffold @cacheplane/ag-ui lib, pure-function reducer with
table-driven spec, toAgent + conformance test, provideAgUiAgent DI
convenience, cockpit streaming demo, final verify + PR. Pinned to
@ag-ui/client and fast-json-patch (RFC 6902 for StateDelta).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Mirror libs/langgraph/ structure. Stubbed toAgent and provideAgUiAgent
will be implemented in subsequent commits.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Implements reduceEvent(event, store) covering RUN_STARTED/FINISHED/ERROR,
TEXT_MESSAGE_START/CONTENT/END, TOOL_CALL_START/ARGS/END/RESULT,
STATE_SNAPSHOT/DELTA, MESSAGES_SNAPSHOT, and CUSTOM. Discriminates
state_update CustomEvents into AgentStateUpdateEvent. Table-driven tests
cover every variant.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Subscribes to source via AgentSubscriber.onEvent and reduces every event
into the produced Agent's signals. submit() optimistically appends user
message to both our signals and source.addMessage(), then calls
source.runAgent(). stop() calls source.abortRun(). Conformance suite
validates the AG-UI adapter passes the same contract assertions as the
LangGraph adapter.

Also fixes reducer.ts type casts (as unknown as) required by @ag-ui/client
0.0.52 which uses Zod-inferred BaseEvent types that do not overlap with
narrower cast targets without the intermediate unknown step.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Constructs HttpAgent from config and wires it through toAgent into the
AG_UI_AGENT injection token. Convenience entry point for the common case;
custom transports go through toAgent(customAgent) directly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Mirrors cockpit/langgraph/streaming/angular/ structure. Demonstrates
the chat-runtime decoupling: same <chat> composition, AG-UI runtime
instead of LangGraph.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 27, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
cacheplane Ready Ready Preview, Comment Apr 27, 2026 3:37pm
cacheplane-minting-service Ready Ready Preview, Comment Apr 27, 2026 3:37pm

Request Review

@blove blove merged commit b03c90d into main Apr 27, 2026
15 checks passed
@blove blove deleted the feat/ag-ui-adapter branch May 7, 2026 16:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant