@hsb3/carbon-agui-adapter 0.1.0 → 0.2.0

package/README.md

@@ -1,26 +1,34 @@
 # carbon-agui-adapter
 
-Drives IBM **Carbon AI Chat** (`@carbon/ai-chat`) from an **AG-UI** event stream. Zero runtime deps.
+Drives IBM **Carbon AI Chat** (`@carbon/ai-chat`) from an **AG-UI** event stream.
+
+One runtime dependency (`@ag-ui/core`, for event schemas). `@carbon/ai-chat` is a
+devDependency only — the consuming app owns its own Carbon version.
 
 - Carbon `customSendMessage` → AG-UI `RunAgentInput` (thread + history + tools + state)
 - AG-UI events → Carbon `addMessageChunk` (`partial_item` / `complete_item` / `final_response`)
-- Keeps thread history and shared state across turns; applies `STATE_DELTA` JSON Patches
+- Keeps thread history and shared state across turns; applies `STATE_DELTA` as full RFC 6902 JSON Patch
 - Tool calls → Carbon **chain-of-thought** steps (`message_options.chain_of_thought`) with args/result/status
 - Cancel via Carbon's `AbortSignal`; `RUN_ERROR` throws so Carbon shows the retry UI
-- `test/carbon-compat.ts` typechecks the adapter against the real `@carbon/ai-chat` (1.19) types
+- LangGraph interrupts → an approve/reject/edit decision card; `respondToInterrupt` resumes the same thread
+- `CUSTOM` `carbon.item`/`carbon.items` events → native Carbon items (the generative-UI seam)
+- Validated at both seams at runtime: AG-UI events via `@ag-ui/core` schemas, Carbon items via an allowlist
+- `test/carbon-compat.ts` typechecks the adapter against the real `@carbon/ai-chat` types (version pinned: see `docs/SPEC.md` §3)
+- `bun run coverage` prints the AG-UI x Carbon matrix and exits nonzero on any gap
 
 ## Run
 
 ```bash
-npm install
-npm run check      # typecheck + tests
-npm run build      # dist/
+bun install
+bun run check      # typecheck + tests
+bun run coverage   # AG-UI x Carbon coverage matrix; must exit 0
+bun run build      # dist/
 ```
 
 ## Use
 
 ```ts
-import { createAgUiSendMessage, createSseRunner } from 'carbon-agui-adapter';
+import { createAgUiSendMessage, createSseRunner } from '@hsb3/carbon-agui-adapter';
 
 const config = {
   messaging: {
@@ -34,6 +42,8 @@ const config = {
 };
 ```
 
+`createSseRunner` also takes `fetch` (inject your own) and `onParseError(raw, err)` — a `data:` frame that is not valid JSON is reported there and skipped, never thrown, so the rest of the stream survives.
+
 Need history/state/reset access? Use the class:
 
 ```ts
@@ -46,7 +56,7 @@ Using `@ag-ui/client` instead of raw SSE:
 
 ```ts
 import { HttpAgent } from '@ag-ui/client';
-import { fromObservable } from 'carbon-agui-adapter';
+import { fromObservable } from '@hsb3/carbon-agui-adapter';
 
 const agent = new HttpAgent({ url: 'https://my-agent/run' });
 const run = (input, { signal }) => fromObservable(agent.run(input), signal);
@@ -65,24 +75,44 @@ const run = (input, { signal }) => fromObservable(agent.run(input), signal);
 | `RUN_ERROR` | throws `AgUiRunError` |
 | `RUN_FINISHED` (no outcome) / stream end / abort | `final_response` (aborted text gets `stream_stopped: true`) |
 | `RUN_FINISHED` with `outcome.type === 'interrupt'` | `user_defined` decision item (`InterruptDecisionData`); interrupt retained for resume |
+| `RUN_FINISHED`, no interrupts, `detectClarification` accepts the state | `user_defined` question item (`ClarificationData`) + `onClarification`; no interrupt state touched |
 | `MESSAGES_SNAPSHOT` with a new assistant message | rendered as a `text` item (covers non-streaming graphs, e.g. a resume continuation) |
-| `RUN_STARTED`, `STEP_*`, `RAW`, `CUSTOM` | `onEvent` only |
+| `RUN_STARTED`, `STEP_*`, `SUBAGENT_*`, `RAW`, `CUSTOM` | `onEvent` only |
 
 ## HITL: interrupt → approve/reject/edit → resume
 
 A LangGraph interrupt (via `ag-ui-langgraph`, `emit_interrupt_outcome=True`) arrives on
-`RUN_FINISHED.outcome`. The adapter emits a Carbon `user_defined` item carrying
-`InterruptDecisionData` (`kind: 'interrupt'`, `interruptId`, `message`, `action`, `args`,
-`responseSchema`, `toolCallId`) so a host renderer can draw a decision card, and retains the
-interrupt on `adapter.pendingInterrupt`. The host resolves it:
+`RUN_FINISHED.outcome`. The adapter emits one Carbon `user_defined` item per interrupt in
+that outcome, carrying `InterruptDecisionData` (`kind: 'interrupt'`, `interruptId`,
+`message`, `action`, `args`, `responseSchema`, `toolCallId`) so a host renderer can draw a
+decision card, and retains **every** interrupt awaiting its resume in
+`adapter.pendingInterrupts` (keyed by id, arrival order) — a later interrupt is added,
+never assigned over an unanswered one, and a repeat of an id already pending is ignored.
+`adapter.pendingInterrupt` reads the oldest pending one, which may already carry a
+decision that has not been resumed yet. The host resolves them:
 
 ```ts
-await adapter.respondToInterrupt(decision, instance);
+await adapter.respondToInterrupt(decision, instance, { signal }, interruptId);
 // decision: { type: 'approve' } | { type: 'edit', args } | { type: 'reject' }
+// interruptId defaults to the oldest interrupt that has no decision yet. When every
+// pending interrupt is already decided (a failed resume put them back), it defaults to
+// the only one if there is exactly one and throws otherwise, rather than guess which
+// card a bare retry meant.
 ```
 
-This issues a resume run — same `threadId`, empty `messages`, one `resume[]` entry — through
-the same runner and streams the continuation back into the conversation. The decision → wire
+Once every pending interrupt has a decision this issues ONE resume run — same `threadId`,
+empty `messages`, one `resume[]` entry per interrupt in arrival order — through the same
+runner and streams the continuation back into the conversation. Answering one of several
+pending interrupts resolves without running anything.
+
+A failed resume is retryable **if and only if the run failed before its first event**. If
+it yields no event at all — it threw before the first one, an already-aborted signal
+swallowed it, or it simply completed empty — the interrupts and decisions are restored, so
+the decision can be taken again; `respondToInterrupt` still rejects, so the host can show
+the error and re-arm its card. Once the run has yielded any event — `RUN_ERROR` included —
+the server has consumed the interrupt and it is **not** restored: the host should report
+the error and leave the card disabled. (A `reset()` during an in-flight resume also wins:
+nothing is restored into a conversation the host has cleared.) The decision → wire
 mapping (see `docs/hitl-interrupt-resume.md`):
 
 | Decision | `resume[]` entry |
@@ -94,9 +124,42 @@ mapping (see `docs/hitl-interrupt-resume.md`):
 Register the card with the web component's `renderUserDefinedResponse` and read
 `state.messageItem.user_defined`; see `examples/langgraph-carbon/web/src/main.ts`.
 
+## Clarification without an interrupt
+
+A graph that has not adopted `interrupt()` can still be **asking**: it ends the run
+normally, leaves a marker in state, and waits for a fresh turn on the same thread. Every
+sink renders that as a finished answer unless told how to spot the marker — and the marker
+is deployment-specific, so it is yours to supply:
+
+```ts
+new CarbonAgUiAdapter({
+  run,
+  detectClarification: (state) =>
+    (state as { phase?: string }).phase === 'needs_detail'
+      ? { question: (state as { ask?: string }).ask }
+      : false,
+  onClarification: (data) => console.log(data.question, data.threadId),  // optional
+});
+```
+
+`detectClarification` is called **at most once per run**, on `RUN_FINISHED`, with the
+state the adapter already tracks, and **only when the outcome carries no interrupts** — an
+interrupt outcome already is a question. A truthy verdict emits a `user_defined` item
+carrying `ClarificationData` (`kind: 'clarification'`, `question?`, `threadId`) through the
+same `complete_item` path as the decision card, so one `renderUserDefinedResponse` branches
+on `kind`; `onClarification` fires with the same payload for a host that wants the flag
+without rendering. Nothing else moves: no interrupt state is read or written,
+`respondToInterrupt` is unaffected, and the thread stays live by construction — the
+follow-up is an ordinary send on the same `threadId`. Supply no predicate and behavior is
+byte for byte what it was before. A predicate that throws is a host bug and propagates,
+like a throwing `onEvent`.
+
+Deliberately temporary: this is the bridge for pre-`interrupt()` graphs (contract and
+deletion plan in `docs/hitl-interrupt-resume.md`).
+
 ## Notes
 
-- Verified against `@carbon/ai-chat@1.19.0`: `PartialItemChunk` / `CompleteItemChunk` (`streaming_metadata.response_id`) / `FinalResponseChunk` (`final_response.id` = `response_id`), `ItemStreamingMetadata.stream_stopped`, `CustomSendMessageOptions.signal`, `ChainOfThoughtStep`.
+- Verified against the pinned `@carbon/ai-chat` (`docs/SPEC.md` §3): `PartialItemChunk` / `CompleteItemChunk` (`streaming_metadata.response_id`) / `FinalResponseChunk` (`final_response.id` = `response_id`), `ItemStreamingMetadata.stream_stopped`, `CustomSendMessageOptions.signal`, `ChainOfThoughtStep`.
 - Runtime is dependency-free; `@carbon/ai-chat` is a devDependency only for the compat typecheck (pulls ~200 MB of Carbon peers — delete `test/carbon-compat.ts` and the devDep if you don't want that).
 - `response_type` is a string enum in Carbon (`MessageResponseTypes`); the adapter emits the plain string `"text"`, which is the enum's runtime value. Chain-of-thought is only attached to `final_response` (no live per-step updates) — return a `system` item from `onToolCall` if you need immediate feedback.
-- JSON Patch supports `add` / `replace` / `remove` only. Use `fast-json-patch` if your agent emits `move` / `copy` / `test`.
+- `applyJsonPatch` implements the full RFC 6902 op set — `add` / `remove` / `replace` / `move` / `copy` / `test`.

package/dist/adapter.d.ts

@@ -1,4 +1,4 @@
-import type { AgUiContext, AgUiEvent, AgUiMessage, AgUiRunner, AgUiTool, CarbonChatInstanceLike, CarbonCustomSendMessage, CarbonGenericItem, CarbonMessageFeedbackOptions, CarbonMessageRequest, Decision, Interrupt, JsonPatchOp, RunAgentInput, RunOutcome } from './types.js';
+import type { AgUiContext, AgUiEvent, AgUiMessage, AgUiRunner, AgUiTool, CarbonChatInstanceLike, CarbonCustomSendMessage, CarbonGenericItem, CarbonMessageFeedbackOptions, CarbonMessageRequest, CarbonSendMessageOptions, ClarificationData, Decision, Interrupt, JsonPatchOp, RunAgentInput, RunOutcome } from './types.js';
 export interface ToolCallInfo {
     id: string;
     name: string;
@@ -34,6 +34,33 @@ export interface AdapterOptions {
         outcome?: RunOutcome;
         result?: unknown;
     }) => void;
+    /**
+     * Clarification-as-state (kata 73gc). A graph with no `interrupt()` can still
+     * be ASKING something: it ends the run normally and leaves a marker in state,
+     * expecting a fresh turn on the same thread. Every marker is deployment
+     * specific, so the rule is a caller-supplied predicate — nothing here knows
+     * any marker string.
+     *
+     * Called at most ONCE per run, on `RUN_FINISHED`, with the latest tracked
+     * `state`, and only when the outcome carries no interrupts (an interrupt
+     * outcome already IS a question, and its decision card is the affordance).
+     * Return `false` for a normal completion, or `{ question? }` to render the
+     * turn as an open question: a `user_defined` item carrying
+     * `ClarificationData`, sibling of the interrupt card. It touches no interrupt
+     * state, so `respondToInterrupt` is unaffected and the thread simply stays
+     * live for the next send.
+     *
+     * A throwing predicate is a host bug and propagates like a throwing `onEvent`
+     * — it is not routed to `onInvalidEvent`, which reports bad data from the wire.
+     *
+     * ponytail: bridge to real `interrupt()` adoption; delete option, callback and
+     * `ClarificationData` together once graphs interrupt properly.
+     */
+    detectClarification?: (state: unknown) => false | {
+        question?: string;
+    };
+    /** Fires with the same payload the clarification item carries, for a host that wants the flag without rendering a card. */
+    onClarification?: (data: ClarificationData) => void;
     /**
      * When set, Carbon feedback (thumbs) config attached to each assistant TEXT
      * response item so the UI renders the controls. Feedback attaches per-item
@@ -70,26 +97,58 @@ export declare class CarbonAgUiAdapter {
         content: Record<string, unknown>;
     }>;
     messages: AgUiMessage[];
-    /** The interrupt awaiting a decision, or undefined when none is pending. */
-    pendingInterrupt?: Interrupt;
+    /**
+     * Every interrupt still awaiting its resume, keyed by interrupt id in arrival
+     * order — one RUN_FINISHED outcome can carry several, and a later outcome adds
+     * to the collection rather than replacing it. Insertion order is the order the
+     * resume `resume[]` entries are built in. An entry stays here after it has been
+     * answered, until the resume run actually goes out; read `decisions` state via
+     * `respondToInterrupt` rather than tracking it yourself.
+     */
+    readonly pendingInterrupts: Map<string, Interrupt>;
+    /** Decisions collected so far, keyed by interrupt id. The resume run fires once every pending interrupt has one. */
+    private readonly decisions;
     private readonly genId;
+    /** Bumped by reset(); an in-flight resume that restores compares against it. */
+    private resetGeneration;
     /** The Carbon instance from the most recent run, reused for resume streaming. */
     private lastInstance?;
+    /**
+     * The oldest pending interrupt — which may already carry a decision that has
+     * not been resumed yet — or undefined when none is pending. `pendingInterrupts`
+     * is the full set; this is the convenience read for the single-interrupt case.
+     */
+    get pendingInterrupt(): Interrupt | undefined;
     constructor(opts: AdapterOptions);
     /** Pass as `messaging.customSendMessage` in Carbon's PublicConfig. */
     readonly sendMessage: CarbonCustomSendMessage;
     buildRunInput(request: CarbonMessageRequest): RunAgentInput;
     reset(): void;
     /**
-     * Resume the interrupted run with the user's decision. Builds a resume
+     * Record the user's decision for one pending interrupt and, once every
+     * pending interrupt has one, resume the interrupted run. Builds a resume
      * `RunAgentInput` per docs/hitl-interrupt-resume.md (same threadId, empty
-     * messages, one `resume[]` entry), runs it through the same runner, and
-     * streams the continuation back into the conversation.
+     * messages, one `resume[]` entry per pending interrupt in arrival order),
+     * runs it through the same runner, and streams the continuation back into
+     * the conversation.
+     *
+     * Answering one of several pending interrupts resolves without running — the
+     * graph is resumed once, with the whole batch of decisions.
+     *
+     * If the resume run yields no events at all (it threw before the first one,
+     * or an already-aborted signal swallowed it), the interrupts and decisions
+     * are restored so the decision can be retried; the error still rejects.
      *
      * @param instance The Carbon instance to stream into. Defaults to the one
      *   from the most recent run (e.g. the interrupted turn).
+     * @param options Forwarded to the runner — pass `signal` so the host's stop
+     *   control can abort the resumed continuation like a normal send.
+     * @param interruptId Which pending interrupt this decision answers. Defaults
+     *   to the oldest one still undecided; when every pending interrupt already
+     *   has a decision (a failed resume restored them) it defaults to the only
+     *   one if there is exactly one, and throws otherwise rather than guess.
      */
-    respondToInterrupt(decision: Decision, instance?: CarbonChatInstanceLike): Promise<void>;
+    respondToInterrupt(decision: Decision, instance?: CarbonChatInstanceLike, options?: CarbonSendMessageOptions, interruptId?: string): Promise<void>;
     private upsertMessage;
     private handle;
     /**

package/dist/adapter.js

@@ -20,11 +20,32 @@ export class CarbonAgUiAdapter {
     /** Progress/status state per messageId, reconciled from ACTIVITY_SNAPSHOT/ACTIVITY_DELTA. */
     activities = new Map();
     messages = [];
-    /** The interrupt awaiting a decision, or undefined when none is pending. */
-    pendingInterrupt;
+    /**
+     * Every interrupt still awaiting its resume, keyed by interrupt id in arrival
+     * order — one RUN_FINISHED outcome can carry several, and a later outcome adds
+     * to the collection rather than replacing it. Insertion order is the order the
+     * resume `resume[]` entries are built in. An entry stays here after it has been
+     * answered, until the resume run actually goes out; read `decisions` state via
+     * `respondToInterrupt` rather than tracking it yourself.
+     */
+    pendingInterrupts = new Map();
+    /** Decisions collected so far, keyed by interrupt id. The resume run fires once every pending interrupt has one. */
+    decisions = new Map();
     genId;
+    /** Bumped by reset(); an in-flight resume that restores compares against it. */
+    resetGeneration = 0;
     /** The Carbon instance from the most recent run, reused for resume streaming. */
     lastInstance;
+    /**
+     * The oldest pending interrupt — which may already carry a decision that has
+     * not been resumed yet — or undefined when none is pending. `pendingInterrupts`
+     * is the full set; this is the convenience read for the single-interrupt case.
+     */
+    get pendingInterrupt() {
+        for (const interrupt of this.pendingInterrupts.values())
+            return interrupt;
+        return undefined;
+    }
     constructor(opts) {
         this.opts = opts;
         this.genId = opts.idGenerator ?? (() => crypto.randomUUID());
@@ -48,25 +69,63 @@ export class CarbonAgUiAdapter {
     reset() {
         this.messages = [];
         this.state = this.opts.initialState ?? {};
-        this.pendingInterrupt = undefined;
+        this.pendingInterrupts.clear();
+        this.decisions.clear();
+        this.resetGeneration += 1;
     }
     /**
-     * Resume the interrupted run with the user's decision. Builds a resume
+     * Record the user's decision for one pending interrupt and, once every
+     * pending interrupt has one, resume the interrupted run. Builds a resume
      * `RunAgentInput` per docs/hitl-interrupt-resume.md (same threadId, empty
-     * messages, one `resume[]` entry), runs it through the same runner, and
-     * streams the continuation back into the conversation.
+     * messages, one `resume[]` entry per pending interrupt in arrival order),
+     * runs it through the same runner, and streams the continuation back into
+     * the conversation.
+     *
+     * Answering one of several pending interrupts resolves without running — the
+     * graph is resumed once, with the whole batch of decisions.
+     *
+     * If the resume run yields no events at all (it threw before the first one,
+     * or an already-aborted signal swallowed it), the interrupts and decisions
+     * are restored so the decision can be retried; the error still rejects.
      *
      * @param instance The Carbon instance to stream into. Defaults to the one
      *   from the most recent run (e.g. the interrupted turn).
+     * @param options Forwarded to the runner — pass `signal` so the host's stop
+     *   control can abort the resumed continuation like a normal send.
+     * @param interruptId Which pending interrupt this decision answers. Defaults
+     *   to the oldest one still undecided; when every pending interrupt already
+     *   has a decision (a failed resume restored them) it defaults to the only
+     *   one if there is exactly one, and throws otherwise rather than guess.
      */
-    async respondToInterrupt(decision, instance) {
-        const interrupt = this.pendingInterrupt;
-        if (!interrupt)
+    async respondToInterrupt(decision, instance, options = {}, interruptId) {
+        const ids = [...this.pendingInterrupts.keys()];
+        if (interruptId === undefined && ids.length === 0) {
             throw new Error('respondToInterrupt: no pending interrupt');
+        }
+        const targetId = interruptId ??
+            ids.find((id) => !this.decisions.has(id)) ??
+            // Everything pending is already decided — a restored failure. One card is an
+            // unambiguous retry; with several, picking the oldest would silently rewrite a
+            // decision the user made on a different card and resume on the spot.
+            (ids.length === 1 ? ids[0] : undefined);
+        if (targetId === undefined) {
+            throw new Error('respondToInterrupt: several interrupts pending — pass interruptId');
+        }
+        if (!this.pendingInterrupts.has(targetId)) {
+            throw new Error(`respondToInterrupt: unknown interrupt ${targetId}`);
+        }
         const target = instance ?? this.lastInstance;
         if (!target)
             throw new Error('respondToInterrupt: no Carbon instance to stream into');
-        this.pendingInterrupt = undefined;
+        this.decisions.set(targetId, decision);
+        // Every pending card must be answered before the graph can be resumed once.
+        if (this.decisions.size < this.pendingInterrupts.size)
+            return;
+        const resume = ids.map((id) => decisionToResumeEntry(this.decisions.get(id), id));
+        const heldInterrupts = new Map(this.pendingInterrupts);
+        const heldDecisions = new Map(this.decisions);
+        this.pendingInterrupts.clear();
+        this.decisions.clear();
         const input = {
             threadId: this.threadId,
             runId: this.genId(),
@@ -75,9 +134,37 @@ export class CarbonAgUiAdapter {
             tools: this.opts.tools ?? [],
             context: this.opts.context ?? [],
             forwardedProps: this.opts.forwardedProps ?? {},
-            resume: [decisionToResumeEntry(decision, interrupt.id)],
+            resume,
+        };
+        // ponytail: "no events yielded" is the retryable test — a successful but eventless
+        // resume restores too. Once the server yields ANY event (RUN_ERROR included) it has
+        // consumed the interrupt, so restoring there would double-resume the graph.
+        const progress = { started: false };
+        const generation = this.resetGeneration;
+        const restore = () => {
+            // A reset() during the run means the host threw the conversation away; putting a
+            // decision card back into it would resurrect an interrupt with no thread behind it.
+            if (progress.started || this.resetGeneration !== generation)
+                return;
+            for (const [id, interrupt] of heldInterrupts) {
+                if (!this.pendingInterrupts.has(id))
+                    this.pendingInterrupts.set(id, interrupt);
+            }
+            for (const [id, held] of heldDecisions) {
+                if (!this.decisions.has(id))
+                    this.decisions.set(id, held);
+            }
         };
-        await this.runAndStream(input, {}, target);
+        try {
+            await this.runAndStream(input, options, target, undefined, progress);
+        }
+        catch (err) {
+            restore();
+            throw err;
+        }
+        // runAndStream swallows the throw when options.signal is aborted; that path leaves
+        // the decision unsent too, so it restores just the same.
+        restore();
     }
     upsertMessage(msg) {
         const i = this.messages.findIndex((m) => m.id === msg.id);
@@ -95,7 +182,7 @@ export class CarbonAgUiAdapter {
      * into Carbon chunks on `instance`. Shared by the initial turn and by
      * `respondToInterrupt`, so a resumed continuation streams identically.
      */
-    async runAndStream(input, options, instance, requestId) {
+    async runAndStream(input, options, instance, requestId, progress) {
         this.lastInstance = instance;
         const { runId } = input;
         const meta = { response_id: runId };
@@ -108,6 +195,8 @@ export class CarbonAgUiAdapter {
         // Chunk variants carry the id only on their first chunk; later chunks continue the current one.
         let lastChunkTextId;
         let lastChunkToolId;
+        // detectClarification is evaluated at most once per run (see RUN_FINISHED).
+        let clarificationChecked = false;
         // Reasoning text accumulates per messageId (THINKING_TEXT_* has none → fixed 'thinking'
         // key). One ReasoningStep per key at close; empties are dropped. Not streamed live.
         const THINKING_KEY = 'thinking';
@@ -180,6 +269,10 @@ export class CarbonAgUiAdapter {
         };
         try {
             for await (const rawEv of this.opts.run(input, { signal: options.signal })) {
+                // The run has produced something, so a resume can no longer be retried (see
+                // respondToInterrupt): the server has consumed the interrupt.
+                if (progress)
+                    progress.started = true;
                 // IN seam (issue gmb9): validate against the AG-UI protocol schema before
                 // switching. A malformed event is reported and skipped, NEVER thrown —
                 // one bad event must not kill the stream. `validate: false` passes through.
@@ -276,8 +369,19 @@ export class CarbonAgUiAdapter {
                         this.opts.onStateChange?.(this.state);
                         break;
                     case 'STATE_DELTA':
-                        this.state = applyJsonPatch(this.state, ev.delta);
-                        this.opts.onStateChange?.(this.state);
+                        try {
+                            this.state = applyJsonPatch(this.state, ev.delta);
+                            this.opts.onStateChange?.(this.state);
+                        }
+                        catch (err) {
+                            // A patch that is schema-valid but fails to apply (stale JSON Pointer,
+                            // failed `test` op) is reported and skipped, exactly like a malformed
+                            // event: one bad event must not kill the stream. `applyJsonPatch` works
+                            // on a clone, so state keeps its last good value — it may diverge from
+                            // the server until the next STATE_SNAPSHOT.
+                            const msg = err instanceof Error ? err.message : String(err);
+                            this.opts.onInvalidEvent?.(ev, `STATE_DELTA failed to apply: ${msg}; ops: ${JSON.stringify(ev.delta)}`);
+                        }
                         break;
                     case 'ACTIVITY_SNAPSHOT':
                         // A snapshot is authoritative; it replaces any prior activity for this messageId.
@@ -287,9 +391,19 @@ export class CarbonAgUiAdapter {
                         break;
                     case 'ACTIVITY_DELTA': {
                         const entry = this.activities.get(ev.messageId) ?? { activityType: ev.activityType, content: {} };
-                        entry.content = applyJsonPatch(entry.content, ev.patch);
-                        this.activities.set(ev.messageId, entry);
-                        this.opts.onActivity?.(entry.activityType, entry.content, ev.messageId);
+                        try {
+                            entry.content = applyJsonPatch(entry.content, ev.patch);
+                            this.activities.set(ev.messageId, entry);
+                            this.opts.onActivity?.(entry.activityType, entry.content, ev.messageId);
+                        }
+                        catch (err) {
+                            // Same contract as STATE_DELTA above: a patch that is schema-valid but
+                            // fails to apply is reported and skipped, never thrown. `applyJsonPatch`
+                            // works on a clone, so the activity keeps its last good content — it may
+                            // diverge from the server until the next ACTIVITY_SNAPSHOT.
+                            const msg = err instanceof Error ? err.message : String(err);
+                            this.opts.onInvalidEvent?.(ev, `ACTIVITY_DELTA failed to apply: ${msg}; ops: ${JSON.stringify(ev.patch)}`);
+                        }
                         break;
                     }
                     case 'MESSAGES_SNAPSHOT': {
@@ -343,19 +457,45 @@ export class CarbonAgUiAdapter {
                         // turn as a plain final_response, emit a user_defined decision item so
                         // the host can render an approve/reject/edit card, and retain the
                         // interrupt for the resume. Non-interrupt outcomes fall through.
+                        // The only non-interrupt outcome is `{ type: 'success' }` (or an absent
+                        // outcome): a clean completion that carries no payload, so the
+                        // already-streamed content stands and there is nothing extra to render.
+                        // A host reads any returned `result` via onRunFinished above.
                         this.opts.onRunFinished?.({ outcome: ev.outcome, result: ev.result });
-                        const interrupt = firstInterrupt(ev.outcome);
-                        if (interrupt) {
-                            this.pendingInterrupt = interrupt;
+                        const interrupts = ev.outcome?.type === 'interrupt' ? ev.outcome.interrupts ?? [] : [];
+                        for (const interrupt of interrupts) {
+                            // Never clobber an interrupt already awaiting a decision — that is exactly
+                            // how a card ends up on screen with no way to answer it — and never draw a
+                            // second card for it either: the duplicate's click could only fail.
+                            if (this.pendingInterrupts.has(interrupt.id))
+                                continue;
+                            this.pendingInterrupts.set(interrupt.id, interrupt);
                             const item = interruptItem(interrupt);
                             items.push(item);
                             await emit({ complete_item: item, streaming_metadata: meta });
                         }
-                        else {
-                            // The only non-interrupt outcome is `{ type: 'success' }` (or an
-                            // absent outcome): a clean completion that carries no payload, so
-                            // the already-streamed content stands and there is nothing extra to
-                            // render. A host reads any returned `result` via onRunFinished above.
+                        // Clarification-as-state (kata 73gc), deliberately AFTER and disjoint from
+                        // the interrupt path: a graph with no interrupt() can still be asking
+                        // something, and only the host knows its marker. Interrupt outcomes are
+                        // excluded — the decision card already is the question — and the predicate
+                        // runs at most once per run, so a repeated RUN_FINISHED cannot draw a
+                        // second card. Nothing here reads or writes pendingInterrupts, which is
+                        // what makes the whole path deletable once interrupt() is adopted.
+                        if (!clarificationChecked && interrupts.length === 0 && this.opts.detectClarification) {
+                            clarificationChecked = true;
+                            // A throwing predicate is a host bug: let it propagate like onEvent does.
+                            const verdict = this.opts.detectClarification(this.state);
+                            if (verdict) {
+                                const data = { kind: 'clarification', question: verdict.question, threadId: this.threadId };
+                                this.opts.onClarification?.(data);
+                                const item = {
+                                    response_type: 'user_defined',
+                                    user_defined: data,
+                                    streaming_metadata: { id: this.genId() },
+                                };
+                                items.push(item);
+                                await emit({ complete_item: item, streaming_metadata: meta });
+                            }
                         }
                         break;
                     }
@@ -372,7 +512,7 @@ export class CarbonAgUiAdapter {
                         }
                         break;
                     default:
-                        // RUN_STARTED / STEP_* / RAW / other CUSTOM: surfaced via onEvent only.
+                        // RUN_STARTED / STEP_* / SUBAGENT_* / RAW / other CUSTOM: surfaced via onEvent only.
                         break;
                 }
             }
@@ -424,12 +564,6 @@ function parseJsonLoose(s) {
         return s;
     }
 }
-/** The first interrupt in a RUN_FINISHED outcome, or undefined if not an interrupt. */
-function firstInterrupt(outcome) {
-    if (outcome?.type !== 'interrupt')
-        return undefined;
-    return outcome.interrupts?.[0];
-}
 /** Build the Carbon `user_defined` decision-card item from an interrupt. */
 function interruptItem(interrupt) {
     const raw = interrupt.metadata?.langgraph?.raw ?? {};

package/dist/coverage.js

@@ -23,6 +23,9 @@ export const AG_UI_COVERAGE = {
     RUN_ERROR: { status: 'handled', note: 'Thrown as AgUiRunError.' },
     STEP_STARTED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
     STEP_FINISHED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
+    SUBAGENT_STARTED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
+    SUBAGENT_FINISHED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
+    SUBAGENT_ERROR: { status: 'observed', note: 'Lifecycle; onEvent only (distinct from top-level RUN_ERROR, which throws).' },
     TEXT_MESSAGE_START: { status: 'handled', note: 'Opens a streamed text item.' },
     TEXT_MESSAGE_CONTENT: { status: 'handled', note: 'Partial text chunk.' },
     TEXT_MESSAGE_END: { status: 'handled', note: 'Completes the text item.' },

package/dist/transport.d.ts

@@ -3,11 +3,17 @@ export interface SseRunnerOptions {
     url: string;
     headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
     fetch?: typeof fetch;
+    /** Called when a `data:` payload is not valid JSON; the frame is skipped and the stream continues. */
+    onParseError?: (raw: string, err: unknown) => void;
 }
 /** POST RunAgentInput as JSON, read back `text/event-stream` of AG-UI events. */
 export declare function createSseRunner(opts: SseRunnerOptions): AgUiRunner;
-/** Parse an SSE byte stream into AG-UI events (one JSON object per `data:` block). */
-export declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<AgUiEvent>;
+/**
+ * Parse an SSE byte stream into AG-UI events (one JSON object per `data:` block).
+ * A block whose payload is not valid JSON is reported to `onParseError` and skipped —
+ * one bad frame must not kill the stream.
+ */
+export declare function parseSse(body: ReadableStream<Uint8Array>, onParseError?: (raw: string, err: unknown) => void): AsyncGenerator<AgUiEvent>;
 /** Minimal rxjs-compatible shape, so `@ag-ui/client`'s `agent.run(input)` plugs in without importing rxjs here. */
 export interface ObservableLike<T> {
     subscribe(observer: {

package/dist/transport.js

@@ -9,13 +9,19 @@ export function createSseRunner(opts) {
             body: JSON.stringify(input),
             signal,
         });
-        if (!res.ok || !res.body)
+        if (!res.ok)
             throw new Error(`AG-UI request failed: HTTP ${res.status}`);
-        yield* parseSse(res.body);
+        if (!res.body)
+            throw new Error('AG-UI response had no body');
+        yield* parseSse(res.body, opts.onParseError);
     };
 }
-/** Parse an SSE byte stream into AG-UI events (one JSON object per `data:` block). */
-export async function* parseSse(body) {
+/**
+ * Parse an SSE byte stream into AG-UI events (one JSON object per `data:` block).
+ * A block whose payload is not valid JSON is reported to `onParseError` and skipped —
+ * one bad frame must not kill the stream.
+ */
+export async function* parseSse(body, onParseError) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buf = '';
@@ -24,12 +30,12 @@ export async function* parseSse(body) {
         while ((idx = buf.indexOf('\n\n')) !== -1) {
             const block = buf.slice(0, idx);
             buf = buf.slice(idx + 2);
-            const ev = parseBlock(block);
+            const ev = parseBlock(block, onParseError);
             if (ev)
                 yield ev;
         }
         if (final && buf.trim()) {
-            const ev = parseBlock(buf);
+            const ev = parseBlock(buf, onParseError);
             buf = '';
             if (ev)
                 yield ev;
@@ -50,13 +56,23 @@ export async function* parseSse(body) {
         reader.releaseLock();
     }
 }
-function parseBlock(block) {
+function parseBlock(block, onParseError) {
     const data = block
         .split('\n')
         .filter((l) => l.startsWith('data:'))
         .map((l) => l.slice(5).replace(/^ /, ''))
         .join('\n');
-    return data ? JSON.parse(data) : null;
+    if (!data)
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch (err) {
+        // Reported and skipped, via the same "no event" contract as a block with no
+        // `data:` lines. Throwing here would discard every event already parsed.
+        onParseError?.(data, err);
+        return null;
+    }
 }
 /** Bridge an Observable (e.g. `new HttpAgent({url}).run(input)`) to the AsyncIterable the adapter consumes. */
 export async function* fromObservable(obs, signal) {

package/dist/types.d.ts

@@ -90,6 +90,26 @@ export interface InterruptDecisionData {
     responseSchema?: unknown;
     toolCallId?: string;
 }
+/**
+ * Payload carried in the Carbon `user_defined` item emitted when a run finished
+ * WITHOUT an interrupt but the host's `detectClarification` predicate says the
+ * agent is asking a question (kata 73gc). Sibling of `InterruptDecisionData`:
+ * same `user_defined` seam, different `kind`, and no decision to send back —
+ * the user simply types the next message on the same thread.
+ *
+ * ponytail: deliberately temporary. This is the bridge for graphs that signal a
+ * clarification by completing normally with a marker in state; once they adopt
+ * real `interrupt()` the question arrives as an interrupt and this whole path
+ * (type, option, callback) deletes cleanly, because it never touches the
+ * interrupt state.
+ */
+export interface ClarificationData {
+    kind: 'clarification';
+    /** The question, when the predicate could extract one from state. */
+    question?: string;
+    /** The still-live thread the follow-up turn goes to. */
+    threadId: string;
+}
 export interface JsonPatchOp {
     op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsb3/carbon-agui-adapter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Adapter that drives IBM Carbon AI Chat from an AG-UI event stream",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@ag-ui/core": "0.0.58"
+    "@ag-ui/core": "0.0.59"
   },
   "devDependencies": {
     "@carbon/ai-chat": "1.19.0",