@hsb3/carbon-agui-adapter 0.1.0

package/dist/index.js

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

package/dist/transport.d.ts

@@ -0,0 +1,22 @@
+import type { AgUiEvent, AgUiRunner } from './types.js';
+export interface SseRunnerOptions {
+    url: string;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    fetch?: typeof fetch;
+}
+/** 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>;
+/** Minimal rxjs-compatible shape, so `@ag-ui/client`'s `agent.run(input)` plugs in without importing rxjs here. */
+export interface ObservableLike<T> {
+    subscribe(observer: {
+        next: (v: T) => void;
+        error: (e: unknown) => void;
+        complete: () => void;
+    }): {
+        unsubscribe(): void;
+    };
+}
+/** Bridge an Observable (e.g. `new HttpAgent({url}).run(input)`) to the AsyncIterable the adapter consumes. */
+export declare function fromObservable<T>(obs: ObservableLike<T>, signal?: AbortSignal): AsyncGenerator<T>;

package/dist/transport.js

@@ -0,0 +1,93 @@
+/** POST RunAgentInput as JSON, read back `text/event-stream` of AG-UI events. */
+export function createSseRunner(opts) {
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    return async function* (input, { signal }) {
+        const extra = typeof opts.headers === 'function' ? await opts.headers() : opts.headers ?? {};
+        const res = await doFetch(opts.url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'text/event-stream', ...extra },
+            body: JSON.stringify(input),
+            signal,
+        });
+        if (!res.ok || !res.body)
+            throw new Error(`AG-UI request failed: HTTP ${res.status}`);
+        yield* parseSse(res.body);
+    };
+}
+/** Parse an SSE byte stream into AG-UI events (one JSON object per `data:` block). */
+export async function* parseSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    const drain = function* (final) {
+        let idx;
+        while ((idx = buf.indexOf('\n\n')) !== -1) {
+            const block = buf.slice(0, idx);
+            buf = buf.slice(idx + 2);
+            const ev = parseBlock(block);
+            if (ev)
+                yield ev;
+        }
+        if (final && buf.trim()) {
+            const ev = parseBlock(buf);
+            buf = '';
+            if (ev)
+                yield ev;
+        }
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true }).replace(/\r\n/g, '\n');
+            yield* drain(false);
+        }
+        buf += decoder.decode();
+        yield* drain(true);
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function parseBlock(block) {
+    const data = block
+        .split('\n')
+        .filter((l) => l.startsWith('data:'))
+        .map((l) => l.slice(5).replace(/^ /, ''))
+        .join('\n');
+    return data ? JSON.parse(data) : null;
+}
+/** Bridge an Observable (e.g. `new HttpAgent({url}).run(input)`) to the AsyncIterable the adapter consumes. */
+export async function* fromObservable(obs, signal) {
+    const queue = [];
+    let done = false;
+    let error;
+    let wake;
+    const notify = () => { wake?.(); wake = undefined; };
+    const sub = obs.subscribe({
+        next: (v) => { queue.push(v); notify(); },
+        error: (e) => { error = e; done = true; notify(); },
+        complete: () => { done = true; notify(); },
+    });
+    const onAbort = () => { error = signal?.reason ?? new Error('aborted'); done = true; notify(); };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for (;;) {
+            if (queue.length) {
+                yield queue.shift();
+                continue;
+            }
+            if (done) {
+                if (error !== undefined)
+                    throw error;
+                return;
+            }
+            await new Promise((r) => { wake = r; });
+        }
+    }
+    finally {
+        sub.unsubscribe();
+        signal?.removeEventListener('abort', onAbort);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,460 @@
+export type AgUiRole = 'developer' | 'system' | 'assistant' | 'user' | 'tool';
+export interface AgUiToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface AgUiMessage {
+    id: string;
+    role: AgUiRole;
+    content?: string;
+    name?: string;
+    toolCalls?: AgUiToolCall[];
+    toolCallId?: string;
+}
+export interface AgUiTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+export interface AgUiContext {
+    description: string;
+    value: string;
+}
+export interface RunAgentInput {
+    threadId: string;
+    runId: string;
+    state: unknown;
+    messages: AgUiMessage[];
+    tools: AgUiTool[];
+    context: AgUiContext[];
+    forwardedProps: unknown;
+    /** Resume a suspended run (LangGraph interrupt). One entry per interrupt. */
+    resume?: ResumeEntry[];
+}
+/** A single LangGraph interrupt, as promoted into `RUN_FINISHED.outcome`. */
+export interface Interrupt {
+    id: string;
+    reason?: string;
+    message?: string;
+    toolCallId?: string;
+    /** Graph-supplied JSON schema for the expected resume payload. */
+    responseSchema?: unknown;
+    /** The original `interrupt()` value verbatim lives under langgraph.raw. */
+    metadata?: {
+        langgraph?: {
+            raw?: {
+                action?: string;
+                args?: Record<string, unknown>;
+                message?: string;
+                [k: string]: unknown;
+            };
+        };
+    };
+}
+/** `RUN_FINISHED.outcome` — only the interrupt variant is handled here. */
+export interface RunOutcome {
+    type: string;
+    interrupts?: Interrupt[];
+}
+export type ResumeStatus = 'resolved' | 'cancelled';
+/** One resume decision on the wire (`RunAgentInput.resume[]`). */
+export interface ResumeEntry {
+    interruptId: string;
+    status: ResumeStatus;
+    payload: unknown;
+}
+/** A user's decision on an interrupt. Edit carries the overriding args. */
+export type Decision = {
+    type: 'approve';
+} | {
+    type: 'edit';
+    args: Record<string, unknown>;
+} | {
+    type: 'reject';
+};
+/**
+ * Payload carried in the Carbon `user_defined` item's `user_defined` field so a
+ * host renderer can draw the approve/reject/edit card. `kind` discriminates it
+ * from any other user_defined response the host may render.
+ */
+export interface InterruptDecisionData {
+    kind: 'interrupt';
+    interruptId: string;
+    message?: string;
+    action?: string;
+    args?: Record<string, unknown>;
+    responseSchema?: unknown;
+    toolCallId?: string;
+}
+export interface JsonPatchOp {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    value?: unknown;
+    from?: string;
+}
+export type AgUiEvent = {
+    type: 'RUN_STARTED';
+    threadId: string;
+    runId: string;
+} | {
+    type: 'RUN_FINISHED';
+    threadId: string;
+    runId: string;
+    result?: unknown;
+    outcome?: RunOutcome;
+} | {
+    type: 'RUN_ERROR';
+    message: string;
+    code?: string;
+} | {
+    type: 'STEP_STARTED';
+    stepName: string;
+} | {
+    type: 'STEP_FINISHED';
+    stepName: string;
+} | {
+    type: 'TEXT_MESSAGE_START';
+    messageId: string;
+    role: 'assistant';
+} | {
+    type: 'TEXT_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'TEXT_MESSAGE_END';
+    messageId: string;
+} | {
+    type: 'TEXT_MESSAGE_CHUNK';
+    messageId?: string;
+    role?: 'assistant';
+    delta?: string;
+} | {
+    type: 'TOOL_CALL_START';
+    toolCallId: string;
+    toolCallName: string;
+    parentMessageId?: string;
+} | {
+    type: 'TOOL_CALL_ARGS';
+    toolCallId: string;
+    delta: string;
+} | {
+    type: 'TOOL_CALL_END';
+    toolCallId: string;
+} | {
+    type: 'TOOL_CALL_CHUNK';
+    toolCallId?: string;
+    toolCallName?: string;
+    parentMessageId?: string;
+    delta?: string;
+} | {
+    type: 'TOOL_CALL_RESULT';
+    messageId: string;
+    toolCallId: string;
+    content: string;
+    role?: 'tool';
+} | {
+    type: 'STATE_SNAPSHOT';
+    snapshot: unknown;
+} | {
+    type: 'STATE_DELTA';
+    delta: JsonPatchOp[];
+} | {
+    type: 'MESSAGES_SNAPSHOT';
+    messages: AgUiMessage[];
+} | {
+    type: 'REASONING_START';
+    messageId: string;
+} | {
+    type: 'REASONING_END';
+    messageId: string;
+} | {
+    type: 'REASONING_MESSAGE_START';
+    messageId: string;
+    role: 'reasoning';
+} | {
+    type: 'REASONING_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'REASONING_MESSAGE_END';
+    messageId: string;
+} | {
+    type: 'REASONING_MESSAGE_CHUNK';
+    messageId?: string;
+    delta?: string;
+} | {
+    type: 'REASONING_ENCRYPTED_VALUE';
+    subtype: 'tool-call' | 'message';
+    entityId: string;
+    encryptedValue: string;
+} | {
+    type: 'ACTIVITY_SNAPSHOT';
+    messageId: string;
+    activityType: string;
+    content: Record<string, unknown>;
+    replace?: boolean;
+} | {
+    type: 'ACTIVITY_DELTA';
+    messageId: string;
+    activityType: string;
+    patch: JsonPatchOp[];
+} | {
+    type: 'THINKING_START';
+    title?: string;
+} | {
+    type: 'THINKING_END';
+} | {
+    type: 'THINKING_TEXT_MESSAGE_START';
+} | {
+    type: 'THINKING_TEXT_MESSAGE_CONTENT';
+    delta: string;
+} | {
+    type: 'THINKING_TEXT_MESSAGE_END';
+} | {
+    type: 'RAW';
+    event: unknown;
+    source?: string;
+} | {
+    type: 'CUSTOM';
+    name: string;
+    value: unknown;
+};
+/** Transport: given a run input, yield AG-UI events. Must respect `signal`. */
+export type AgUiRunner = (input: RunAgentInput, opts: {
+    signal?: AbortSignal;
+}) => AsyncIterable<AgUiEvent>;
+export interface CarbonMessageRequest {
+    id?: string;
+    input: {
+        text?: string;
+    };
+    thread_id?: string;
+}
+export interface CarbonItemStreamingMetadata {
+    id: string;
+    stream_stopped?: boolean;
+    cancellable?: boolean;
+}
+/**
+ * Mirrors Carbon's `GenericItemMessageFeedbackOptions` — thumbs-up/down config.
+ * Attaches per-item via `message_item_options.feedback` (NOT per-response
+ * message_options). `is_on` toggles the control; `id` is required for the
+ * feedback to persist in history. carbon-compat.ts proves this lines up.
+ */
+export interface CarbonMessageFeedbackOptions {
+    is_on?: boolean;
+    id?: string;
+    categories?: string[] | {
+        positive?: string[];
+        negative?: string[];
+    };
+    max_length?: number;
+    title?: string;
+    prompt?: string;
+    placeholder?: string;
+}
+export interface CarbonGenericItem {
+    response_type: string;
+    streaming_metadata?: CarbonItemStreamingMetadata;
+    text?: string;
+    /** Carbon's `UserDefinedItem.user_defined` bucket — arbitrary host payload. */
+    user_defined?: Record<string, unknown>;
+    /** Carbon's per-item `message_item_options` — carries feedback (thumbs) config. */
+    message_item_options?: {
+        feedback?: CarbonMessageFeedbackOptions;
+    };
+}
+export interface CarbonTextItem extends CarbonGenericItem {
+    response_type: 'text';
+    text: string;
+}
+/** A Carbon `user_defined` response item; the host renders it via `renderUserDefinedResponse`. */
+export interface CarbonUserDefinedItem extends CarbonGenericItem {
+    response_type: 'user_defined';
+    user_defined: Record<string, unknown>;
+}
+/** Carbon `button` item. `button_type` runtime values: post_back | custom_event | show_panel | url. */
+export interface CarbonButtonItem extends CarbonGenericItem {
+    response_type: 'button';
+    button_type: string;
+    label?: string;
+    url?: string;
+    kind?: string;
+}
+/** Carbon `card` item — a container that renders nested response items. */
+export interface CarbonCardItem extends CarbonGenericItem {
+    response_type: 'card';
+    body?: CarbonGenericItem[];
+    footer?: CarbonGenericItem[];
+    max_width?: string;
+}
+/** Carbon `option` item — a list of choices rendered as buttons or a dropdown. */
+export interface CarbonOptionItem extends CarbonGenericItem {
+    response_type: 'option';
+    options: {
+        label: string;
+        value: {
+            input: {
+                text?: string;
+            };
+        };
+    }[];
+    title?: string;
+    description?: string;
+}
+/** Carbon `image` item. */
+export interface CarbonImageItem extends CarbonGenericItem {
+    response_type: 'image';
+    source: string;
+    title?: string;
+    description?: string;
+    alt_text?: string;
+}
+/** Carbon `video` item. */
+export interface CarbonVideoItem extends CarbonGenericItem {
+    response_type: 'video';
+    source: string;
+    title?: string;
+    description?: string;
+    alt_text?: string;
+}
+/** Carbon `audio` item. */
+export interface CarbonAudioItem extends CarbonGenericItem {
+    response_type: 'audio';
+    source: string;
+    title?: string;
+    description?: string;
+    alt_text?: string;
+}
+/** Carbon `iframe` item. */
+export interface CarbonIFrameItem extends CarbonGenericItem {
+    response_type: 'iframe';
+    source: string;
+    title?: string;
+    description?: string;
+}
+/** Carbon `date` item — prompts a date picker; carries no fields beyond the base. */
+export interface CarbonDateItem extends CarbonGenericItem {
+    response_type: 'date';
+}
+/** Carbon `pause` item — a rendering pause before subsequent items. */
+export interface CarbonPauseItem extends CarbonGenericItem {
+    response_type: 'pause';
+    time?: number;
+    typing?: boolean;
+}
+/** Carbon `inline_error` item — a user-friendly inline error message. */
+export interface CarbonInlineErrorItem extends CarbonGenericItem {
+    response_type: 'inline_error';
+    text?: string;
+}
+/** Carbon `system` item — a status / informational system line. */
+export interface CarbonSystemMessageItem extends CarbonGenericItem {
+    response_type: 'system';
+    title: string;
+    variant?: 'default' | 'date' | 'agent';
+}
+/** Carbon `carousel` item — a horizontally-scrolling set of nested items. */
+export interface CarbonCarouselItem extends CarbonGenericItem {
+    response_type: 'carousel';
+    items: CarbonGenericItem[];
+}
+/** Carbon `grid` item — a column/row layout of nested items. */
+export interface CarbonGridItem extends CarbonGenericItem {
+    response_type: 'grid';
+    columns: {
+        width: string;
+    }[];
+    rows: {
+        cells: {
+            items: CarbonGenericItem[];
+        }[];
+    }[];
+}
+/** Carbon `preview_card` item — a card that can trigger a workspace view. */
+export interface CarbonPreviewCardItem extends CarbonGenericItem {
+    response_type: 'preview_card';
+    workspace_id: string;
+    title?: string;
+    subtitle?: string;
+}
+/** Carbon `conversational_search` item — AI text with optional source citations. */
+export interface CarbonConversationalSearchItem extends CarbonGenericItem {
+    response_type: 'conversational_search';
+    text: string;
+    citations?: {
+        url?: string;
+        text?: string;
+        title?: string;
+    }[];
+}
+/**
+ * Every Carbon response item the adapter can emit, discriminated by
+ * `response_type`. Carbon renders each natively except `user_defined`.
+ */
+export type CarbonResponseItem = CarbonTextItem | CarbonUserDefinedItem | CarbonButtonItem | CarbonCardItem | CarbonOptionItem | CarbonImageItem | CarbonVideoItem | CarbonAudioItem | CarbonIFrameItem | CarbonDateItem | CarbonPauseItem | CarbonInlineErrorItem | CarbonSystemMessageItem | CarbonCarouselItem | CarbonGridItem | CarbonPreviewCardItem | CarbonConversationalSearchItem;
+/** Maps to Carbon's ChainOfThoughtStep — how Carbon renders tool calls. */
+export interface CarbonChainOfThoughtStep {
+    title?: string;
+    description?: string;
+    tool_name?: string;
+    request?: {
+        args?: unknown;
+    };
+    response?: {
+        content: unknown;
+    };
+    status?: 'processing' | 'failure' | 'success';
+}
+/** Maps to Carbon's ReasoningStep. `content` mirrors Carbon's `string | GenericItem[]`; the adapter only emits the string form. */
+export interface CarbonReasoningStep {
+    title: string;
+    open_state?: 'open' | 'close' | 'default';
+    content?: string | CarbonGenericItem[];
+}
+/** Maps to Carbon's ReasoningSteps — the reasoning sibling of chain_of_thought. */
+export interface CarbonReasoningSteps {
+    open_state?: 'open' | 'close' | 'default';
+    steps?: CarbonReasoningStep[];
+    content?: string | CarbonGenericItem[];
+}
+export interface CarbonMessageResponse {
+    id?: string;
+    request_id?: string;
+    output: {
+        generic?: CarbonGenericItem[];
+    };
+    thread_id?: string;
+    message_options?: {
+        chain_of_thought?: CarbonChainOfThoughtStep[];
+        reasoning?: CarbonReasoningSteps;
+    };
+}
+export type CarbonStreamChunk = {
+    partial_item: Partial<CarbonGenericItem>;
+    streaming_metadata?: {
+        response_id: string;
+    };
+} | {
+    complete_item: CarbonGenericItem;
+    streaming_metadata?: {
+        response_id: string;
+    };
+} | {
+    final_response: CarbonMessageResponse;
+};
+export interface CarbonSendMessageOptions {
+    signal?: AbortSignal;
+    silent?: boolean;
+}
+export interface CarbonChatInstanceLike {
+    messaging: {
+        addMessageChunk(chunk: CarbonStreamChunk): void | Promise<void>;
+    };
+}
+/** Shape of `PublicConfigMessaging.customSendMessage`. */
+export type CarbonCustomSendMessage = (request: CarbonMessageRequest, options: CarbonSendMessageOptions, instance: CarbonChatInstanceLike) => Promise<void>;

package/dist/types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// AG-UI (https://docs.ag-ui.com) — structural mirror of @ag-ui/core.
+// Kept local so the adapter has zero runtime deps; swap for @ag-ui/core if wanted.
+// ---------------------------------------------------------------------------
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,28 @@
+import type { AgUiEvent, CarbonGenericItem } from './types.js';
+/**
+ * IN seam. Validate a raw runner event against the AG-UI protocol schema.
+ * On success the parsed value is a canonical event; the cast to the adapter's
+ * local `AgUiEvent` is justified because it was validated against the
+ * protocol's own union and the local type is a structural subset the switch
+ * handles. On failure, `error` is zod's error summary.
+ */
+export declare function validateAgUiEvent(raw: unknown): {
+    ok: true;
+    event: AgUiEvent;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * OUT seam. Validate a raw CUSTOM-carried Carbon item before the adapter emits
+ * it: it must be an object, carry a `response_type` string in `known` (the
+ * adapter passes its KNOWN_CARBON_TYPES allowlist so this file needs no coverage
+ * import), and satisfy the required top-level fields for that response_type.
+ */
+export declare function validateCarbonItem(raw: unknown, known: Set<string>): {
+    ok: true;
+    item: CarbonGenericItem;
+} | {
+    ok: false;
+    reason: string;
+};