@hsb3/carbon-agui-adapter 0.1.0 → 0.1.1

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
+- 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` (1.19) types
+- `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: {
@@ -46,7 +54,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);
@@ -66,7 +74,7 @@ const run = (input, { signal }) => fromObservable(agent.run(input), signal);
 | `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 |
 | `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
 

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, Decision, Interrupt, JsonPatchOp, RunAgentInput, RunOutcome } from './types.js';
 export interface ToolCallInfo {
     id: string;
     name: string;
@@ -88,8 +88,10 @@ export declare class CarbonAgUiAdapter {
      *
      * @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.
      */
-    respondToInterrupt(decision: Decision, instance?: CarbonChatInstanceLike): Promise<void>;
+    respondToInterrupt(decision: Decision, instance?: CarbonChatInstanceLike, options?: CarbonSendMessageOptions): Promise<void>;
     private upsertMessage;
     private handle;
     /**

package/dist/adapter.js

@@ -58,8 +58,10 @@ export class CarbonAgUiAdapter {
      *
      * @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.
      */
-    async respondToInterrupt(decision, instance) {
+    async respondToInterrupt(decision, instance, options = {}) {
         const interrupt = this.pendingInterrupt;
         if (!interrupt)
             throw new Error('respondToInterrupt: no pending interrupt');
@@ -77,7 +79,7 @@ export class CarbonAgUiAdapter {
             forwardedProps: this.opts.forwardedProps ?? {},
             resume: [decisionToResumeEntry(decision, interrupt.id)],
         };
-        await this.runAndStream(input, {}, target);
+        await this.runAndStream(input, options, target);
     }
     upsertMessage(msg) {
         const i = this.messages.findIndex((m) => m.id === msg.id);
@@ -372,7 +374,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;
                 }
             }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsb3/carbon-agui-adapter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",