@portel/photon 1.22.1 → 1.23.1

package/README.md

@@ -72,17 +72,22 @@ One definition. Multiple surfaces.
 
 ### Quick Start
 
+From zero to an MCP server connected to Claude Desktop in three commands:
+
 ```bash
 npm install -g @portel/photon
-photon maker new my-tool      # Scaffold a new photon
-photon                        # Open Beam, the web UI
+photon new my-tool                  # Scaffolds ./my-tool.photon.ts in your CWD
+photon mcp install my-tool          # Registers it in Claude Desktop's config
+# Restart Claude Desktop. Your tool is live.
 ```
 
-Or try without installing:
+Prefer the web dashboard? Skip step 3 and run `photon` instead — it opens Beam, the auto-generated UI.
+
+Or try without installing globally:
 
 ```bash
-npx @portel/photon maker new my-tool
-npx @portel/photon
+npx @portel/photon new my-tool
+npx @portel/photon mcp install my-tool
 ```
 
 > Requires [Node.js 20+](https://nodejs.org). TypeScript is compiled internally; no `tsconfig.json` needed.
@@ -267,7 +272,10 @@ Things you don't build because Photon handles them:
 | **Persistent memory** | `this.memory` gives your photon per-instance key-value storage, no database needed |
 | **Scheduled execution** | `@scheduled` runs any method on a cron schedule |
 | **Webhooks** | `@webhook` exposes any method as an HTTP endpoint |
-| **OAuth** | Built-in OAuth 2.0 flows for Google, GitHub, Microsoft |
+| **OAuth (client)** | Built-in OAuth 2.0 flows for Google, GitHub, Microsoft |
+| **OAuth Authorization Server** | Issue tokens to MCP clients yourself: CIMD + DCR, PKCE, OIDC id_token, RFC 8693 token exchange |
+| **SQLite persistence** | Audit log, execution history, and OAuth grants survive daemon restart (bun:sqlite or better-sqlite3) |
+| **Daemon ops** | `photon ps` lists and controls scheduled jobs, webhooks, and live sessions |
 | **Distributed locks** | `@locked` serializes access: one caller at a time, across processes |
 | **Cross-photon calls** | `this.call()` invokes another photon's methods |
 | **Real-time events** | `this.emit()` fires named events to the browser UI with zero wiring |
@@ -375,6 +383,7 @@ photon upgrade                    # Upgrade all
 # Ops
 photon doctor                     # Diagnose environment
 photon test                       # Run tests
+photon ps                         # Observe & control scheduled jobs, webhooks, sessions
 ```
 
 ### Install from GitHub
@@ -442,6 +451,9 @@ Uses Bun's compiler under the hood. The binary bundles the photon, its `@depende
 |---|---|
 | [Custom UI](./docs/guides/CUSTOM-UI.md) | Build rich interactive interfaces with the photon bridge API |
 | [OAuth](./docs/guides/AUTH.md) | Built-in OAuth 2.0 with Google, GitHub, Microsoft |
+| [MCP Client Registration](./docs/guides/mcp-client-registration.md) | Register MCP clients with Photon's AS via CIMD or DCR |
+| [Observability](./docs/guides/observability.md) | OpenTelemetry traces, metrics, logs, and structured errors |
+| [Protocol Features](./docs/guides/PROTOCOL-FEATURES.md) | Capability handshake, structured errors, trace correlation |
 | [Daemon Pub/Sub](./docs/internals/DAEMON-PUBSUB.md) | Real-time cross-process messaging |
 | [Webhooks](./docs/reference/WEBHOOKS.md) | HTTP endpoints for external services |
 | [Locks](./docs/reference/LOCKS.md) | Distributed locks for exclusive access |
@@ -455,9 +467,8 @@ Uses Bun's compiler under the hood. The binary bundles the photon, its `@depende
 | [Security](./SECURITY.md) | Best practices and audit checklist |
 | [Marketplace Publishing](./docs/guides/MARKETPLACE-PUBLISHING.md) | Create and share team marketplaces |
 | [Best Practices](./docs/guides/BEST-PRACTICES.md) | Patterns for production photons |
-| [Comparison](./docs/COMPARISON.md) | Benchmarks vs official MCP implementations |
 
-**Reference:** [Complete Developer Guide](./docs/GUIDE.md) · [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) · [Naming Conventions](./docs/guides/NAMING-CONVENTIONS.md) · [Architecture](./docs/internals/ARCHITECTURE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
+**Reference:** [Complete Developer Guide](./docs/GUIDE.md) · [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) · [Naming Conventions](./docs/guides/NAMING-CONVENTIONS.md) · [Architecture](./docs/internals/ARCHITECTURE.md) · [OAuth Authorization Server](./docs/internals/OAUTH-AUTHORIZATION-SERVER.md) · [Lifecycle & Ingress](./docs/internals/LIFECYCLE-AND-INGRESS.md) · [PHOTON_DIR & Namespace](./docs/internals/PHOTON-DIR-AND-NAMESPACE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
 ---
 

package/dist/a2ui/mapper.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A2UI v0.9 Result Mapper
+ *
+ * Converts a Photon method's return value into a valid A2UI JSONL message
+ * sequence (createSurface → updateComponents → updateDataModel). Mirrors
+ * the auto-mapping heuristics used by @format table/list/card so photon
+ * authors can add `@format a2ui` without writing any UI code.
+ *
+ * Escape hatch: returning `{ __a2ui: true, components, data }` bypasses
+ * heuristics and emits the components verbatim.
+ *
+ * @see https://a2ui.org/specification/v0.9-a2ui/
+ */
+import { type A2UIMessage } from './types.js';
+export interface MapperOptions {
+    surfaceId?: string;
+    theme?: {
+        primaryColor?: string;
+        iconUrl?: string;
+        agentDisplayName?: string;
+    };
+}
+/**
+ * Does the given array look like a pre-serialized A2UI JSONL stream that
+ * should be forwarded verbatim instead of re-mapped? Every element must be
+ * a well-formed A2UI message (has `version` AND one of the message wrapper
+ * keys). Empty arrays are not streams — they're empty lists, and should go
+ * through the mapper so the lifecycle messages are emitted.
+ *
+ * Extracted into the mapper module so CLI, AG-UI adapter, and future
+ * transports share one classifier instead of drifting apart.
+ */
+export declare function looksLikeA2UIStream(arr: unknown[]): boolean;
+/**
+ * Translate a method result into the A2UI JSONL sequence.
+ * Always returns at least three messages: createSurface, updateComponents,
+ * updateDataModel. The component list always contains exactly one `root`.
+ */
+export declare function resultToA2UIMessages(result: unknown, options?: MapperOptions): A2UIMessage[];
+//# sourceMappingURL=mapper.d.ts.map

package/dist/a2ui/mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../../src/a2ui/mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAIL,KAAK,WAAW,EAGjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QACN,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAKD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,OAAO,CAoB3D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,WAAW,EAAE,CA+BhG"}

package/dist/a2ui/mapper.js

@@ -0,0 +1,286 @@
+/**
+ * A2UI v0.9 Result Mapper
+ *
+ * Converts a Photon method's return value into a valid A2UI JSONL message
+ * sequence (createSurface → updateComponents → updateDataModel). Mirrors
+ * the auto-mapping heuristics used by @format table/list/card so photon
+ * authors can add `@format a2ui` without writing any UI code.
+ *
+ * Escape hatch: returning `{ __a2ui: true, components, data }` bypasses
+ * heuristics and emits the components verbatim.
+ *
+ * @see https://a2ui.org/specification/v0.9-a2ui/
+ */
+import { randomUUID } from 'crypto';
+import { A2UI_VERSION, A2UI_BASIC_CATALOG, isA2UIEscapeHatch, } from './types.js';
+/** Wrapper keys that identify each A2UI message variant (see ./types.ts). */
+const A2UI_MESSAGE_KEYS = ['createSurface', 'updateComponents', 'updateDataModel', 'deleteSurface'];
+/**
+ * Does the given array look like a pre-serialized A2UI JSONL stream that
+ * should be forwarded verbatim instead of re-mapped? Every element must be
+ * a well-formed A2UI message (has `version` AND one of the message wrapper
+ * keys). Empty arrays are not streams — they're empty lists, and should go
+ * through the mapper so the lifecycle messages are emitted.
+ *
+ * Extracted into the mapper module so CLI, AG-UI adapter, and future
+ * transports share one classifier instead of drifting apart.
+ */
+export function looksLikeA2UIStream(arr) {
+    if (arr.length === 0)
+        return false;
+    return arr.every((m) => {
+        if (typeof m !== 'object' || m === null)
+            return false;
+        const rec = m;
+        if (typeof rec.version !== 'string')
+            return false;
+        // Must carry EXACTLY ONE wrapper key whose value is itself an object
+        // with the surfaceId that A2UI messages always include. This rejects
+        // row data that happens to carry both a `version` string and a key
+        // named `updateDataModel` / similar as arbitrary column values.
+        let wrapperCount = 0;
+        for (const k of A2UI_MESSAGE_KEYS) {
+            if (!(k in rec))
+                continue;
+            wrapperCount++;
+            const wrapped = rec[k];
+            if (!wrapped || typeof wrapped !== 'object' || Array.isArray(wrapped))
+                return false;
+            if (typeof wrapped.surfaceId !== 'string')
+                return false;
+        }
+        return wrapperCount === 1;
+    });
+}
+/**
+ * Translate a method result into the A2UI JSONL sequence.
+ * Always returns at least three messages: createSurface, updateComponents,
+ * updateDataModel. The component list always contains exactly one `root`.
+ */
+export function resultToA2UIMessages(result, options = {}) {
+    const tree = buildTree(result);
+    // Escape-hatch overrides win over caller options when both are present —
+    // the escape hatch is the photon author's explicit intent, options are
+    // the transport's defaults.
+    const surfaceId = tree.surfaceId ?? options.surfaceId ?? `s-${randomUUID()}`;
+    const theme = tree.theme ?? options.theme;
+    const { components, data } = tree;
+    assertSingleRoot(components);
+    const messages = [
+        {
+            version: A2UI_VERSION,
+            createSurface: {
+                surfaceId,
+                catalogId: A2UI_BASIC_CATALOG,
+                ...(theme ? { theme } : {}),
+            },
+        },
+        {
+            version: A2UI_VERSION,
+            updateComponents: { surfaceId, components },
+        },
+        {
+            version: A2UI_VERSION,
+            updateDataModel: { surfaceId, path: '/', value: data },
+        },
+    ];
+    return messages;
+}
+function buildTree(result) {
+    if (isA2UIEscapeHatch(result)) {
+        return buildFromEscapeHatch(result);
+    }
+    if (result === null || result === undefined) {
+        return buildPrimitive('');
+    }
+    if (typeof result === 'string' || typeof result === 'number' || typeof result === 'boolean') {
+        return buildPrimitive(String(result));
+    }
+    if (Array.isArray(result)) {
+        return buildList(result);
+    }
+    if (isCardShaped(result)) {
+        return buildCard(result);
+    }
+    if (typeof result === 'object') {
+        return buildKeyValueColumn(result);
+    }
+    // Functions, symbols, bigints — render their type rather than risk [object Object].
+    return buildPrimitive(`<${typeof result}>`);
+}
+function buildFromEscapeHatch(hatch) {
+    if (!hatch.components.some((c) => c.id === 'root')) {
+        throw new Error("A2UI escape hatch must include a component with id 'root'");
+    }
+    return {
+        components: hatch.components,
+        data: hatch.data ?? {},
+        surfaceId: hatch.surfaceId,
+        theme: hatch.theme,
+    };
+}
+function buildPrimitive(value) {
+    return {
+        components: [{ id: 'root', component: 'Text', text: value }],
+        data: { value },
+    };
+}
+function buildList(rows) {
+    if (rows.length === 0) {
+        return buildPrimitive('(empty list)');
+    }
+    const firstRow = rows[0];
+    if (firstRow === null || typeof firstRow !== 'object' || Array.isArray(firstRow)) {
+        return buildPrimitiveList(rows);
+    }
+    const keys = Object.keys(firstRow);
+    const titleKey = pickTitleKey(keys);
+    const components = [
+        {
+            id: 'root',
+            component: 'List',
+            list: {
+                template: { id: 'rowCard' },
+                data: { path: '/items' },
+            },
+        },
+        {
+            id: 'rowCard',
+            component: 'Card',
+            child: 'rowText',
+        },
+        {
+            id: 'rowText',
+            component: 'Text',
+            text: { path: titleKey },
+        },
+    ];
+    return { components, data: { items: rows } };
+}
+function buildPrimitiveList(values) {
+    const items = values.map((v, i) => ({ label: String(v), index: i }));
+    const components = [
+        {
+            id: 'root',
+            component: 'List',
+            list: {
+                template: { id: 'rowCard' },
+                data: { path: '/items' },
+            },
+        },
+        { id: 'rowCard', component: 'Card', child: 'rowText' },
+        { id: 'rowText', component: 'Text', text: { path: 'label' } },
+    ];
+    return { components, data: { items } };
+}
+/**
+ * Does this object look like a Card result? Card layout renders only
+ * `title` + optional `description` + optional `actions`; anything else
+ * would silently be dropped. Require that there are no extra "data"
+ * fields — a result like `{ title: 'prod-01', region: 'us-east', cpu: '42%' }`
+ * should go through buildKeyValueColumn instead so every field renders.
+ */
+const CARD_KEYS = new Set(['title', 'description', 'actions']);
+function isCardShaped(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const obj = value;
+    if (typeof obj.title !== 'string')
+        return false;
+    if (obj.actions !== undefined && !Array.isArray(obj.actions))
+        return false;
+    // Reject objects that carry fields beyond the card schema — those are
+    // data-bearing records, not cards.
+    for (const key of Object.keys(obj)) {
+        if (!CARD_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+function buildCard(card) {
+    const contentIds = ['cardTitle'];
+    const components = [
+        { id: 'root', component: 'Card', child: 'cardBody' },
+        {
+            id: 'cardTitle',
+            component: 'Text',
+            text: { path: '/title' },
+            variant: 'h2',
+        },
+    ];
+    if (card.description) {
+        components.push({
+            id: 'cardDesc',
+            component: 'Text',
+            text: { path: '/description' },
+        });
+        contentIds.push('cardDesc');
+    }
+    const actions = card.actions ?? [];
+    actions.forEach((action, i) => {
+        const btnId = `cardBtn${i}`;
+        components.push({
+            id: btnId,
+            component: 'Button',
+            text: action.label,
+            variant: i === 0 ? 'primary' : 'borderless',
+            action: {
+                event: { name: action.name ?? action.label },
+            },
+        });
+        contentIds.push(btnId);
+    });
+    components.push({
+        id: 'cardBody',
+        component: 'Column',
+        children: contentIds,
+    });
+    return { components, data: card };
+}
+function buildKeyValueColumn(obj) {
+    const keys = Object.keys(obj);
+    if (keys.length === 0) {
+        return buildPrimitive('(empty object)');
+    }
+    const childIds = [];
+    const components = [];
+    keys.forEach((key, i) => {
+        const rowId = `row${i}`;
+        // RFC 6901: encode ~ as ~0 and / as ~1 when a key is embedded in a JSON
+        // Pointer. Order matters — ~0 first would double-encode / produced by ~1.
+        const pointerKey = key.replace(/~/g, '~0').replace(/\//g, '~1');
+        components.push({
+            id: rowId,
+            component: 'Text',
+            text: {
+                call: 'formatString',
+                args: { value: `**${key}:** \${/${pointerKey}}` },
+            },
+        });
+        childIds.push(rowId);
+    });
+    components.unshift({
+        id: 'root',
+        component: 'Column',
+        children: childIds,
+    });
+    return { components, data: obj };
+}
+// ════════════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ════════════════════════════════════════════════════════════════════════════════
+function pickTitleKey(keys) {
+    const preferred = ['title', 'name', 'label', 'subject'];
+    for (const p of preferred) {
+        if (keys.includes(p))
+            return p;
+    }
+    return keys[0] ?? 'value';
+}
+function assertSingleRoot(components) {
+    const rootCount = components.filter((c) => c.id === 'root').length;
+    if (rootCount !== 1) {
+        throw new Error(`A2UI component tree must have exactly one 'root' component, got ${rootCount}`);
+    }
+}
+//# sourceMappingURL=mapper.js.map

package/dist/a2ui/mapper.js.map

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

package/dist/a2ui/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * A2UI v0.9 Protocol Types
+ *
+ * Zero-dependency definitions for the A2UI v0.9 Draft wire format — a
+ * declarative generative-UI protocol that rides on AG-UI transport.
+ *
+ * @see https://a2ui.org/specification/v0.9-a2ui/
+ *
+ * Scope: producer-side only. These types describe the JSON messages the
+ * Photon runtime emits, not the full renderer contract.
+ */
+export declare const A2UI_VERSION = "v0.9";
+export declare const A2UI_BASIC_CATALOG = "https://a2ui.org/specification/v0_9/basic_catalog.json";
+export interface A2UIPath {
+    path: string;
+}
+export interface A2UIFunctionCall {
+    call: string;
+    args?: Record<string, unknown>;
+}
+export type DynamicString = string | A2UIPath | A2UIFunctionCall;
+export type DynamicNumber = number | A2UIPath | A2UIFunctionCall;
+export type DynamicBoolean = boolean | A2UIPath | A2UIFunctionCall;
+export interface A2UIComponentBase {
+    id: string;
+    component: string;
+}
+export interface A2UIText extends A2UIComponentBase {
+    component: 'Text';
+    text: DynamicString;
+    variant?: 'h1' | 'h2' | 'h3' | 'body' | 'caption';
+}
+export interface A2UIImage extends A2UIComponentBase {
+    component: 'Image';
+    url: DynamicString;
+    alt?: DynamicString;
+}
+export interface A2UIDivider extends A2UIComponentBase {
+    component: 'Divider';
+}
+export interface A2UIRow extends A2UIComponentBase {
+    component: 'Row';
+    children: string[];
+}
+export interface A2UIColumn extends A2UIComponentBase {
+    component: 'Column';
+    children: string[];
+}
+export interface A2UICard extends A2UIComponentBase {
+    component: 'Card';
+    child: string;
+}
+export interface A2UIListTemplate {
+    template: {
+        id: string;
+    };
+    data: A2UIPath;
+}
+export interface A2UIList extends A2UIComponentBase {
+    component: 'List';
+    list: A2UIListTemplate;
+}
+export interface A2UIButton extends A2UIComponentBase {
+    component: 'Button';
+    text: DynamicString;
+    variant?: 'primary' | 'borderless';
+    action?: {
+        event?: {
+            name: string;
+            context?: Record<string, unknown>;
+        };
+        functionCall?: A2UIFunctionCall;
+    };
+}
+export interface A2UITextField extends A2UIComponentBase {
+    component: 'TextField';
+    label?: DynamicString;
+    value?: A2UIPath;
+    checks?: Array<{
+        call: string;
+        args?: Record<string, unknown>;
+        message?: string;
+    }>;
+}
+export type A2UIComponent = A2UIText | A2UIImage | A2UIDivider | A2UIRow | A2UIColumn | A2UICard | A2UIList | A2UIButton | A2UITextField;
+export interface CreateSurfaceMessage {
+    version: typeof A2UI_VERSION;
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+        theme?: {
+            primaryColor?: string;
+            iconUrl?: string;
+            agentDisplayName?: string;
+        };
+        sendDataModel?: boolean;
+    };
+}
+export interface UpdateComponentsMessage {
+    version: typeof A2UI_VERSION;
+    updateComponents: {
+        surfaceId: string;
+        components: A2UIComponent[];
+    };
+}
+export interface UpdateDataModelMessage {
+    version: typeof A2UI_VERSION;
+    updateDataModel: {
+        surfaceId: string;
+        path: string;
+        value: unknown;
+    };
+}
+export interface DeleteSurfaceMessage {
+    version: typeof A2UI_VERSION;
+    deleteSurface: {
+        surfaceId: string;
+    };
+}
+export type A2UIMessage = CreateSurfaceMessage | UpdateComponentsMessage | UpdateDataModelMessage | DeleteSurfaceMessage;
+export interface A2UIEscapeHatch {
+    __a2ui: true;
+    components: A2UIComponent[];
+    data?: unknown;
+    surfaceId?: string;
+    theme?: CreateSurfaceMessage['createSurface']['theme'];
+}
+export declare function isA2UIEscapeHatch(value: unknown): value is A2UIEscapeHatch;
+//# sourceMappingURL=types.d.ts.map

package/dist/a2ui/types.d.ts.map

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

package/dist/a2ui/types.js

@@ -0,0 +1,20 @@
+/**
+ * A2UI v0.9 Protocol Types
+ *
+ * Zero-dependency definitions for the A2UI v0.9 Draft wire format — a
+ * declarative generative-UI protocol that rides on AG-UI transport.
+ *
+ * @see https://a2ui.org/specification/v0.9-a2ui/
+ *
+ * Scope: producer-side only. These types describe the JSON messages the
+ * Photon runtime emits, not the full renderer contract.
+ */
+export const A2UI_VERSION = 'v0.9';
+export const A2UI_BASIC_CATALOG = 'https://a2ui.org/specification/v0_9/basic_catalog.json';
+export function isA2UIEscapeHatch(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__a2ui === true &&
+        Array.isArray(value.components));
+}
+//# sourceMappingURL=types.js.map

package/dist/a2ui/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/a2ui/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AACnC,MAAM,CAAC,MAAM,kBAAkB,GAAG,wDAAwD,CAAC;AA2J3F,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA8B,CAAC,MAAM,KAAK,IAAI;QAC/C,KAAK,CAAC,OAAO,CAAE,KAAkC,CAAC,UAAU,CAAC,CAC9D,CAAC;AACJ,CAAC"}

package/dist/ag-ui/adapter.d.ts

@@ -35,7 +35,15 @@ export declare function proxyExternalAgent(agentUrl: string, input: RunAgentInpu
  * Returns { outputHandler, finish, error } — call finish() after successful
  * execution or error() on failure to emit the terminal event.
  */
-export declare function createAGUIOutputHandler(photonName: string, toolName: string, runId: string, broadcast: BroadcastFn): {
+export interface AGUIOutputHandlerOptions {
+    /**
+     * When the underlying method declares `@format a2ui`, set this to 'a2ui'.
+     * The handler will map the final result into A2UI v0.9 messages and emit
+     * each as a CUSTOM event named 'a2ui.message' before the STATE_SNAPSHOT.
+     */
+    outputFormat?: string;
+}
+export declare function createAGUIOutputHandler(photonName: string, toolName: string, runId: string, broadcast: BroadcastFn, options?: AGUIOutputHandlerOptions): {
     outputHandler: (yieldValue: any) => void;
     finish: (result?: unknown) => void;
     error: (message: string, classification?: {

package/dist/ag-ui/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/ag-ui/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAiC,KAAK,aAAa,EAAkB,MAAM,YAAY,CAAC;AAO/F,KAAK,WAAW,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;AA4DlD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,IAAI,CAAC,CAwFf;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,WAAW,GACrB;IACD,aAAa,EAAE,CAAC,UAAU,EAAE,GAAG,KAAK,IAAI,CAAC;IACzC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC3F,CAmOA"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/ag-ui/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAiC,KAAK,aAAa,EAAkB,MAAM,YAAY,CAAC;AAQ/F,KAAK,WAAW,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;AA4DlD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,IAAI,CAAC,CAwFf;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,WAAW,EACtB,OAAO,GAAE,wBAA6B,GACrC;IACD,aAAa,EAAE,CAAC,UAAU,EAAE,GAAG,KAAK,IAAI,CAAC;IACzC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC3F,CAuQA"}