@nifrajs/ag-ui 3.2.0

package/README.md

@@ -0,0 +1,135 @@
+# @nifrajs/ag-ui
+
+Mount a nifra agent as an [AG-UI](https://docs.ag-ui.com) (Agent-User Interaction protocol) endpoint: one POST accepting `RunAgentInput`, a stream of AG-UI events out over SSE - run lifecycle, step and tool-call events projected from the runner's step evidence, text message events for the output, and a typed continuation for human-in-the-loop resume.
+
+A protocol bridge over [`@nifrajs/agent`](../agent) - the request body reuses core's single bounded, prototype-guarded trust boundary, and the model, durable state store, and approval transport are injected per request through the same `ports` factory `mountAgent` uses. Dependency-free beyond the two nifra peers.
+
+## Install
+
+```bash
+bun add @nifrajs/ag-ui @nifrajs/agent
+```
+
+## Mount
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountAgUI } from "@nifrajs/ag-ui"
+import { agent } from "./agent" // an AgentDefinition
+
+const app = server()
+mountAgUI(app, {
+  agent,
+  ports: (c) => ({
+    model: myModelPort,        // scope to the request subject
+    capabilities: ["search.read"],
+    state: myStateStore,       // required for resume
+  }),
+})
+// POST /agui - RunAgentInput in, AG-UI events out (SSE)
+```
+
+## Event mapping
+
+| Runner | AG-UI events |
+| --- | --- |
+| run starts | `RUN_STARTED`, then `CUSTOM { name: "nifra.turn" }` announcing the turn id |
+| tool evidence | `TOOL_CALL_START` / `TOOL_CALL_END`, then `TOOL_CALL_RESULT` whose `content` is the token-only outcome `{ "outcome": "committed" \| "failed" \| "denied", "code"? }` |
+| model, approval, budget, state evidence | `STEP_STARTED` / `STEP_FINISHED` |
+| model text deltas | live `TEXT_MESSAGE_START` / `_CONTENT` (see streaming below) |
+| model reasoning deltas | `REASONING_START` / `REASONING_MESSAGE_START` / `_CONTENT` / `_END` / `REASONING_END` |
+| model tool-args deltas | provisional `TOOL_CALL_START` + `TOOL_CALL_ARGS`, closed by the call's tool evidence |
+| shared state | `STATE_SNAPSHOT` on the seed and `STATE_DELTA` (RFC 6902 ops) per patch (see below) |
+| model usage deltas | summed per `(provider, model)` into the `usage: TokenUsage[]` array on `RUN_FINISHED` |
+| completed output | `TEXT_MESSAGE_START` / `_CONTENT` / `_END` (unless text was streamed), an optional `MESSAGES_SNAPSHOT` (see below), then `RUN_FINISHED` with `result` and `outcome: { "type": "success" }` |
+| completed with a typed error | `RUN_ERROR` |
+| suspended | `CUSTOM { name: "nifra.pending" }` with the continuation, then `RUN_FINISHED` with `outcome: { "type": "interrupt", "interrupts": [...] }` |
+
+Evidence-derived events carry the evidence `timestamp`. The runtime is token-only by design - `TOOL_CALL_RESULT` reports the outcome and error code, never the tool's payload.
+
+Agent input is `forwardedProps.input` when present, otherwise the content of the last `role: "user"` message.
+
+## Token streaming
+
+A model port that calls the request's optional `onDelta` callback (see `@nifrajs/agent`'s `AgentModelDelta`) streams live:
+
+- `{ kind: "text", text }` opens a `TEXT_MESSAGE` and streams each chunk as `TEXT_MESSAGE_CONTENT`. When any text was streamed, the terminal text block is suppressed - the streamed text IS the assistant message, so a streaming port must stream all user-visible text. A non-streaming port keeps the single terminal block; nothing changes for it.
+- `{ kind: "reasoning", text }` streams a `REASONING_*` message.
+- `{ kind: "tool-args", name?, argsText }` opens a provisional `TOOL_CALL_START` (id `<turnId>:call:<n>`) and streams `TOOL_CALL_ARGS`. The tool evidence that follows closes the same call - `TOOL_CALL_END` plus the token-only `TOOL_CALL_RESULT` - instead of opening a second one.
+- `{ kind: "usage", provider?, model?, inputTokens?, ... }` never becomes a frame. The counts are summed per `(provider, model)` across the run's model decisions and stamped as the spec `usage: TokenUsage[]` array on the terminal `RUN_FINISHED` (success and interrupt alike); non-finite figures are ignored.
+
+Each stream closes when a different delta kind starts, when tool evidence lands, or at the end of the run. Deltas are transient observer data: a `Last-Event-ID` replay carries evidence frames and the stored, unsuppressed terminal events only - the stored `RUN_FINISHED` keeps its `usage`.
+
+## Shared state
+
+The `ports` factory receives `(c, run)`; `run.sharedState` is the run's `AgentSharedState` channel and `run.turnId` the resolved turn id. `body.state` seeds the document and is announced with an upfront `STATE_SNAPSHOT`; every `patch` from a port or tool executor streams as `STATE_DELTA` carrying the RFC 6902 ops. A first patch on an unseeded document announces itself as a `STATE_SNAPSHOT` instead of a delta against a base the client never saw. The channel is per-run and transient - nothing in it is persisted.
+
+```ts
+mountAgUI(app, {
+  agent,
+  ports: (c, run) => ({
+    model: myStreamingModelPort(run.sharedState), // patch progress as the run advances
+    capabilities: ["search.read"],
+  }),
+})
+```
+
+With `emitMessagesSnapshot: true`, a successful run also emits `MESSAGES_SNAPSHOT` - the request's `messages` echoed back with the assistant output message appended - before `RUN_FINISHED`. It is off by default: the snapshot echoes client message payloads, and terminal events persist to the evidence log when one is configured.
+
+## Human-in-the-loop resume
+
+A suspended run finishes with `outcome: { "type": "interrupt", "interrupts": [interrupt] }` where the interrupt is:
+
+```jsonc
+{
+  "id": "<turnId>",
+  "reason": "approval",                    // approval | budget | model | cancelled | max_turns
+  "toolCallId": "<effectId>",              // present for tool suspensions
+  "responseSchema": { /* JSON Schema for the resume payload */ },
+  "metadata": { "turnId": "…", "continuation": { "kind": "approval", "tool": "…", "effectId": "…" } }
+}
+```
+
+Resume with the AG-UI `resume` array. The runtime keeps state token-only - it holds no interrupt registry - so the payload must echo `metadata.continuation`, with the suspended tool's input replayed in `continuation.input`:
+
+```jsonc
+{
+  "threadId": "thread-1", "runId": "run-2", "messages": [],
+  "forwardedProps": { "input": { "prompt": "go" } },
+  "resume": [{
+    "interruptId": "<interrupt id>",
+    "status": "resolved",                  // "cancelled" without an approval resumes as a denial
+    "payload": {
+      "continuation": { "kind": "approval", "tool": "search.read", "effectId": "…", "input": { "q": "…" } },
+      "approval": { "granted": true }
+    }
+  }]
+}
+```
+
+The pre-interrupt form - the same `{ continuation, approval? }` object in `forwardedProps.resume` plus `forwardedProps.turnId` - keeps working. A resume that fails validation is ignored and the POST starts a fresh run.
+
+## Resumable streams
+
+Pass an `evidenceLog` to make a dropped SSE connection resumable. Evidence-derived frames then
+carry SSE `id: <seq>`; a client reconnects by re-POSTing the same body with a `Last-Event-ID`
+header and receives the missed events, rejoining a still-running turn live or replaying the stored
+terminal events - the run is never re-executed.
+
+```ts
+import { createMemoryAgentEvidenceLog } from "@nifrajs/agent/events"
+
+mountAgUI(app, { agent, ports, evidenceLog: createMemoryAgentEvidenceLog() })
+```
+
+The in-memory log is the single-process dev/test reference; a durable, multi-process log is an
+adapter implementing the same `AgentEvidenceLog` interface.
+
+The seam performs no authentication or authorization - wrap it with your app's route guards and scope every port in `ports(c)` to the caller.
+
+## Docs
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `@nifrajs/ag-ui` - mount a nifra agent as an AG-UI (Agent-User Interaction protocol) endpoint.
+ *
+ * The package is a protocol bridge over the `@nifrajs/agent` runner, mirroring the `mountAgent`
+ * seam: one HTTP POST accepting the AG-UI `RunAgentInput` body, the bounded runner in the middle,
+ * a stream of AG-UI events out. The request body is read through core's single bounded,
+ * proto-guarded framing lane (`@nifrajs/core/edge-kit`); the model, durable state store, and
+ * approval transport arrive through a per-request `ports` factory and never live in this package.
+ *
+ * Wire contract (default path `/agui`):
+ * - `POST {path}` body `RunAgentInput` (`threadId` and `runId` required) -> SSE where each `data:`
+ *   field is one AG-UI event:
+ *   - `RUN_STARTED`, then `CUSTOM { name: "nifra.turn", value: { turnId } }` announcing the
+ *     runner's turn id.
+ *   - Step evidence maps to `TOOL_CALL_START`/`TOOL_CALL_END` for tool effects, followed by a
+ *     `TOOL_CALL_RESULT` whose `content` is the token-only outcome (`{ outcome, code? }` - the
+ *     runtime never carries tool payloads), and `STEP_STARTED`/`STEP_FINISHED` for everything
+ *     else. Evidence-derived events carry the evidence `timestamp`.
+ *   - A model port that streams (`request.onDelta`) turns into live token frames:
+ *     `TEXT_MESSAGE_START`/`_CONTENT` for text deltas, `REASONING_*` for reasoning deltas, and
+ *     `TOOL_CALL_START` + `TOOL_CALL_ARGS` for the tool call being formed - the following tool
+ *     evidence closes that same call (`TOOL_CALL_END` + `TOOL_CALL_RESULT`) instead of opening a
+ *     second one. When any text was streamed, the terminal `TEXT_MESSAGE_*` block is suppressed -
+ *     the streamed text IS the assistant message, so a streaming port must stream all
+ *     user-visible text. A non-streaming port keeps the single terminal
+ *     `TEXT_MESSAGE_START`/`_CONTENT`/`_END` block. `usage` deltas are summed per
+ *     `(provider, model)` across the run's model decisions and stamped as the spec's
+ *     `usage: TokenUsage[]` array on the terminal `RUN_FINISHED` event (success and interrupt
+ *     alike) - they never produce a frame of their own. Deltas are transient: a `Last-Event-ID`
+ *     replay carries evidence frames and the stored (unsuppressed) terminal events only - the
+ *     stored `RUN_FINISHED` keeps its `usage`.
+ *   - The `ports` factory receives `(c, run)` where `run.sharedState` is the run's
+ *     `AgentSharedState` channel: `body.state` seeds the document (announced as an upfront
+ *     `STATE_SNAPSHOT` when present), every `patch` streams as `STATE_DELTA` (RFC 6902 ops), and
+ *     a first patch without a seeded document announces itself as a `STATE_SNAPSHOT`.
+ *   - A completed run ends `RUN_FINISHED` with `result` and `outcome: { type: "success" }`, after
+ *     an optional `MESSAGES_SNAPSHOT` (see `emitMessagesSnapshot`); a failed one ends `RUN_ERROR`.
+ *   - A suspended run (approval, budget, model retry, max turns) emits
+ *     `CUSTOM { name: "nifra.pending", value: { turnId, reason, continuation } }` and then
+ *     `RUN_FINISHED` with `outcome: { type: "interrupt", interrupts: [{ id: turnId, reason,
+ *     toolCallId?, responseSchema, metadata: { turnId, continuation } }] }`. Resume with the
+ *     spec `resume` array - `[{ interruptId: turnId, status, payload: { continuation,
+ *     approval? } }]` where `payload.continuation` echoes `metadata.continuation` (the runtime is
+ *     stateless, so the client must send it back) - or with the legacy
+ *     `forwardedProps.resume` (`{ continuation, approval? }`) plus `forwardedProps.turnId`. A
+ *     `status: "cancelled"` entry without an explicit approval resumes as a denial. The runtime
+ *     keeps state token-only, so a suspended tool's input must be replayed in
+ *     `continuation.input`. A resume that fails validation is ignored and the POST starts a
+ *     fresh run.
+ * - Agent input is `forwardedProps.input` when present, otherwise the content of the last
+ *   `role: "user"` message.
+ * - With an `evidenceLog` configured, evidence-derived frames carry SSE `id: <seq>` and a dropped
+ *   connection is resumable: re-POST the same body with a `Last-Event-ID` header to replay the
+ *   missed events and rejoin the still-running turn - the run is never re-executed. Without the
+ *   log the header is ignored and every POST starts a run.
+ * - The seam performs no authentication or authorization. Wrap it with the app's own route guards,
+ *   and scope the store/model returned by `ports` to the caller.
+ */
+import { type AgentDefinition, type AgentPorts, type AgentSharedState } from "@nifrajs/agent";
+import { type AgentEvidenceLog } from "@nifrajs/agent/events";
+import { type ProtoPoisoning } from "@nifrajs/core/edge-kit";
+import type { StandardSchemaV1 } from "@nifrajs/core/schema";
+/** The structural slice of a route context the seam needs. */
+export interface AgUIRouteContext {
+    readonly req: Request;
+}
+/** The structural slice of a nifra server `mountAgUI` needs. */
+export interface AgUIMountableApp {
+    post(path: string, handler: (c: AgUIRouteContext) => Response | Promise<Response>): unknown;
+}
+/** Per-run context handed to the `ports` factory alongside the route context. */
+export interface AgUIRunContext {
+    /** The runner turn id this request resolves to (fresh run or resume target). */
+    readonly turnId: string;
+    /**
+     * The run's shared UI state channel. `body.state` seeds the document; patches applied by any
+     * port stream to the client as `STATE_SNAPSHOT`/`STATE_DELTA`. Transient - never persisted.
+     */
+    readonly sharedState: AgentSharedState;
+}
+export interface MountAgUIOptions<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1> {
+    readonly agent: AgentDefinition<InputSchema, OutputSchema>;
+    /** Endpoint path. Default `/agui`. */
+    readonly path?: string;
+    /** Bounded run length passed to the runner. */
+    readonly maxTurns?: number;
+    /** Maximum request body size in bytes. Default 1_000_000. */
+    readonly maxBodyBytes?: number;
+    /** Prototype-poisoning policy for the framing lane. Default `"reject"`. */
+    readonly protoPoisoning?: ProtoPoisoning;
+    /**
+     * Build the ports for one request - the model, durable state store, approval transport,
+     * capabilities, and budgets. Receives the route context so the caller can scope every port to
+     * the request subject, and the run context carrying the turn id and the shared UI state channel.
+     */
+    readonly ports: (c: AgUIRouteContext, run: AgUIRunContext) => AgentPorts | Promise<AgentPorts>;
+    /**
+     * Evidence log making the SSE stream resumable via `Last-Event-ID`. The in-memory reference
+     * (`createMemoryAgentEvidenceLog`) is single-process; a durable log is an adapter concern.
+     */
+    readonly evidenceLog?: AgentEvidenceLog;
+    /**
+     * Emit a `MESSAGES_SNAPSHOT` (the request's `messages` plus the assistant output message)
+     * before `RUN_FINISHED` on a successful completion. Default `false`: the snapshot echoes
+     * client-sent message payloads, and terminal events are persisted to the evidence log when one
+     * is configured - leave it off unless the client relies on an authoritative snapshot.
+     */
+    readonly emitMessagesSnapshot?: boolean;
+}
+/** Mount a single agent as an AG-UI `POST {path}` SSE endpoint. */
+export declare function mountAgUI<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1>(app: AgUIMountableApp, options: MountAgUIOptions<InputSchema, OutputSchema>): void;
+/**
+ * One aggregated token-usage entry in the spec's `RUN_FINISHED.usage` array: the model port's
+ * `usage` deltas summed per `(provider, model)` pair, matching AG-UI's `TokenUsage` shape.
+ */
+export interface AgUIRunUsage {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+    readonly reasoningTokens?: number;
+    readonly cachedInputTokens?: number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EACL,KAAK,eAAe,EAIpB,KAAK,UAAU,EAEf,KAAK,gBAAgB,EAStB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAEL,KAAK,cAAc,EAKpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAQ5D,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAA;CAC5F;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAA;CACvC;AAED,MAAM,WAAW,gBAAgB,CAC/B,WAAW,SAAS,gBAAgB,EACpC,YAAY,SAAS,gBAAgB;IAErC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;IAC1D,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC9F;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAA;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;CACxC;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CACvB,WAAW,SAAS,gBAAgB,EACpC,YAAY,SAAS,gBAAgB,EACrC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,IAAI,CAgBnF;AAyND;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CACpC"}