@hsb3/carbon-agui-adapter 0.1.0

package/dist/adapter.js

@@ -0,0 +1,557 @@
+import { CARBON_COVERAGE } from './coverage.js';
+import { validateAgUiEvent, validateCarbonItem } from './validate.js';
+/**
+ * Known Carbon response_type values — the allowlist for CUSTOM item dispatch.
+ * Derived from the coverage matrix so it can never drift from the declared set.
+ */
+const KNOWN_CARBON_TYPES = new Set(Object.keys(CARBON_COVERAGE));
+export class AgUiRunError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'AgUiRunError';
+    }
+}
+export class CarbonAgUiAdapter {
+    opts;
+    threadId;
+    state;
+    /** 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;
+    genId;
+    /** The Carbon instance from the most recent run, reused for resume streaming. */
+    lastInstance;
+    constructor(opts) {
+        this.opts = opts;
+        this.genId = opts.idGenerator ?? (() => crypto.randomUUID());
+        this.threadId = opts.threadId ?? this.genId();
+        this.state = opts.initialState ?? {};
+    }
+    /** Pass as `messaging.customSendMessage` in Carbon's PublicConfig. */
+    sendMessage = (req, options, instance) => this.handle(req, options, instance);
+    buildRunInput(request) {
+        this.upsertMessage({ id: request.id ?? this.genId(), role: 'user', content: request.input.text ?? '' });
+        return {
+            threadId: this.threadId,
+            runId: this.genId(),
+            state: this.state,
+            messages: [...this.messages],
+            tools: this.opts.tools ?? [],
+            context: this.opts.context ?? [],
+            forwardedProps: this.opts.forwardedProps ?? {},
+        };
+    }
+    reset() {
+        this.messages = [];
+        this.state = this.opts.initialState ?? {};
+        this.pendingInterrupt = undefined;
+    }
+    /**
+     * 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).
+     */
+    async respondToInterrupt(decision, instance) {
+        const interrupt = this.pendingInterrupt;
+        if (!interrupt)
+            throw new Error('respondToInterrupt: no pending interrupt');
+        const target = instance ?? this.lastInstance;
+        if (!target)
+            throw new Error('respondToInterrupt: no Carbon instance to stream into');
+        this.pendingInterrupt = undefined;
+        const input = {
+            threadId: this.threadId,
+            runId: this.genId(),
+            state: this.state,
+            messages: [],
+            tools: this.opts.tools ?? [],
+            context: this.opts.context ?? [],
+            forwardedProps: this.opts.forwardedProps ?? {},
+            resume: [decisionToResumeEntry(decision, interrupt.id)],
+        };
+        await this.runAndStream(input, {}, target);
+    }
+    upsertMessage(msg) {
+        const i = this.messages.findIndex((m) => m.id === msg.id);
+        if (i === -1)
+            this.messages.push(msg);
+        else
+            this.messages[i] = msg;
+    }
+    async handle(request, options, instance) {
+        const input = this.buildRunInput(request);
+        await this.runAndStream(input, options, instance, request.id);
+    }
+    /**
+     * 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.
+     */
+    async runAndStream(input, options, instance, requestId) {
+        this.lastInstance = instance;
+        const { runId } = input;
+        const meta = { response_id: runId };
+        const emit = (chunk) => instance.messaging.addMessageChunk(chunk);
+        const items = [];
+        const openText = new Map();
+        const openTools = new Map();
+        const steps = [];
+        const stepByCall = new Map();
+        // Chunk variants carry the id only on their first chunk; later chunks continue the current one.
+        let lastChunkTextId;
+        let lastChunkToolId;
+        // 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';
+        const reasoningText = new Map();
+        const addReasoning = (key, delta) => reasoningText.set(key, (reasoningText.get(key) ?? '') + delta);
+        // Feedback (thumbs) config attaches to completed assistant text items only, so
+        // both TEXT_MESSAGE_END and stream-close-finalized text land it in final_response.
+        const feedback = this.opts.feedback;
+        const textItem = (id, text, stopped = false) => ({
+            response_type: 'text',
+            text,
+            streaming_metadata: stopped ? { id, stream_stopped: true } : { id },
+            ...(feedback ? { message_item_options: { feedback } } : {}),
+        });
+        // Live partials only: flags Carbon's native stop-streaming button. Complete items and
+        // the final_response never carry it — cancelling mid-stream is only meaningful while live.
+        // No feedback config on partials; it belongs on the completed item Carbon renders.
+        const partialTextItem = (id, text) => ({
+            response_type: 'text',
+            text,
+            streaming_metadata: { id, cancellable: true },
+        });
+        // Finalize one tool call (drained from openTools): record it in history, build the
+        // chain-of-thought step, and fire onToolCall. Shared by TOOL_CALL_END and the
+        // stream-close drain (chunk variants have no END, so they finalize at close).
+        const finalizeToolCall = async (tc) => {
+            this.upsertMessage({
+                id: tc.parentMessageId ?? tc.id,
+                role: 'assistant',
+                toolCalls: [{ id: tc.id, type: 'function', function: { name: tc.name, arguments: tc.args } }],
+            });
+            if (this.opts.chainOfThought !== false) {
+                const step = { title: tc.name, tool_name: tc.name, request: { args: parseJsonLoose(tc.args) } };
+                steps.push(step);
+                stepByCall.set(tc.id, step);
+            }
+            const rendered = await this.opts.onToolCall?.(tc);
+            if (rendered) {
+                items.push(rendered);
+                await emit({ complete_item: rendered, streaming_metadata: meta });
+            }
+        };
+        // Dispatch one CUSTOM-carried Carbon item across the agent → UI trust
+        // boundary: validate response_type + required fields (issue gmb9), stamp an
+        // id if absent, then render it the same way TEXT_MESSAGE_END renders a
+        // completed item. `validate: false` falls back to the pre-gmb9 allowlist-only
+        // shallow check so disabling validation is uniform across both seams.
+        const dispatchCarbonItem = async (raw) => {
+            let item;
+            if (this.opts.validate !== false) {
+                const result = validateCarbonItem(raw, KNOWN_CARBON_TYPES);
+                if (!result.ok) {
+                    this.opts.onInvalidItem?.(raw, result.reason);
+                    return;
+                }
+                item = result.item;
+            }
+            else {
+                if (raw === null || typeof raw !== 'object')
+                    return;
+                item = raw;
+                if (typeof item.response_type !== 'string' || !KNOWN_CARBON_TYPES.has(item.response_type))
+                    return;
+            }
+            const withId = item.streaming_metadata?.id
+                ? item
+                : { ...item, streaming_metadata: { ...item.streaming_metadata, id: this.genId() } };
+            items.push(withId);
+            await emit({ complete_item: withId, streaming_metadata: meta });
+        };
+        try {
+            for await (const rawEv of this.opts.run(input, { signal: options.signal })) {
+                // 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.
+                let ev;
+                if (this.opts.validate !== false) {
+                    const result = validateAgUiEvent(rawEv);
+                    if (!result.ok) {
+                        this.opts.onInvalidEvent?.(rawEv, result.error);
+                        continue;
+                    }
+                    ev = result.event;
+                }
+                else {
+                    ev = rawEv;
+                }
+                this.opts.onEvent?.(ev);
+                switch (ev.type) {
+                    case 'TEXT_MESSAGE_START':
+                        openText.set(ev.messageId, '');
+                        break;
+                    case 'TEXT_MESSAGE_CONTENT':
+                        openText.set(ev.messageId, (openText.get(ev.messageId) ?? '') + ev.delta);
+                        await emit({ partial_item: partialTextItem(ev.messageId, ev.delta), streaming_metadata: meta });
+                        break;
+                    case 'TEXT_MESSAGE_END': {
+                        const text = openText.get(ev.messageId) ?? '';
+                        openText.delete(ev.messageId);
+                        const item = textItem(ev.messageId, text);
+                        items.push(item);
+                        this.upsertMessage({ id: ev.messageId, role: 'assistant', content: text });
+                        await emit({ complete_item: item, streaming_metadata: meta });
+                        break;
+                    }
+                    case 'TEXT_MESSAGE_CHUNK': {
+                        // First chunk carries the id; later chunks omit it and continue the current message.
+                        const id = ev.messageId ?? lastChunkTextId;
+                        if (id && !openText.has(id))
+                            openText.set(id, '');
+                        lastChunkTextId = id;
+                        if (ev.delta != null && id) {
+                            openText.set(id, (openText.get(id) ?? '') + ev.delta);
+                            await emit({ partial_item: partialTextItem(id, ev.delta), streaming_metadata: meta });
+                        }
+                        break;
+                    }
+                    case 'TOOL_CALL_START':
+                        openTools.set(ev.toolCallId, {
+                            id: ev.toolCallId,
+                            name: ev.toolCallName,
+                            args: '',
+                            parentMessageId: ev.parentMessageId,
+                        });
+                        break;
+                    case 'TOOL_CALL_ARGS': {
+                        const tc = openTools.get(ev.toolCallId);
+                        if (tc)
+                            tc.args += ev.delta;
+                        break;
+                    }
+                    case 'TOOL_CALL_END': {
+                        const tc = openTools.get(ev.toolCallId);
+                        if (!tc)
+                            break;
+                        openTools.delete(ev.toolCallId);
+                        await finalizeToolCall(tc);
+                        break;
+                    }
+                    case 'TOOL_CALL_CHUNK': {
+                        // First chunk carries id + name; later chunks omit them and continue the args.
+                        const id = ev.toolCallId ?? lastChunkToolId;
+                        if (ev.toolCallName && id && !openTools.has(id)) {
+                            openTools.set(id, { id, name: ev.toolCallName, args: '', parentMessageId: ev.parentMessageId });
+                        }
+                        lastChunkToolId = id;
+                        if (ev.delta && id) {
+                            const tc = openTools.get(id);
+                            if (tc)
+                                tc.args += ev.delta;
+                        }
+                        // No END event: finalized in the stream-close drain below.
+                        break;
+                    }
+                    case 'TOOL_CALL_RESULT': {
+                        this.upsertMessage({ id: ev.messageId, role: 'tool', content: ev.content, toolCallId: ev.toolCallId });
+                        const step = stepByCall.get(ev.toolCallId);
+                        if (step) {
+                            step.response = { content: parseJsonLoose(ev.content) };
+                            step.status = 'success';
+                        }
+                        break;
+                    }
+                    case 'STATE_SNAPSHOT':
+                        this.state = ev.snapshot;
+                        this.opts.onStateChange?.(this.state);
+                        break;
+                    case 'STATE_DELTA':
+                        this.state = applyJsonPatch(this.state, ev.delta);
+                        this.opts.onStateChange?.(this.state);
+                        break;
+                    case 'ACTIVITY_SNAPSHOT':
+                        // A snapshot is authoritative; it replaces any prior activity for this messageId.
+                        // ponytail: host renders via onActivity; a Carbon system-message render is a deliberate follow-up.
+                        this.activities.set(ev.messageId, { activityType: ev.activityType, content: ev.content });
+                        this.opts.onActivity?.(ev.activityType, ev.content, ev.messageId);
+                        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);
+                        break;
+                    }
+                    case 'MESSAGES_SNAPSHOT': {
+                        // A non-streaming graph (e.g. the HITL resume continuation) delivers
+                        // its assistant reply as a full snapshot rather than TEXT_MESSAGE_*
+                        // deltas. Render any assistant message that is newly present in this
+                        // run and wasn't already streamed (streamed messages are already in
+                        // this.messages via TEXT_MESSAGE_END), so it lands in the conversation.
+                        const known = new Set(this.messages.map((m) => m.id));
+                        for (const m of ev.messages) {
+                            if (m.role !== 'assistant' || !m.content || known.has(m.id))
+                                continue;
+                            const item = textItem(m.id, m.content);
+                            items.push(item);
+                            await emit({ complete_item: item, streaming_metadata: meta });
+                        }
+                        this.messages = [...ev.messages];
+                        break;
+                    }
+                    case 'REASONING_MESSAGE_START':
+                        reasoningText.set(ev.messageId, reasoningText.get(ev.messageId) ?? '');
+                        break;
+                    case 'REASONING_MESSAGE_CONTENT':
+                        addReasoning(ev.messageId, ev.delta);
+                        break;
+                    case 'REASONING_MESSAGE_CHUNK':
+                        if (ev.messageId != null && ev.delta != null)
+                            addReasoning(ev.messageId, ev.delta);
+                        break;
+                    case 'THINKING_TEXT_MESSAGE_START':
+                        reasoningText.set(THINKING_KEY, reasoningText.get(THINKING_KEY) ?? '');
+                        break;
+                    case 'THINKING_TEXT_MESSAGE_CONTENT':
+                        addReasoning(THINKING_KEY, ev.delta);
+                        break;
+                    case 'REASONING_ENCRYPTED_VALUE':
+                        // Encrypted reasoning payload; nothing to render.
+                        break;
+                    case 'REASONING_START':
+                    case 'REASONING_END':
+                    case 'REASONING_MESSAGE_END':
+                    case 'THINKING_START':
+                    case 'THINKING_END':
+                    case 'THINKING_TEXT_MESSAGE_END':
+                        // Reasoning lifecycle markers; the step is built from accumulated text at close.
+                        break;
+                    case 'RUN_ERROR':
+                        throw new AgUiRunError(ev.message, ev.code);
+                    case 'RUN_FINISHED': {
+                        // A HITL interrupt arrives here as `outcome`. Instead of closing the
+                        // 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.
+                        this.opts.onRunFinished?.({ outcome: ev.outcome, result: ev.result });
+                        const interrupt = firstInterrupt(ev.outcome);
+                        if (interrupt) {
+                            this.pendingInterrupt = 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.
+                        }
+                        break;
+                    }
+                    case 'CUSTOM':
+                        // Generative UI: an agent dispatches rendered Carbon items. Only the
+                        // `carbon.item` / `carbon.items` names carry items; any other CUSTOM
+                        // name is surfaced via onEvent only (handled by the default arm below).
+                        if (ev.name === 'carbon.item') {
+                            await dispatchCarbonItem(ev.value);
+                        }
+                        else if (ev.name === 'carbon.items' && Array.isArray(ev.value)) {
+                            for (const it of ev.value)
+                                await dispatchCarbonItem(it);
+                        }
+                        break;
+                    default:
+                        // RUN_STARTED / STEP_* / RAW / other CUSTOM: surfaced via onEvent only.
+                        break;
+                }
+            }
+        }
+        catch (err) {
+            if (!options.signal?.aborted)
+                throw err;
+        }
+        // Stream ended (RUN_FINISHED, exhausted, or aborted): close anything still open.
+        // Tool chunks have no END, so any still-open tools are finalized here. Non-chunk
+        // runs leave openTools empty (TOOL_CALL_END already drained them), so this is a no-op.
+        for (const [id, tc] of openTools) {
+            openTools.delete(id);
+            await finalizeToolCall(tc);
+        }
+        const stopped = options.signal?.aborted ?? false;
+        for (const [id, text] of openText) {
+            const item = textItem(id, text, stopped);
+            items.push(item);
+            this.upsertMessage({ id, role: 'assistant', content: text });
+            await emit({ complete_item: item, streaming_metadata: meta });
+        }
+        // One reasoning step per accumulated key; drop empties. Coexists with chain_of_thought.
+        const reasoningSteps = [];
+        for (const [, text] of reasoningText) {
+            if (text)
+                reasoningSteps.push({ title: 'Reasoning', content: text });
+        }
+        const messageOptions = {
+            ...(steps.length ? { chain_of_thought: steps } : {}),
+            ...(reasoningSteps.length ? { reasoning: { steps: reasoningSteps } } : {}),
+        };
+        // ponytail: chain-of-thought/reasoning only land on final_response; attach partial_response to chunks if live status is wanted.
+        await emit({
+            final_response: {
+                id: runId,
+                request_id: requestId,
+                output: { generic: items },
+                ...(Object.keys(messageOptions).length ? { message_options: messageOptions } : {}),
+            },
+        });
+    }
+}
+function parseJsonLoose(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        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 ?? {};
+    const data = {
+        kind: 'interrupt',
+        interruptId: interrupt.id,
+        message: interrupt.message ?? raw.message,
+        action: raw.action,
+        args: raw.args,
+        responseSchema: interrupt.responseSchema,
+        toolCallId: interrupt.toolCallId,
+    };
+    return {
+        response_type: 'user_defined',
+        user_defined: data,
+        streaming_metadata: { id: interrupt.id },
+    };
+}
+/** Map a decision to a resume entry per docs/hitl-interrupt-resume.md. */
+function decisionToResumeEntry(decision, interruptId) {
+    switch (decision.type) {
+        case 'approve':
+            return { interruptId, status: 'resolved', payload: { approved: true } };
+        case 'edit':
+            return { interruptId, status: 'resolved', payload: { approved: true, args: decision.args } };
+        case 'reject':
+            return { interruptId, status: 'cancelled', payload: null };
+    }
+}
+/** Convenience: returns just the customSendMessage function. */
+export function createAgUiSendMessage(opts) {
+    return new CarbonAgUiAdapter(opts).sendMessage;
+}
+/** Resolve a JSON Pointer to its `{ parent, key }` within the `{ doc }` working root. */
+function resolvePointer(root, path) {
+    if (path !== '' && !path.startsWith('/'))
+        throw new Error(`Bad JSON Pointer: ${path}`);
+    const tokens = path === '' ? [] : path.slice(1).split('/').map((t) => t.replace(/~1/g, '/').replace(/~0/g, '~'));
+    const keys = ['doc', ...tokens];
+    const key = keys.pop();
+    let parent = root;
+    for (const k of keys) {
+        if (parent === null || typeof parent !== 'object')
+            throw new Error(`Path not found: ${path}`);
+        parent = parent[k];
+    }
+    return { parent, key };
+}
+function getAt(root, path) {
+    const { parent, key } = resolvePointer(root, path);
+    if (Array.isArray(parent))
+        return parent[key === '-' ? parent.length - 1 : Number(key)];
+    if (parent !== null && typeof parent === 'object')
+        return parent[key];
+    throw new Error(`Path not found: ${path}`);
+}
+function addAt(root, path, value) {
+    const { parent, key } = resolvePointer(root, path);
+    if (Array.isArray(parent))
+        parent.splice(key === '-' ? parent.length : Number(key), 0, value);
+    else if (parent !== null && typeof parent === 'object')
+        parent[key] = value;
+    else
+        throw new Error(`Path not found: ${path}`);
+}
+function replaceAt(root, path, value) {
+    const { parent, key } = resolvePointer(root, path);
+    if (Array.isArray(parent))
+        parent[Number(key)] = value;
+    else if (parent !== null && typeof parent === 'object')
+        parent[key] = value;
+    else
+        throw new Error(`Path not found: ${path}`);
+}
+function removeAt(root, path) {
+    const { parent, key } = resolvePointer(root, path);
+    if (Array.isArray(parent))
+        parent.splice(key === '-' ? parent.length - 1 : Number(key), 1);
+    else if (parent !== null && typeof parent === 'object')
+        delete parent[key];
+    else
+        throw new Error(`Path not found: ${path}`);
+}
+// ponytail: hand-rolled RFC 6902 (add/replace/remove/move/copy/test) — zero-dep by design,
+// see the note at the top of types.ts. Swap for fast-json-patch if perf on huge docs matters.
+export function applyJsonPatch(doc, ops) {
+    const root = { doc: structuredClone(doc) };
+    for (const op of ops) {
+        switch (op.op) {
+            case 'add':
+                addAt(root, op.path, op.value);
+                break;
+            case 'replace':
+                replaceAt(root, op.path, op.value);
+                break;
+            case 'remove':
+                removeAt(root, op.path);
+                break;
+            case 'move': {
+                if (op.from == null)
+                    throw new Error(`Missing "from" for move: ${op.path}`);
+                const value = getAt(root, op.from);
+                removeAt(root, op.from);
+                addAt(root, op.path, value);
+                break;
+            }
+            case 'copy': {
+                if (op.from == null)
+                    throw new Error(`Missing "from" for copy: ${op.path}`);
+                addAt(root, op.path, structuredClone(getAt(root, op.from)));
+                break;
+            }
+            case 'test': {
+                const actual = getAt(root, op.path);
+                if (JSON.stringify(actual) !== JSON.stringify(op.value)) {
+                    throw new Error(`JSON Patch test failed: ${op.path}`);
+                }
+                break;
+            }
+            default:
+                throw new Error(`Unsupported JSON Patch op: ${op.op}`);
+        }
+    }
+    return root.doc;
+}

package/dist/coverage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * - `handled`     — the adapter actively translates/emits this.
+ * - `observed`    — surfaced via lifecycle/onEvent only, no Carbon output by design.
+ * - `not-applicable` — out of this adapter's scope, with a reason (counts as green).
+ * - `gap`         — should be covered, isn't yet (the epic's open work).
+ */
+export type CoverageStatus = 'handled' | 'observed' | 'not-applicable' | 'gap';
+export interface CoverageEntry {
+    status: CoverageStatus;
+    note: string;
+    /** kata issue that closes this gap, when status is `gap`. */
+    issue?: string;
+}
+/** Green = covered; only `gap` is red. */
+export declare function isGap(e: CoverageEntry): boolean;
+export declare const AG_UI_COVERAGE: Record<string, CoverageEntry>;
+export declare const CARBON_COVERAGE: Record<string, CoverageEntry>;
+export interface CoverageGaps {
+    agUi: string[];
+    carbon: string[];
+    /** Total unresolved gaps across both axes; 0 = epic DoD met. */
+    total: number;
+}
+/** List every `gap` entry on each axis. */
+export declare function coverageGaps(): CoverageGaps;

package/dist/coverage.js

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// Coverage matrix — the epic's definition-of-done gate (issue xte5).
+//
+// Two declared maps: every AG-UI EventType × how the adapter treats it, and
+// every Carbon MessageResponseType × whether the adapter can emit it. The gate
+// (scripts/coverage.ts + test/coverage.test.ts) cross-checks these keys against
+// the *installed* enums (@ag-ui/core EventType, @carbon/ai-chat's declared
+// MessageResponseTypes) so the matrix stays honest as upstream evolves and no
+// entry is hand-invented or left stale.
+//
+// "Done" for the completeness epic = zero `gap` entries (`bun run coverage`
+// exits 0). Builders closing a child issue flip their entries from `gap` to
+// `handled` here — that is how the matrix goes green.
+// ---------------------------------------------------------------------------
+/** Green = covered; only `gap` is red. */
+export function isGap(e) {
+    return e.status === 'gap';
+}
+// AG-UI EventType → adapter handling. Keys must equal @ag-ui/core's EventType.
+export const AG_UI_COVERAGE = {
+    RUN_STARTED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
+    RUN_FINISHED: { status: 'handled', note: 'Closes turn; interrupt outcome → decision card. Non-interrupt outcomes: 9ma7.' },
+    RUN_ERROR: { status: 'handled', note: 'Thrown as AgUiRunError.' },
+    STEP_STARTED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
+    STEP_FINISHED: { status: 'observed', note: 'Lifecycle; onEvent only.' },
+    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.' },
+    TEXT_MESSAGE_CHUNK: { status: 'handled', note: 'Combined text variant; first chunk carries id, deltas streamed, finalized at close.' },
+    TOOL_CALL_START: { status: 'handled', note: 'Opens a tool call.' },
+    TOOL_CALL_ARGS: { status: 'handled', note: 'Accumulates tool args.' },
+    TOOL_CALL_END: { status: 'handled', note: 'Chain-of-thought step + onToolCall hook.' },
+    TOOL_CALL_CHUNK: { status: 'handled', note: 'Combined tool variant; first chunk carries id+name, args accumulated, finalized at close.' },
+    TOOL_CALL_RESULT: { status: 'handled', note: 'Fills the chain-of-thought step response.' },
+    STATE_SNAPSHOT: { status: 'handled', note: 'Replaces adapter state.' },
+    STATE_DELTA: { status: 'handled', note: 'Full RFC 6902 JSON-Patch (add/replace/remove/move/copy/test).' },
+    MESSAGES_SNAPSHOT: { status: 'handled', note: 'Renders newly-present assistant messages.' },
+    THINKING_START: { status: 'handled', note: 'Deprecated reasoning-start alias; lifecycle marker.' },
+    THINKING_END: { status: 'handled', note: 'Deprecated reasoning-end alias; lifecycle marker.' },
+    THINKING_TEXT_MESSAGE_START: { status: 'handled', note: 'Opens the implicit thinking reasoning step.' },
+    THINKING_TEXT_MESSAGE_CONTENT: { status: 'handled', note: 'Accumulates thinking text (no messageId).' },
+    THINKING_TEXT_MESSAGE_END: { status: 'handled', note: 'Closes the thinking reasoning step.' },
+    REASONING_START: { status: 'handled', note: 'Reasoning lifecycle marker.' },
+    REASONING_END: { status: 'handled', note: 'Reasoning lifecycle marker.' },
+    REASONING_MESSAGE_START: { status: 'handled', note: 'Opens a reasoning step per messageId.' },
+    REASONING_MESSAGE_CONTENT: { status: 'handled', note: 'Accumulates reasoning text.' },
+    REASONING_MESSAGE_END: { status: 'handled', note: 'Closes a reasoning step; rendered on final_response.' },
+    REASONING_MESSAGE_CHUNK: { status: 'handled', note: 'Combined reasoning variant; delta accumulated.' },
+    REASONING_ENCRYPTED_VALUE: { status: 'handled', note: 'Encrypted; no displayable text, explicit no-op.' },
+    ACTIVITY_SNAPSHOT: { status: 'handled', note: 'Reconciled into activities map (authoritative); exposed via onActivity.' },
+    ACTIVITY_DELTA: { status: 'handled', note: 'JSON-Patch applied onto activity content; exposed via onActivity.' },
+    RAW: { status: 'observed', note: 'Passthrough; onEvent only.' },
+    CUSTOM: { status: 'handled', note: "Dispatched as rendered Carbon items via name 'carbon.item'/'carbon.items'." },
+};
+// Carbon MessageResponseType → can the adapter emit it. Keys must equal
+// @carbon/ai-chat's MessageResponseTypes enum values.
+export const CARBON_COVERAGE = {
+    text: { status: 'handled', note: 'Streamed + complete text items.' },
+    user_defined: { status: 'handled', note: 'HITL decision card; host payload passthrough.' },
+    connect_to_agent: { status: 'not-applicable', note: 'Human-agent escalation needs a service desk; out of adapter scope.' },
+    option: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonOptionItem, shape compile-proven in carbon-compat.ts.' },
+    image: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonImageItem, shape compile-proven in carbon-compat.ts.' },
+    video: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonVideoItem, shape compile-proven in carbon-compat.ts.' },
+    audio: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonAudioItem, shape compile-proven in carbon-compat.ts.' },
+    iframe: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonIFrameItem, shape compile-proven in carbon-compat.ts.' },
+    date: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonDateItem, shape compile-proven in carbon-compat.ts.' },
+    card: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonCardItem, shape compile-proven in carbon-compat.ts.' },
+    carousel: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonCarouselItem, shape compile-proven in carbon-compat.ts.' },
+    button: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonButtonItem, shape compile-proven in carbon-compat.ts.' },
+    grid: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonGridItem, shape compile-proven in carbon-compat.ts.' },
+    preview_card: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonPreviewCardItem, shape compile-proven in carbon-compat.ts.' },
+    conversational_search: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonConversationalSearchItem, shape compile-proven in carbon-compat.ts.' },
+    pause: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonPauseItem, shape compile-proven in carbon-compat.ts.' },
+    inline_error: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonInlineErrorItem, shape compile-proven in carbon-compat.ts.' },
+    system: { status: 'handled', note: 'Emittable via CUSTOM carbon.item dispatch; typed as CarbonSystemMessageItem, shape compile-proven in carbon-compat.ts.' },
+};
+/** List every `gap` entry on each axis. */
+export function coverageGaps() {
+    const agUi = Object.entries(AG_UI_COVERAGE).filter(([, e]) => isGap(e)).map(([k]) => k);
+    const carbon = Object.entries(CARBON_COVERAGE).filter(([, e]) => isGap(e)).map(([k]) => k);
+    return { agUi, carbon, total: agUi.length + carbon.length };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './adapter.js';
+export * from './transport.js';
+export * from './coverage.js';
+export * from './validate.js';