@flowget/ai-chat 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,250 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ChatModelAdapter } from '@assistant-ui/react';
+
+/**
+ * Graph types — deliberately builder-agnostic. `@flowget/ai-chat` never
+ * imports `@flowget/builder`; the host maps its own graph to/from these plain
+ * structural shapes through the `currentGraph` / `applyGraph` seam on
+ * {@link WorkflowChat}. That seam is the whole point of the package: the chat
+ * proposes a graph, the host owns how it lands on the canvas.
+ */
+/** A node in a laid-out canvas graph — `position` required. */
+type WorkflowNode = {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    position: {
+        x: number;
+        y: number;
+    };
+};
+/** An edge in a canvas graph. `null` handles belong to the wire, not here. */
+type WorkflowEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    type?: string;
+};
+/**
+ * A laid-out graph, ready to apply to a canvas. Arrays are `readonly` so a
+ * host's own (often readonly) graph assigns to `currentGraph` without a cast.
+ */
+type WorkflowGraph = {
+    nodes: readonly WorkflowNode[];
+    edges: readonly WorkflowEdge[];
+};
+/** A node in a *proposed* graph — `position` optional (the AI omits layout). */
+type ProposedNode = {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+    };
+};
+/** An edge in a proposed graph — tolerant of the wire's `null` handles. */
+type ProposedEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+    /** Edge kind (e.g. the host's custom edge type); carried through to the canvas. */
+    type?: string | null;
+};
+/** The position-optional graph the server proposes. */
+type ProposedGraph = {
+    nodes: readonly ProposedNode[];
+    edges: readonly ProposedEdge[];
+};
+/**
+ * Turn a position-optional proposal into a laid-out graph, given the current
+ * canvas as the baseline. The default is the package's zero-dependency
+ * `layoutProposal`; a builder-host can inject its own (e.g. a dagre merge) via
+ * the `layout` prop on {@link WorkflowChat} to keep ai-chat builder-agnostic.
+ */
+type WorkflowLayout = (proposed: ProposedGraph, current: WorkflowGraph) => WorkflowGraph;
+/**
+ * The host-provided seam that lets the chat read + write the canvas without
+ * knowing anything about the host's builder. Supplied to {@link WorkflowChat}.
+ */
+type WorkflowChatBridge = {
+    /** Read the graph currently on the canvas (edit context + layout baseline). */
+    getCurrentGraph: () => WorkflowGraph;
+    /** Commit a laid-out graph to the canvas (e.g. the builder store's setGraph). */
+    applyGraph: (graph: WorkflowGraph) => void;
+    /** Lay a proposal out before applying. Defaults to the built-in layout. */
+    layout?: WorkflowLayout;
+};
+
+/**
+ * The wire contract between the client and the authoring backend — a small
+ * mirror of `@flowget/ai`'s request/stream shapes, kept local so the client
+ * layer never imports the (server-only) engine.
+ *
+ * A dev-only type-level parity guard (`contract.parity.ts`, not shipped) keeps
+ * this hand-mirror from silently drifting from `@flowget/ai`'s contract.
+ */
+
+/**
+ * The caller identity, mirrored from `@flowget/ai`'s `Actor`.
+ *
+ * **Untrusted by default.** When set on the client `ChatRequest`, it is plain
+ * JSON on the request body — the browser can put anything here. Treat it as a
+ * *hint*: a server that gates data access on the actor MUST derive/verify it
+ * server-side (from its own session/JWT) via `createChatStreamResponse`'s
+ * `buildRequest` option and/or a `@flowget/ai` authorizer. See the README
+ * "Security" section.
+ */
+type ChatActor = {
+    id: string;
+    tenantId?: string;
+    roles: readonly string[];
+    scopes?: readonly string[];
+    claims?: Record<string, unknown>;
+};
+/** Body of `POST <endpoint>`. */
+type ChatRequest = {
+    command: string;
+    /** The graph currently on the canvas — present for a targeted edit. */
+    currentGraph?: WorkflowGraph;
+    /** Caller identity hint (untrusted on the wire — see {@link ChatActor}). */
+    actor?: ChatActor;
+    /** Opaque, client-carried continuity payload forwarded to the model. */
+    context?: unknown;
+};
+/**
+ * A streamed chat event (mirrors the engine's `AuthorStreamEvent`). Assistant
+ * text arrives as `text-delta`s; the stream ends with a terminal `proposal` |
+ * `message`, or `error`. Discriminate on `kind` — the same key `@flowget/ai`
+ * uses, so `/server` forwards the engine's events verbatim.
+ */
+type ChatStreamEvent = {
+    kind: "text-delta";
+    delta: string;
+} | {
+    kind: "proposal";
+    graph: ProposedGraph;
+    summary: string;
+} | {
+    kind: "message";
+    text: string;
+} | {
+    kind: "error";
+    error: string;
+};
+
+/**
+ * The transport seam — how the browser reaches the authoring backend.
+ *
+ * The **customer-swappable** boundary: the default streams from the host's BFF
+ * over SSE, but a host with a different backend swaps this one async generator
+ * without touching the runtime, tool UI, or bridge.
+ */
+
+/** Streams authoring events (deltas → terminal) for a command + graph. */
+type ChatStreamTransport = (request: ChatRequest, signal?: AbortSignal) => AsyncIterable<ChatStreamEvent>;
+/** Default transport: POST command + graph to the BFF, read the SSE stream. */
+declare function httpChatStreamTransport(endpoint?: string): ChatStreamTransport;
+
+type WorkflowChatProps = {
+    /** The graph currently on the canvas (edit context + layout baseline). */
+    currentGraph: WorkflowGraph;
+    /** Commit a laid-out graph to the canvas (e.g. the builder store's setGraph). */
+    applyGraph: (graph: WorkflowGraph) => void;
+    /** Fully custom backend transport. Overrides `endpoint`. */
+    transport?: ChatStreamTransport;
+    /** Endpoint for the default SSE transport. Default `/api/chat`. */
+    endpoint?: string;
+    /** Panel heading. Default `"Workflow AI"`. */
+    heading?: string;
+    /** Panel subtitle. Default `"Draft & edit with a prompt"`. */
+    subtitle?: string;
+    /** Empty-state suggestion chips. Pass `[]` to hide them. */
+    examples?: readonly string[];
+    /**
+     * Lay a proposal out before it's applied. Defaults to the built-in
+     * `layoutProposal` (BFS layered layout preserving surviving-node positions);
+     * a builder-host can inject its own (e.g. a dagre merge) to get proper
+     * layout — ai-chat stays builder-agnostic (the host supplies the function).
+     */
+    layout?: WorkflowLayout;
+    /**
+     * Caller identity hint attached to each request. **Untrusted on the wire** —
+     * a server that gates on it must derive/verify server-side (see the README
+     * "Security" section and `createChatStreamResponse`'s `buildRequest`).
+     */
+    actor?: ChatActor;
+    /** Opaque continuity payload forwarded to the model with each request. */
+    context?: unknown;
+};
+declare function WorkflowChat({ currentGraph, applyGraph, transport, endpoint, heading, subtitle, examples, layout, actor, context, }: WorkflowChatProps): react.JSX.Element;
+
+/**
+ * The assistant-ui `ChatModelAdapter` for workflow authoring.
+ *
+ * The backend streams the assistant's text as it's generated and ends in a
+ * single terminal event, mapping onto `LocalRuntime`'s streaming shape
+ * (`async *run`, yielding cumulative content):
+ *
+ *  - `text-delta` → append to the running text and yield it (the "typing" feel).
+ *  - `message`    → terminal plain assistant text turn.
+ *  - `proposal`   → terminal `propose_workflow` tool call carrying an approval
+ *    gate (`approval:{ id }`) + `requires-action`. The gate PAUSES the run; the
+ *    proposal card renders Apply / Dismiss. On decision the runtime re-invokes
+ *    this adapter — we detect the resolved gate on the in-progress message and
+ *    close the turn WITHOUT re-authoring.
+ */
+
+/** Optional per-request metadata carried alongside the command + graph. */
+type ChatRequestMeta = {
+    /** Caller identity hint — untrusted on the wire (see {@link ChatActor}). */
+    actor?: ChatActor;
+    /** Opaque, client-carried continuity payload forwarded to the model. */
+    context?: unknown;
+};
+type WorkflowChatAdapterOptions = {
+    /** How to reach the authoring backend (streamed). */
+    transport: ChatStreamTransport;
+    /** Reads the graph currently on the canvas (the edit context). */
+    getCurrentGraph: () => WorkflowGraph;
+    /** Reads optional `actor` / `context` to attach to each request. Stable. */
+    getRequestMeta?: () => ChatRequestMeta;
+};
+declare function createWorkflowChatAdapter({ transport, getCurrentGraph, getRequestMeta, }: WorkflowChatAdapterOptions): ChatModelAdapter;
+
+type ChatRuntimeProviderProps = {
+    children: ReactNode;
+    /** Reads the graph currently on the canvas. Must be referentially stable. */
+    getCurrentGraph: () => WorkflowGraph;
+    /** Swap the backend seam; defaults to `httpChatStreamTransport(endpoint)`. */
+    transport?: ChatStreamTransport;
+    /** Reads optional `actor` / `context` for each request. Must be stable. */
+    getRequestMeta?: () => ChatRequestMeta;
+};
+declare function ChatRuntimeProvider({ children, getCurrentGraph, transport, getRequestMeta, }: ChatRuntimeProviderProps): react.JSX.Element;
+
+/**
+ * Turn a position-optional *proposed* graph into a laid-out {@link WorkflowGraph}.
+ *
+ * The AI emits topology + config but no coordinates, so we lay the graph out:
+ *  1. **Layout stability on edit** — a node that already exists on the canvas
+ *     (matched by id) keeps its exact current position; only new nodes move.
+ *  2. **New nodes** get a simple left-to-right layered layout (BFS depth →
+ *     column, order-within-depth → row).
+ *
+ * Pure + framework-free so the host can also call it directly if it drives its
+ * own apply path.
+ */
+
+/**
+ * Merge a proposed graph onto the current canvas graph, preserving the layout
+ * of surviving nodes. Returns a laid-out {@link WorkflowGraph}.
+ */
+declare function layoutProposal(proposed: ProposedGraph, current?: WorkflowGraph): WorkflowGraph;
+
+export { type ChatActor, type ChatRequest, type ChatRequestMeta, ChatRuntimeProvider, type ChatRuntimeProviderProps, type ChatStreamEvent, type ChatStreamTransport, type ProposedEdge, type ProposedGraph, type ProposedNode, WorkflowChat, type WorkflowChatAdapterOptions, type WorkflowChatBridge, type WorkflowChatProps, type WorkflowEdge, type WorkflowGraph, type WorkflowLayout, type WorkflowNode, createWorkflowChatAdapter, httpChatStreamTransport, layoutProposal };

package/dist/react.d.ts

@@ -0,0 +1,250 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ChatModelAdapter } from '@assistant-ui/react';
+
+/**
+ * Graph types — deliberately builder-agnostic. `@flowget/ai-chat` never
+ * imports `@flowget/builder`; the host maps its own graph to/from these plain
+ * structural shapes through the `currentGraph` / `applyGraph` seam on
+ * {@link WorkflowChat}. That seam is the whole point of the package: the chat
+ * proposes a graph, the host owns how it lands on the canvas.
+ */
+/** A node in a laid-out canvas graph — `position` required. */
+type WorkflowNode = {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    position: {
+        x: number;
+        y: number;
+    };
+};
+/** An edge in a canvas graph. `null` handles belong to the wire, not here. */
+type WorkflowEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    type?: string;
+};
+/**
+ * A laid-out graph, ready to apply to a canvas. Arrays are `readonly` so a
+ * host's own (often readonly) graph assigns to `currentGraph` without a cast.
+ */
+type WorkflowGraph = {
+    nodes: readonly WorkflowNode[];
+    edges: readonly WorkflowEdge[];
+};
+/** A node in a *proposed* graph — `position` optional (the AI omits layout). */
+type ProposedNode = {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+    };
+};
+/** An edge in a proposed graph — tolerant of the wire's `null` handles. */
+type ProposedEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+    /** Edge kind (e.g. the host's custom edge type); carried through to the canvas. */
+    type?: string | null;
+};
+/** The position-optional graph the server proposes. */
+type ProposedGraph = {
+    nodes: readonly ProposedNode[];
+    edges: readonly ProposedEdge[];
+};
+/**
+ * Turn a position-optional proposal into a laid-out graph, given the current
+ * canvas as the baseline. The default is the package's zero-dependency
+ * `layoutProposal`; a builder-host can inject its own (e.g. a dagre merge) via
+ * the `layout` prop on {@link WorkflowChat} to keep ai-chat builder-agnostic.
+ */
+type WorkflowLayout = (proposed: ProposedGraph, current: WorkflowGraph) => WorkflowGraph;
+/**
+ * The host-provided seam that lets the chat read + write the canvas without
+ * knowing anything about the host's builder. Supplied to {@link WorkflowChat}.
+ */
+type WorkflowChatBridge = {
+    /** Read the graph currently on the canvas (edit context + layout baseline). */
+    getCurrentGraph: () => WorkflowGraph;
+    /** Commit a laid-out graph to the canvas (e.g. the builder store's setGraph). */
+    applyGraph: (graph: WorkflowGraph) => void;
+    /** Lay a proposal out before applying. Defaults to the built-in layout. */
+    layout?: WorkflowLayout;
+};
+
+/**
+ * The wire contract between the client and the authoring backend — a small
+ * mirror of `@flowget/ai`'s request/stream shapes, kept local so the client
+ * layer never imports the (server-only) engine.
+ *
+ * A dev-only type-level parity guard (`contract.parity.ts`, not shipped) keeps
+ * this hand-mirror from silently drifting from `@flowget/ai`'s contract.
+ */
+
+/**
+ * The caller identity, mirrored from `@flowget/ai`'s `Actor`.
+ *
+ * **Untrusted by default.** When set on the client `ChatRequest`, it is plain
+ * JSON on the request body — the browser can put anything here. Treat it as a
+ * *hint*: a server that gates data access on the actor MUST derive/verify it
+ * server-side (from its own session/JWT) via `createChatStreamResponse`'s
+ * `buildRequest` option and/or a `@flowget/ai` authorizer. See the README
+ * "Security" section.
+ */
+type ChatActor = {
+    id: string;
+    tenantId?: string;
+    roles: readonly string[];
+    scopes?: readonly string[];
+    claims?: Record<string, unknown>;
+};
+/** Body of `POST <endpoint>`. */
+type ChatRequest = {
+    command: string;
+    /** The graph currently on the canvas — present for a targeted edit. */
+    currentGraph?: WorkflowGraph;
+    /** Caller identity hint (untrusted on the wire — see {@link ChatActor}). */
+    actor?: ChatActor;
+    /** Opaque, client-carried continuity payload forwarded to the model. */
+    context?: unknown;
+};
+/**
+ * A streamed chat event (mirrors the engine's `AuthorStreamEvent`). Assistant
+ * text arrives as `text-delta`s; the stream ends with a terminal `proposal` |
+ * `message`, or `error`. Discriminate on `kind` — the same key `@flowget/ai`
+ * uses, so `/server` forwards the engine's events verbatim.
+ */
+type ChatStreamEvent = {
+    kind: "text-delta";
+    delta: string;
+} | {
+    kind: "proposal";
+    graph: ProposedGraph;
+    summary: string;
+} | {
+    kind: "message";
+    text: string;
+} | {
+    kind: "error";
+    error: string;
+};
+
+/**
+ * The transport seam — how the browser reaches the authoring backend.
+ *
+ * The **customer-swappable** boundary: the default streams from the host's BFF
+ * over SSE, but a host with a different backend swaps this one async generator
+ * without touching the runtime, tool UI, or bridge.
+ */
+
+/** Streams authoring events (deltas → terminal) for a command + graph. */
+type ChatStreamTransport = (request: ChatRequest, signal?: AbortSignal) => AsyncIterable<ChatStreamEvent>;
+/** Default transport: POST command + graph to the BFF, read the SSE stream. */
+declare function httpChatStreamTransport(endpoint?: string): ChatStreamTransport;
+
+type WorkflowChatProps = {
+    /** The graph currently on the canvas (edit context + layout baseline). */
+    currentGraph: WorkflowGraph;
+    /** Commit a laid-out graph to the canvas (e.g. the builder store's setGraph). */
+    applyGraph: (graph: WorkflowGraph) => void;
+    /** Fully custom backend transport. Overrides `endpoint`. */
+    transport?: ChatStreamTransport;
+    /** Endpoint for the default SSE transport. Default `/api/chat`. */
+    endpoint?: string;
+    /** Panel heading. Default `"Workflow AI"`. */
+    heading?: string;
+    /** Panel subtitle. Default `"Draft & edit with a prompt"`. */
+    subtitle?: string;
+    /** Empty-state suggestion chips. Pass `[]` to hide them. */
+    examples?: readonly string[];
+    /**
+     * Lay a proposal out before it's applied. Defaults to the built-in
+     * `layoutProposal` (BFS layered layout preserving surviving-node positions);
+     * a builder-host can inject its own (e.g. a dagre merge) to get proper
+     * layout — ai-chat stays builder-agnostic (the host supplies the function).
+     */
+    layout?: WorkflowLayout;
+    /**
+     * Caller identity hint attached to each request. **Untrusted on the wire** —
+     * a server that gates on it must derive/verify server-side (see the README
+     * "Security" section and `createChatStreamResponse`'s `buildRequest`).
+     */
+    actor?: ChatActor;
+    /** Opaque continuity payload forwarded to the model with each request. */
+    context?: unknown;
+};
+declare function WorkflowChat({ currentGraph, applyGraph, transport, endpoint, heading, subtitle, examples, layout, actor, context, }: WorkflowChatProps): react.JSX.Element;
+
+/**
+ * The assistant-ui `ChatModelAdapter` for workflow authoring.
+ *
+ * The backend streams the assistant's text as it's generated and ends in a
+ * single terminal event, mapping onto `LocalRuntime`'s streaming shape
+ * (`async *run`, yielding cumulative content):
+ *
+ *  - `text-delta` → append to the running text and yield it (the "typing" feel).
+ *  - `message`    → terminal plain assistant text turn.
+ *  - `proposal`   → terminal `propose_workflow` tool call carrying an approval
+ *    gate (`approval:{ id }`) + `requires-action`. The gate PAUSES the run; the
+ *    proposal card renders Apply / Dismiss. On decision the runtime re-invokes
+ *    this adapter — we detect the resolved gate on the in-progress message and
+ *    close the turn WITHOUT re-authoring.
+ */
+
+/** Optional per-request metadata carried alongside the command + graph. */
+type ChatRequestMeta = {
+    /** Caller identity hint — untrusted on the wire (see {@link ChatActor}). */
+    actor?: ChatActor;
+    /** Opaque, client-carried continuity payload forwarded to the model. */
+    context?: unknown;
+};
+type WorkflowChatAdapterOptions = {
+    /** How to reach the authoring backend (streamed). */
+    transport: ChatStreamTransport;
+    /** Reads the graph currently on the canvas (the edit context). */
+    getCurrentGraph: () => WorkflowGraph;
+    /** Reads optional `actor` / `context` to attach to each request. Stable. */
+    getRequestMeta?: () => ChatRequestMeta;
+};
+declare function createWorkflowChatAdapter({ transport, getCurrentGraph, getRequestMeta, }: WorkflowChatAdapterOptions): ChatModelAdapter;
+
+type ChatRuntimeProviderProps = {
+    children: ReactNode;
+    /** Reads the graph currently on the canvas. Must be referentially stable. */
+    getCurrentGraph: () => WorkflowGraph;
+    /** Swap the backend seam; defaults to `httpChatStreamTransport(endpoint)`. */
+    transport?: ChatStreamTransport;
+    /** Reads optional `actor` / `context` for each request. Must be stable. */
+    getRequestMeta?: () => ChatRequestMeta;
+};
+declare function ChatRuntimeProvider({ children, getCurrentGraph, transport, getRequestMeta, }: ChatRuntimeProviderProps): react.JSX.Element;
+
+/**
+ * Turn a position-optional *proposed* graph into a laid-out {@link WorkflowGraph}.
+ *
+ * The AI emits topology + config but no coordinates, so we lay the graph out:
+ *  1. **Layout stability on edit** — a node that already exists on the canvas
+ *     (matched by id) keeps its exact current position; only new nodes move.
+ *  2. **New nodes** get a simple left-to-right layered layout (BFS depth →
+ *     column, order-within-depth → row).
+ *
+ * Pure + framework-free so the host can also call it directly if it drives its
+ * own apply path.
+ */
+
+/**
+ * Merge a proposed graph onto the current canvas graph, preserving the layout
+ * of surviving nodes. Returns a laid-out {@link WorkflowGraph}.
+ */
+declare function layoutProposal(proposed: ProposedGraph, current?: WorkflowGraph): WorkflowGraph;
+
+export { type ChatActor, type ChatRequest, type ChatRequestMeta, ChatRuntimeProvider, type ChatRuntimeProviderProps, type ChatStreamEvent, type ChatStreamTransport, type ProposedEdge, type ProposedGraph, type ProposedNode, WorkflowChat, type WorkflowChatAdapterOptions, type WorkflowChatBridge, type WorkflowChatProps, type WorkflowEdge, type WorkflowGraph, type WorkflowLayout, type WorkflowNode, createWorkflowChatAdapter, httpChatStreamTransport, layoutProposal };