@adonis-agora/agent 0.70.1 → 0.71.0

package/dist/src/a2ui/adapter.js

@@ -0,0 +1,223 @@
+import { decodeInterruptId } from '../ag-ui/core/interrupt-id.js';
+import { agUiEvents } from '../ag-ui/stream.js';
+import { uiActionText } from '../genui/actions.js';
+import { validateUiCapabilities } from '../genui/capabilities.js';
+import { A2UI_APPROVE_ACTION, A2UI_REJECT_ACTION, A2uiProjector, readA2uiAction, } from './core.js';
+const VIA = 'a2ui';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Serve the agent as an A2UI (https://a2ui.org, v0.9) agent: `POST <path>/a2ui` answers with the
+ * run as a JSON Lines stream of A2UI server-to-client messages — `createSurface`,
+ * `updateComponents`, `updateDataModel`, `deleteSurface` — that any A2UI renderer draws.
+ *
+ * ```ts
+ * import { a2uiAdapter } from '@adonis-agora/agent/a2ui'
+ *
+ * export default defineConfig({ adapters: [a2uiAdapter()] })
+ * ```
+ *
+ * The body is `{ threadId?, message?, action?, uiCapabilities?, agent? }`:
+ *  - `message` — the user's text;
+ *  - `action` — an A2UI client message (`{ version: 'v0.9', action: { name, surfaceId,
+ *    sourceComponentId, timestamp, context } }`, or v0.8's `{ userAction }`): it becomes the turn
+ *    (`uiActionText`). `agora.approve` / `agora.reject` with `context.interruptId` decide the
+ *    approval a previous stream ended on, and stream the rest of that run;
+ *  - `threadId` — continue that thread (its owner is checked), or start one under that id.
+ *
+ * Response headers name the library's ids: `X-Agent-Thread-Id`, `X-Agent-Run-Id`. Authenticated and
+ * owner-scoped exactly as `chat` is.
+ */
+export function a2uiAdapter(options = {}) {
+    const path = (options.path ?? 'a2ui').replace(/^\/+|\/+$/g, '');
+    const { path: _path, quietMs, maxActionBytes, ...projection } = options;
+    return {
+        name: 'a2ui',
+        mount(host) {
+            const { service } = host;
+            host.post(path, async (ctx) => {
+                const body = ctx.request.body();
+                const agentName = typeof body.agent === 'string' && body.agent.length > 0 ? body.agent : undefined;
+                const actor = await host.resolveActor(ctx, agentName ?? host.defaultAgentName);
+                if (actor === null)
+                    return;
+                let action;
+                if (body.action !== undefined) {
+                    const read = isRecord(body.action)
+                        ? readA2uiAction(body.action, {
+                            ...(maxActionBytes !== undefined ? { maxBytes: maxActionBytes } : {}),
+                        })
+                        : 'action must be an A2UI action message';
+                    if (typeof read === 'string') {
+                        return ctx.response.badRequest({ message: read, code: 'invalid_action' });
+                    }
+                    action = read;
+                }
+                // Deciding the approval a stream ended on: settle it, then stream the rest of the run.
+                if (action?.name === A2UI_APPROVE_ACTION || action?.name === A2UI_REJECT_ACTION) {
+                    const interruptId = action.context.interruptId;
+                    const address = typeof interruptId === 'string' ? decodeInterruptId(interruptId) : undefined;
+                    if (address === undefined || address === null || address.kind === 'elicitation') {
+                        return ctx.response.badRequest({
+                            message: 'an approval action carries the interruptId it decides',
+                            code: 'invalid_action',
+                        });
+                    }
+                    // An independent proposal: decided through the proposal service (its own run is not
+                    // waiting), answered with the configured reply.
+                    if (address.kind === 'proposal') {
+                        if (address.proposalId === undefined || address.threadId === undefined) {
+                            return ctx.response.badRequest({
+                                message: 'the interruptId names no proposal',
+                                code: 'invalid_action',
+                            });
+                        }
+                        const decision = action.name === A2UI_APPROVE_ACTION ? 'approved' : 'rejected';
+                        let reply;
+                        try {
+                            const result = await service.decideActionProposal(actor, address.threadId, address.proposalId, decision, {}, VIA);
+                            reply = service.actionProposalReply(result, decision);
+                        }
+                        catch (error) {
+                            if (host.refuseSend(ctx, error))
+                                return;
+                            throw error;
+                        }
+                        writeHead(ctx, { 'X-Agent-Thread-Id': address.threadId });
+                        const projector = new A2uiProjector(projection);
+                        const messageId = `proposal-${address.proposalId}`;
+                        for (const event of [
+                            { type: 'TEXT_MESSAGE_START', messageId, role: 'assistant' },
+                            { type: 'TEXT_MESSAGE_CONTENT', messageId, delta: reply },
+                        ]) {
+                            for (const message of projector.project(event)) {
+                                ctx.response.response.write(`${JSON.stringify(message)}\n`);
+                            }
+                        }
+                        ctx.response.response.end();
+                        return;
+                    }
+                    if (!(await host.mayDecide(ctx, actor, address.parked, address.toolCallId)))
+                        return;
+                    try {
+                        if (action.name === A2UI_APPROVE_ACTION) {
+                            await service.approve(address.parked, address.toolCallId, {
+                                executedByRef: actor.id,
+                                via: VIA,
+                            });
+                        }
+                        else {
+                            await service.reject(address.parked, address.toolCallId, undefined, {
+                                executedByRef: actor.id,
+                                via: VIA,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        host.conflictOnMismatch(ctx, error);
+                        return;
+                    }
+                    await stream(ctx, host, address.stream, {
+                        skip: address.position,
+                        answered: [address.toolCallId],
+                        projection,
+                        quietMs,
+                    });
+                    return;
+                }
+                const message = typeof body.message === 'string' ? body.message : '';
+                const text = action !== undefined ? uiActionText(action) : message;
+                if (text.trim().length === 0) {
+                    return ctx.response.badRequest({
+                        message: 'send a message or an action',
+                        code: 'no_user_message',
+                    });
+                }
+                const threadId = typeof body.threadId === 'string' && body.threadId.length > 0 ? body.threadId : undefined;
+                const owner = threadId !== undefined ? await service.threadOwner(threadId) : null;
+                if (owner !== null && !(await host.assertOwner(ctx, actor, owner, 'thread')))
+                    return;
+                let started;
+                try {
+                    started = await service.chat({
+                        actor,
+                        message: text,
+                        ...(threadId === undefined
+                            ? {}
+                            : owner !== null
+                                ? { threadId }
+                                : { newThreadId: threadId }),
+                        ...(agentName !== undefined ? { agentName } : {}),
+                        ...(Object.hasOwn(body, 'uiCapabilities')
+                            ? { uiCapabilities: validateUiCapabilities(body.uiCapabilities) }
+                            : {}),
+                    });
+                }
+                catch (error) {
+                    if (host.refuseSend(ctx, error))
+                        return;
+                    throw error;
+                }
+                await stream(ctx, host, started.runId, {
+                    threadId: started.threadId,
+                    projection,
+                    quietMs,
+                });
+            });
+        },
+    };
+}
+/** Write one run as A2UI JSON Lines, until it ends or stops to ask. */
+async function stream(ctx, host, runId, options) {
+    const raw = ctx.response.response;
+    writeHead(ctx, {
+        'X-Agent-Run-Id': runId,
+        ...(options.threadId !== undefined ? { 'X-Agent-Thread-Id': options.threadId } : {}),
+    });
+    const projector = new A2uiProjector({
+        ...options.projection,
+        ...(options.projection.catalog === undefined && host.genuiCatalog !== undefined
+            ? { catalog: host.genuiCatalog }
+            : {}),
+    });
+    const write = (messages) => {
+        for (const message of messages)
+            raw.write(`${JSON.stringify(message)}\n`);
+    };
+    try {
+        for await (const event of agUiEvents(host.service.subscribe(runId), {
+            threadId: options.threadId ?? runId,
+            runId,
+            streamRunId: runId,
+            ...(options.threadId !== undefined ? { streamThreadId: options.threadId } : {}),
+            ...(options.skip !== undefined ? { skip: options.skip } : {}),
+            ...(options.answered !== undefined ? { answered: options.answered } : {}),
+            ...(options.quietMs !== undefined ? { quietMs: options.quietMs } : {}),
+        })) {
+            write(projector.project(event));
+        }
+    }
+    catch {
+        write(projector.project({ type: 'RUN_ERROR', message: 'The run could not be followed.' }));
+    }
+    raw.end();
+}
+/** Open the JSON Lines response, carrying over the headers already set on the context (cookies). */
+function writeHead(ctx, extra) {
+    const raw = ctx.response.response;
+    const headers = {
+        'Content-Type': 'application/jsonl; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+        ...extra,
+    };
+    const pending = ctx.response.getHeaders();
+    for (const [name, value] of Object.entries(pending)) {
+        if (value !== undefined && !(name in headers))
+            raw.setHeader(name, value);
+    }
+    raw.writeHead(200, headers);
+}
+//# sourceMappingURL=adapter.js.map

package/dist/src/a2ui/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/a2ui/adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/a2ui/core.d.ts

@@ -0,0 +1,181 @@
+/**
+ * A2UI (https://a2ui.org) — Google's declarative agent-to-UI protocol — for this agent's generative
+ * UI, framework-free. Targets A2UI **v0.9** (the current production family: v0.9.1 is a patch of
+ * it; v1.0 is a release candidate).
+ *
+ *  - Outbound: a `ui` frame (one component, or a composed `genui:tree`) becomes a surface — a flat
+ *    list of A2UI components keyed by id — that any A2UI renderer (Lit, Angular, Flutter, React)
+ *    draws. Library builtins map onto A2UI's basic catalog; an app maps its own components with a
+ *    function, or sends them through as custom components of its own A2UI catalog.
+ *  - Streamed: a preview frame the model is still writing becomes the same surface, partially —
+ *    A2UI renderers draw what has arrived and leave a child that is not there yet as a placeholder.
+ *  - Inbound: an A2UI `action` (v0.9) or `userAction` (v0.8) becomes a {@link UiAction}: the next
+ *    user turn.
+ */
+import type { AgUiEvent, AgUiInterrupt } from '../ag-ui/core/types.js';
+import { type UiAction } from '../genui/actions.js';
+import type { Catalog } from '../genui/catalog.js';
+/** The A2UI protocol version every message is stamped with. */
+export declare const A2UI_VERSION = "v0.9";
+/** The catalog id of A2UI v0.9's basic catalog (what `@a2ui/react`'s `basicCatalog.id` is). */
+export declare const A2UI_BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+/** The components of A2UI v0.9's basic catalog. */
+export declare const A2UI_BASIC_COMPONENTS: readonly ['Text', 'Image', 'Icon', 'Video', 'AudioPlayer', 'Row', 'Column', 'List', 'Card', 'Tabs', 'Modal', 'Divider', 'Button', 'CheckBox', 'TextField', 'DateTimeInput', 'ChoicePicker', 'Slider'];
+/** The AG-UI activity type A2UI surfaces travel under (AG-UI's A2UI middleware, CopilotKit). */
+export declare const A2UI_ACTIVITY_TYPE = "a2ui-surface";
+/** The key of the A2UI messages in an `a2ui-surface` activity's content. */
+export declare const A2UI_OPERATIONS_KEY = "a2ui_operations";
+/** Action names the transports answer themselves: deciding a parked approval. */
+export declare const A2UI_APPROVE_ACTION = "agora.approve";
+export declare const A2UI_REJECT_ACTION = "agora.reject";
+/** One A2UI component: its id, its catalog type, and its properties flat beside them. */
+export interface A2uiComponent {
+    id: string;
+    component: string;
+    [property: string]: unknown;
+}
+/** One server-to-client A2UI message. */
+export type A2uiServerMessage = {
+    version: typeof A2UI_VERSION;
+} & ({
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+        theme?: Record<string, unknown>;
+        sendDataModel?: boolean;
+    };
+} | {
+    updateComponents: {
+        surfaceId: string;
+        components: A2uiComponent[];
+    };
+} | {
+    updateDataModel: {
+        surfaceId: string;
+        path?: string;
+        value?: unknown;
+    };
+} | {
+    deleteSurface: {
+        surfaceId: string;
+    };
+});
+/** What a mapper is handed for one node. */
+export interface A2uiMapContext {
+    /** The id the node's root component MUST take (its parent references it). */
+    id: string;
+    /** The ids of the node's children, already converted (a layout lists them). */
+    children: readonly string[];
+    /** A fresh id derived from the node's (`<id>~<suffix>`), for the extra components a mapping needs. */
+    derive(suffix: string): string;
+    /** The node is still being written (a preview): props may be missing — default them. */
+    incomplete: boolean;
+    /** The component's plain-text fallback (`fallbackText`), for a mapping that only has text. */
+    text(): string;
+}
+/**
+ * Maps one of this agent's components to A2UI components. Must return a component whose `id` is
+ * `ctx.id`; any others it adds take ids from `ctx.derive`.
+ */
+export type A2uiMapper = (props: Record<string, unknown>, ctx: A2uiMapContext) => A2uiComponent[];
+export interface A2uiOptions {
+    /**
+     * The A2UI catalog surfaces are created with. Default the basic catalog. An app that registers
+     * its own components on the client names its catalog here (and lists them in `custom`).
+     */
+    catalogId?: string;
+    /** Per component: a mapping to A2UI (overrides a builtin's), or `'custom'` to send it as is. */
+    components?: Record<string, A2uiMapper | 'custom'>;
+    /**
+     * A component with no mapping: `'text'` (default) draws its `fallbackText` as an A2UI `Text`;
+     * `'custom'` sends it as a custom component of the same name, props flat (the client's catalog
+     * must have it).
+     */
+    unmapped?: 'text' | 'custom';
+    /** The agent's catalog: what unmapped components' text comes from. */
+    catalog?: Catalog;
+    /** `createSurface.theme` (basic catalog: `primaryColor`, `agentDisplayName`, `iconUrl`). */
+    theme?: Record<string, unknown>;
+}
+/** The library builtins, mapped onto A2UI's basic catalog. */
+export declare const A2UI_BUILTIN_MAPPERS: Readonly<Record<string, A2uiMapper>>;
+/**
+ * A `ui` frame as A2UI components, flat, the root's id `root`. A composed tree (`genui:tree`) maps
+ * node by node — node ids are their positions (`root`, `root.0`, `root.0.2`), stable from the first
+ * preview to the final frame, so a streamed surface only ever grows. A node still held back
+ * (`held`) is left out: its parent references an id that arrives later, which A2UI draws as a
+ * placeholder.
+ */
+export declare function toA2uiComponents(frame: {
+    component: string;
+    props: unknown;
+}, options?: A2uiOptions): A2uiComponent[];
+/** The messages that draw (or redraw) a surface: `createSurface` the first time, then its components. */
+export declare function a2uiSurfaceMessages(surfaceId: string, components: A2uiComponent[], options: A2uiOptions & {
+    create: boolean;
+    sendDataModel?: boolean;
+}): A2uiServerMessage[];
+/** A surface id A2UI clients accept, from a `ui` frame id (`<toolCallId>:ui:0`). */
+export declare function a2uiSurfaceId(frameId: string): string;
+/**
+ * A2UI's AG-UI binding (the AG-UI A2UI middleware, CopilotKit's renderer): one `ACTIVITY_SNAPSHOT`
+ * of type `a2ui-surface` per `ui` frame, carrying the whole surface (`createSurface` +
+ * `updateComponents`) with `replace: true` — so each preview of a streaming tree repaints the same
+ * activity in place, keyed by the frame id.
+ */
+export declare function a2uiActivityEvent(frame: {
+    id: string;
+    component: string;
+    props: unknown;
+    partial?: boolean;
+}, options?: A2uiOptions): AgUiEvent | null;
+/**
+ * An A2UI catalog definition (v0.9 inline catalog shape) for an agent catalog's components sent
+ * as custom components: `{ catalogId, components: { Name: JSON Schema } }` — what a client
+ * registers, or hands an A2UI-aware runtime (`a2uiClientCapabilities.inlineCatalogs`).
+ */
+export declare function a2uiCatalog(catalog: Catalog, options: {
+    catalogId: string;
+    only?: readonly string[];
+}): {
+    catalogId: string;
+    components: Record<string, Record<string, unknown>>;
+};
+/**
+ * A client-to-server A2UI message, or an AG-UI `forwardedProps.a2uiAction`, as a {@link UiAction}:
+ * v0.9 `{ version, action: { name, surfaceId, sourceComponentId, timestamp, context } }`, v0.8
+ * `{ userAction: { … } }`, or the bare action object. A string when it is not one.
+ */
+export declare function readA2uiAction(raw: unknown, options?: {
+    maxBytes?: number;
+}): UiAction | string;
+/** The surface an approval interrupt is shown on: its message, and Approve / Reject buttons. */
+export declare function a2uiApprovalComponents(interrupt: AgUiInterrupt): A2uiComponent[];
+export interface A2uiStreamOptions extends A2uiOptions {
+    /**
+     * Assistant text: `'surface'` (default) streams it into a surface of its own — one `Text` bound
+     * to `/text` in the data model, updated as tokens arrive; `'omit'` leaves text out (UI only).
+     */
+    text?: 'surface' | 'omit';
+}
+/**
+ * One AG-UI run as an A2UI message stream — the projection the A2UI transport serves. Stateful
+ * (which surfaces exist), pure otherwise: feed it the run's AG-UI events in order.
+ *
+ *  - `CUSTOM agora.ui` → a surface per `ui` frame id, created once and updated in place (previews
+ *    included); a withdrawn preview deletes it;
+ *  - text messages → a text surface each (see {@link A2uiStreamOptions.text});
+ *  - an approval interrupt → a surface with Approve / Reject buttons ({@link A2UI_APPROVE_ACTION});
+ *    any other interrupt → a text surface saying to answer it in the app;
+ *  - `RUN_ERROR` → a text surface with the message.
+ */
+export declare class A2uiProjector {
+    private readonly options;
+    private readonly surfaces;
+    private readonly texts;
+    constructor(options?: A2uiStreamOptions);
+    project(event: AgUiEvent): A2uiServerMessage[];
+    private surface;
+    private ui;
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/src/a2ui/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/a2ui/core.ts"],"names":[],"mappings":"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"}