@hsb3/carbon-agui-adapter 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# carbon-agui-adapter
+
+Drives IBM **Carbon AI Chat** (`@carbon/ai-chat`) from an **AG-UI** event stream. Zero runtime deps.
+
+- 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
+- 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
+
+## Run
+
+```bash
+npm install
+npm run check      # typecheck + tests
+npm run build      # dist/
+```
+
+## Use
+
+```ts
+import { createAgUiSendMessage, createSseRunner } from 'carbon-agui-adapter';
+
+const config = {
+  messaging: {
+    customSendMessage: createAgUiSendMessage({
+      run: createSseRunner({ url: 'https://my-agent/run', headers: { authorization: 'Bearer …' } }),
+      tools: [],                               // AG-UI tool defs forwarded each run
+      onToolCall: (c) => ({ response_type: 'system', text: `⚙ ${c.name}` }),  // optional live feedback; steps land in chain-of-thought regardless
+      onStateChange: (s) => console.log(s),
+    }),
+  },
+};
+```
+
+Need history/state/reset access? Use the class:
+
+```ts
+const adapter = new CarbonAgUiAdapter({ run });
+config.messaging.customSendMessage = adapter.sendMessage;
+adapter.messages; adapter.state; adapter.reset();
+```
+
+Using `@ag-ui/client` instead of raw SSE:
+
+```ts
+import { HttpAgent } from '@ag-ui/client';
+import { fromObservable } from 'carbon-agui-adapter';
+
+const agent = new HttpAgent({ url: 'https://my-agent/run' });
+const run = (input, { signal }) => fromObservable(agent.run(input), signal);
+```
+
+## Event mapping
+
+| AG-UI | Carbon |
+|---|---|
+| `TEXT_MESSAGE_CONTENT` | `partial_item` (text delta) |
+| `TEXT_MESSAGE_END` | `complete_item` (full text) + history |
+| `TOOL_CALL_START/ARGS/END` | history; `chain_of_thought` step (`tool_name`, `request.args`); `complete_item` if `onToolCall` returns an item |
+| `TOOL_CALL_RESULT` | history (`role: tool`); step `response.content` + `status: success` |
+| `STATE_SNAPSHOT` / `STATE_DELTA` | `adapter.state` + `onStateChange` |
+| `MESSAGES_SNAPSHOT` | replaces history |
+| `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 |
+| `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 |
+
+## 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:
+
+```ts
+await adapter.respondToInterrupt(decision, instance);
+// decision: { type: 'approve' } | { type: 'edit', args } | { type: 'reject' }
+```
+
+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
+mapping (see `docs/hitl-interrupt-resume.md`):
+
+| Decision | `resume[]` entry |
+|---|---|
+| `approve` | `{ status: 'resolved', payload: { approved: true } }` |
+| `edit` | `{ status: 'resolved', payload: { approved: true, args } }` |
+| `reject` | `{ status: 'cancelled', payload: null }` |
+
+Register the card with the web component's `renderUserDefinedResponse` and read
+`state.messageItem.user_defined`; see `examples/langgraph-carbon/web/src/main.ts`.
+
+## 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`.
+- 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`.

package/dist/adapter.d.ts

@@ -0,0 +1,104 @@
+import type { AgUiContext, AgUiEvent, AgUiMessage, AgUiRunner, AgUiTool, CarbonChatInstanceLike, CarbonCustomSendMessage, CarbonGenericItem, CarbonMessageFeedbackOptions, CarbonMessageRequest, Decision, Interrupt, JsonPatchOp, RunAgentInput, RunOutcome } from './types.js';
+export interface ToolCallInfo {
+    id: string;
+    name: string;
+    /** Raw JSON string, concatenated from TOOL_CALL_ARGS deltas. */
+    args: string;
+    parentMessageId?: string;
+}
+export interface AdapterOptions {
+    run: AgUiRunner;
+    threadId?: string;
+    tools?: AgUiTool[];
+    context?: AgUiContext[];
+    initialState?: unknown;
+    forwardedProps?: unknown;
+    idGenerator?: () => string;
+    /** Every AG-UI event, before translation. */
+    onEvent?: (event: AgUiEvent) => void;
+    onStateChange?: (state: unknown) => void;
+    /** Called after each ACTIVITY_SNAPSHOT/ACTIVITY_DELTA with the reconciled progress/status content. */
+    onActivity?: (activityType: string, content: Record<string, unknown>, messageId: string) => void;
+    /** Tool calls are rendered as Carbon chain-of-thought steps on the final response. Set false to disable. */
+    chainOfThought?: boolean;
+    /** Called on TOOL_CALL_END. Optionally return a Carbon item to render immediately (e.g. a system message). */
+    onToolCall?: (call: ToolCallInfo) => CarbonGenericItem | null | void | Promise<CarbonGenericItem | null | void>;
+    /**
+     * Called once when RUN_FINISHED is processed, with its `outcome` and any legacy
+     * top-level `result`. A `success` outcome carries no renderable payload, and a
+     * `result` has no obvious Carbon target — this callback is how a host observes
+     * a returned value instead of being blind to it. The interrupt path renders its
+     * own decision card; this still fires so a host sees every completion.
+     */
+    onRunFinished?: (info: {
+        outcome?: RunOutcome;
+        result?: unknown;
+    }) => void;
+    /**
+     * When set, Carbon feedback (thumbs) config attached to each assistant TEXT
+     * response item so the UI renders the controls. Feedback attaches per-item
+     * (`message_item_options.feedback`), never per-response, and only to text
+     * items — not decision cards, tool renders, or CUSTOM-dispatched items.
+     * Capturing the click is Carbon→host via the bus and out of this adapter's scope.
+     */
+    feedback?: CarbonMessageFeedbackOptions;
+    /**
+     * Runtime validation at the AG-UI/Carbon trust boundaries (issue gmb9).
+     * Default TRUE: incoming runner events are validated against the AG-UI
+     * protocol schema and outgoing CUSTOM Carbon items against the known-type +
+     * required-field checks; malformed ones are skipped (never thrown), so one
+     * bad event cannot kill the stream. Set false to skip validation entirely
+     * (blind cast for events, allowlist-only for items — the pre-gmb9 behavior).
+     */
+    validate?: boolean;
+    /** Called when an incoming AG-UI event fails schema validation (then skipped). */
+    onInvalidEvent?: (raw: unknown, error: string) => void;
+    /** Called when an outgoing CUSTOM Carbon item fails validation (then skipped). */
+    onInvalidItem?: (raw: unknown, reason: string) => void;
+}
+export declare class AgUiRunError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare class CarbonAgUiAdapter {
+    private readonly opts;
+    readonly threadId: string;
+    state: unknown;
+    /** Progress/status state per messageId, reconciled from ACTIVITY_SNAPSHOT/ACTIVITY_DELTA. */
+    activities: Map<string, {
+        activityType: string;
+        content: Record<string, unknown>;
+    }>;
+    messages: AgUiMessage[];
+    /** The interrupt awaiting a decision, or undefined when none is pending. */
+    pendingInterrupt?: Interrupt;
+    private readonly genId;
+    /** The Carbon instance from the most recent run, reused for resume streaming. */
+    private lastInstance?;
+    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
+     * `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.
+     *
+     * @param instance The Carbon instance to stream into. Defaults to the one
+     *   from the most recent run (e.g. the interrupted turn).
+     */
+    respondToInterrupt(decision: Decision, instance?: CarbonChatInstanceLike): Promise<void>;
+    private upsertMessage;
+    private handle;
+    /**
+     * Run one `RunAgentInput` through the runner and translate its AG-UI events
+     * into Carbon chunks on `instance`. Shared by the initial turn and by
+     * `respondToInterrupt`, so a resumed continuation streams identically.
+     */
+    private runAndStream;
+}
+/** Convenience: returns just the customSendMessage function. */
+export declare function createAgUiSendMessage(opts: AdapterOptions): CarbonCustomSendMessage;
+export declare function applyJsonPatch<T>(doc: T, ops: JsonPatchOp[]): T;