@flowget/ai-chat 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to `@flowget/ai-chat` are documented here. This
+project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
+minor = breaking).
+
+## [0.1.0]
+
+Initial release — a builder-agnostic AI workflow-authoring chat.
+
+### Added
+
+- **`@flowget/ai-chat/react`** — the client.
+  - `<WorkflowChat currentGraph={…} applyGraph={…} />`: a turnkey floating
+    chat panel (assistant-ui `AssistantModalPrimitive`) with a streaming
+    runtime, a thread, and a proposal → **approval** → apply flow. The
+    approval gate pauses the run; the proposal card renders Apply / Dismiss
+    inline; applying lays the graph out (preserving surviving-node positions)
+    and commits it through the host's `applyGraph`. Builder-agnostic: the host
+    owns the canvas via the `currentGraph` / `applyGraph` seam.
+  - Props for light theming and continuity: `heading`, `subtitle`, `examples`,
+    `endpoint`, a fully custom `transport`, and `actor` / `context` request
+    metadata.
+  - A host-pluggable `layout` prop: delegate proposal layout to your builder
+    (e.g. a dagre merge) instead of the built-in `layoutProposal`, keeping
+    ai-chat builder-agnostic (the host supplies the function).
+  - **Headless tier** for hosts that bring their own shell / transport:
+    `ChatRuntimeProvider`, `createWorkflowChatAdapter`,
+    `httpChatStreamTransport`, and the pure `layoutProposal` layout helper.
+- **`@flowget/ai-chat/server`** — the BFF helper (React-free).
+  - `createChatStreamResponse(req, config, options?)`: parses + validates the
+    request, then streams `@flowget/ai`'s `authorStream()` to the browser as
+    SSE. `options.buildRequest` is the seam for injecting a **server-derived**
+    actor (from the host's session/JWT) over the untrusted client value;
+    `options.onError` maps errors to client-safe messages.
+  - `streamAuthorSSE(request, config, options?)`: the lower-level primitive for
+    hosts that build/validate the `AuthorRequest` themselves.
+  - `parseChatRequest(req, limits?)`: body/command size bounds and shape
+    validation (rejects a non-object or array `currentGraph`).
+- **`@flowget/ai-chat/styles.css`** — a self-contained stylesheet. Every value
+  reads a `--flowget-*` design token with a sensible built-in fallback, so the
+  chat renders standalone and inherits a host's theme where those tokens are
+  defined. Placement is tunable via `--fg-aichat-z` and
+  `--fg-aichat-launcher-offset`; class names use the `fg-aichat-` namespace.
+
+### Security
+
+- The `/server` helper is **unauthenticated by design**. The host must place
+  its own authentication, authorization, and rate-limiting in front of the
+  route, and inject a server-derived `actor` via `buildRequest` for any
+  actor-scoped data access. Server errors are logged server-side and never
+  forwarded verbatim to the browser. See the README "Security" section.

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Flowget
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,228 @@
+# @flowget/ai-chat
+
+Builder-agnostic **AI workflow-authoring chat** for [Flowget](https://flowget.io).
+
+A user describes a workflow in natural language; the chat streams a proposal,
+shows an **approval card**, and — once approved — applies the laid-out graph to
+your canvas. Editing works the same way (the current graph is the context).
+
+Built on assistant-ui primitives (streaming, approval gate, thread) and
+[`@flowget/ai`](https://github.com/flowgethq/ai)'s streaming `author()` — with
+**no lock-in**: the LLM stays behind `@flowget/ai`'s BYO adapter, and the chat
+never imports your builder.
+
+## Two entry points
+
+| Import | Runs | What |
+| --- | --- | --- |
+| `@flowget/ai-chat/react` | browser | `<WorkflowChat>` — the chat panel + streaming runtime + proposal card |
+| `@flowget/ai-chat/server` | your BFF | `createChatStreamResponse()` — SSE over `@flowget/ai`'s `authorStream()` |
+| `@flowget/ai-chat/styles.css` | — | the stylesheet (import once) |
+
+## Install
+
+```bash
+npm install @flowget/ai-chat @flowget/ai @assistant-ui/react
+```
+
+`react`, `react-dom`, `@assistant-ui/react` are peer deps (you provide them).
+`@flowget/ai` is an **optional** peer — install it only if you use the
+`/server` helper (the authoring engine runs there). A react-only consumer with
+its own backend transport can skip it.
+
+## Client — mount the chat
+
+Drop `<WorkflowChat>` inside your builder. It's builder-agnostic: pass the live
+`currentGraph` and an `applyGraph` callback (e.g. your store's `setGraph`). The
+chat proposes; you apply.
+
+```tsx
+import "@flowget/ai-chat/styles.css";
+import { WorkflowChat } from "@flowget/ai-chat/react";
+import { useFlowgetWorkflow } from "@flowget/builder"; // your builder
+
+function BuilderChat() {
+  const { graph, setGraph } = useFlowgetWorkflow();
+  return <WorkflowChat currentGraph={graph} applyGraph={setGraph} />;
+}
+
+// inside your builder's children slot:
+// <FlowgetBuilder ...><BuilderChat /></FlowgetBuilder>
+```
+
+`WorkflowChat` props:
+
+| Prop | Type | |
+| --- | --- | --- |
+| `currentGraph` | `WorkflowGraph` | live canvas graph (edit context + layout baseline) |
+| `applyGraph` | `(g: WorkflowGraph) => void` | commit a laid-out graph to the canvas |
+| `transport?` | `ChatStreamTransport` | fully custom backend transport (overrides `endpoint`) |
+| `endpoint?` | `string` | endpoint for the default SSE transport (`/api/chat`) |
+| `heading?` | `string` | panel heading (default `"Workflow AI"`) |
+| `subtitle?` | `string` | panel subtitle (default `"Draft & edit with a prompt"`) |
+| `examples?` | `readonly string[]` | empty-state suggestion chips; `[]` hides them |
+| `layout?` | `WorkflowLayout` | lay a proposal out before apply (default `layoutProposal`) — see below |
+| `actor?` | `ChatActor` | caller-identity hint — **untrusted on the wire** (see [Security](#security)) |
+| `context?` | `unknown` | opaque continuity payload forwarded to the model |
+
+### Layout — delegate to your builder
+
+By default the chat lays each proposal out with the built-in `layoutProposal`
+(a zero-dependency BFS layered layout that preserves the positions of nodes
+already on the canvas). A builder-host with a better layout — e.g. a dagre
+`autoLayout` / merge — injects it via the `layout` prop, keeping ai-chat
+builder-agnostic (the host supplies the function; the chat never imports your
+builder):
+
+```tsx
+import { WorkflowChat, type WorkflowLayout } from "@flowget/ai-chat/react";
+
+const layout: WorkflowLayout = (proposed, current) => mergeGraph(current, proposed);
+
+<WorkflowChat currentGraph={graph} applyGraph={setGraph} layout={layout} />;
+```
+
+`layout: (proposed: ProposedGraph, current: WorkflowGraph) => WorkflowGraph`.
+`layoutProposal` stays exported as the default / fallback.
+
+### Headless mode
+
+`<WorkflowChat>` is a turnkey shell built from smaller pieces. To bring your own
+shell — or render assistant-ui primitives yourself — compose them directly:
+
+```tsx
+import {
+  ChatRuntimeProvider,
+  httpChatStreamTransport,
+  layoutProposal,
+} from "@flowget/ai-chat/react";
+
+// getCurrentGraph must be referentially stable (a ref getter, not an inline fn)
+<ChatRuntimeProvider getCurrentGraph={getCurrentGraph} transport={httpChatStreamTransport("/api/chat")}>
+  {/* your own assistant-ui <Thread>, composer, and proposal rendering */}
+</ChatRuntimeProvider>
+```
+
+- `ChatRuntimeProvider` — wires assistant-ui's `LocalRuntime` to the authoring
+  adapter and provides it to your subtree.
+- `createWorkflowChatAdapter(...)` — the raw `ChatModelAdapter`, if you drive
+  the runtime yourself.
+- `httpChatStreamTransport(endpoint?)` — the default SSE transport; swap it for
+  any `ChatStreamTransport` (an async generator of `ChatStreamEvent`s) to reach
+  a custom backend.
+- `layoutProposal(proposed, current?)` — the pure layout helper (BFS layered
+  layout; preserves the positions of nodes that already exist on the canvas).
+
+## Server — the BFF route
+
+Wire your `@flowget/ai` config (your node catalog + LLM adapter) into the SSE
+helper. The engine runs entirely server-side.
+
+```ts
+import { createChatStreamResponse } from "@flowget/ai-chat/server";
+import { finalizeConfig, resolveCatalog, openaiAdapter } from "@flowget/ai";
+
+const catalog = await resolveCatalog({ registryDir: process.env.REGISTRY_DIR! });
+const config = finalizeConfig(
+  { adapter: openaiAdapter({ apiKey: process.env.OPENROUTER_API_KEY! }), catalog },
+  catalog,
+);
+
+// e.g. a Bun / Node / edge handler for POST /api/chat
+export async function POST(req: Request): Promise<Response> {
+  // ⚠️ Your auth + rate-limiting run FIRST — see Security below.
+  const session = await getSession(req);
+  if (!session) return new Response("Unauthorized", { status: 401 });
+
+  return createChatStreamResponse(req, config, {
+    // Inject a SERVER-DERIVED actor over the untrusted client value:
+    buildRequest: (parsed) => ({ ...parsed, actor: session.actor }),
+  });
+}
+```
+
+`createChatStreamResponse(req, config, options?)` — parses + validates the
+request, then streams the authoring result as SSE. Options:
+
+| Option | | |
+| --- | --- | --- |
+| `buildRequest?` | `(parsed, req) => AuthorRequest` | rebuild the request — inject a server-derived `actor` / `context` |
+| `onError?` | `(err) => string` | map an error to a client-safe message (default `"Authoring failed"`) |
+| `maxBodyBytes?` | `number` | request-body cap (default 1 MiB) |
+| `maxCommandLength?` | `number` | `command` length cap (default 8000) |
+
+Need to build the `AuthorRequest` yourself? Use the lower-level
+`streamAuthorSSE(request, config, { signal?, onError? })`.
+
+The wire format between `/server` and `/react` is SSE: one `data:`-framed event
+per line — `text-delta`\* then a terminal `proposal | message`, or `error`.
+
+## Security
+
+The `/server` helper is **unauthenticated by design** and does **no**
+rate-limiting. It is streaming plumbing, not a security boundary.
+
+**You MUST:**
+
+- Put your own **authentication and authorization** in front of the route
+  (reject unauthenticated requests before calling the helper).
+- Add **rate-limiting** / abuse protection — each request drives an LLM call.
+- Treat the client-supplied `actor` as **untrusted**. It is plain JSON on the
+  request body; a browser can send anything. If any `@flowget/ai` toolset or
+  authorizer gates data access on the actor (e.g. by `tenantId`), derive the
+  actor **server-side** (from your session/JWT) and inject it with
+  `buildRequest` — and/or verify it with a `@flowget/ai` authorizer. Otherwise
+  a client can spoof it.
+
+Server-side errors are logged on the server and never forwarded verbatim to the
+browser (the client only sees a generic message, or your `onError` mapping).
+
+## Theming
+
+Import the stylesheet once — it is **self-contained** and renders correctly with
+no host theme. Every value reads a `--flowget-*` design token with a built-in
+fallback, so where your app defines those tokens (light/dark), the chat inherits
+them automatically; where it doesn't, the fallback applies.
+
+Overridable design tokens (set them on `:root` or any ancestor):
+
+| Token | Fallback | Used for |
+| --- | --- | --- |
+| `--flowget-color-accent` | `#6366f1` | primary / brand accent |
+| `--flowget-color-text` | `#0f172a` | body text |
+| `--flowget-color-text-subtle` | `#64748b` | secondary text |
+| `--flowget-color-text-inverse` | `#ffffff` | text on the accent |
+| `--flowget-color-bg` | `#ffffff` | input / chip background |
+| `--flowget-color-bg-elevated` | `#ffffff` | panel background |
+| `--flowget-color-surface-strong` | `#f8fafc` | proposal-card surface |
+| `--flowget-color-border` | `#e2e8f0` | borders |
+| `--flowget-color-border-strong` | `#cbd5e1` | hover borders |
+| `--flowget-color-danger` | `#dc2626` | error state |
+| `--flowget-color-success` | `#16a34a` | applied confirmation |
+| `--flowget-radius-lg` / `-md` | `14px` / `9px` | corner radii |
+| `--flowget-shadow-lg` | `0 12px 32px -8px rgba(15,23,42,.28)` | panel / launcher shadow |
+| `--flowget-font-sans` / `-mono` | system stacks | typography |
+| `--flowget-font-size-sm` / `-xs` / `-md` | `13px` / `11px` / `15px` | type scale |
+| `--flowget-motion-fast` | `140ms` | transition duration |
+
+Two package-owned knobs control placement (class prefix: `fg-aichat-`):
+
+| Token | Fallback | |
+| --- | --- | --- |
+| `--fg-aichat-z` | `200` | stacking order of the launcher + panel |
+| `--fg-aichat-launcher-offset` | `24px` | gap from the bottom-right corner |
+
+## How it fits together
+
+```
+browser                          your BFF                         @flowget/ai
+────────                         ────────                         ───────────
+<WorkflowChat>                   createChatStreamResponse(req,cfg)
+  LocalRuntime ── POST /api/chat ──►  authorStream(cfg, request) ──► BYO adapter (LLM)
+  (streams text) ◄──── SSE ────────   (text-delta* → proposal|message)
+  proposal card → Apply → applyGraph(graph)   (your canvas)
+```
+
+## License
+
+FSL-1.1-ALv2