agent-proxy-kit

agent-proxy-kit is an open-source TypeScript package by swyxio that extracts the long-running operation UX work from the SoloChat project into a reusable, provider-agnostic library. It translates raw streaming events from OpenAI, xAI, Gemini, Featherless, Ollama, and other OpenAI-compatible providers into a stable OperationStage contract that any UI can consume. The library is intentionally thin, designed to sit inside an agent proxy without imposing a heavy framework.

What It Is

agent-proxy-kit is a provider-event bridge for LLM streaming UIs. When agents make long-running hosted calls — web searches, tool invocations, reasoning loops — users typically see a vague spinner with no real feedback. This library solves that by surfacing the real signals providers already emit: lifecycle events, tool call events, reasoning deltas, grounding metadata, and finish reasons. It normalizes these into a consistent OperationStage format so developers can render progress bars, elapsed time, stage history, and status labels without writing per-provider parsing logic.

How the Provider Bridge Works

The core abstraction is createProviderStageTracker, which accepts a provider name, model, and start timestamp, then exposes methods to convert raw stream chunks into typed stage events. The library ships three main normalizers:

• OpenAI / xAI Responses API: handles lifecycle events, hosted search/tool events, reasoning deltas, text deltas, completion, and failure events via fromResponsesEvent.
• Gemini: handles thought parts, visible text parts, usage metadata, grounding metadata, URL context, function calls, and code execution parts via normalizeGeminiChunk.
• OpenAI-compatible Chat Completions (e.g., Featherless, Ollama): handles reasoning fields, visible deltas, usage chunks, and finish reasons via normalizeChatCompletionChunk.

The design rule stated in the README is: show real provider events first, synthesize conservative milestones from stream deltas second, and use heartbeats only after quiet gaps.

Operation Snapshots

Beyond raw stage events, the library provides an operationSnapshot utility that aggregates a list of stages into a structured object suitable for rendering progress bars, elapsed time, estimated completion, the latest stage label, and an expandable history view. Snapshots take an operation ID, kind, start timestamp, and accumulated stages array.

Included Codex Skill

The package ships a reusable Codex skill file at skills/agent-proxy/SKILL.md. This is intended as an implementation standard that developers can reference when adding long-running LLM UX to any application, making the library useful not just as a runtime dependency but also as a specification artifact for AI-assisted coding workflows.

Current Status

The repository was created on May 19, 2026 and last updated on May 20, 2026, indicating it is a very new project. It is published to npm as agent-proxy-kit and is available under the MIT License. The project has 2 stars and 1 fork on GitHub at the time of indexing.