From 826f969579e87db81db4a254786ccc748b0efdf5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 00:01:22 +0000 Subject: [PATCH 01/15] Rewrite framework docs to showcase power and developer experience MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The existing docs read like internal specs — accurate but uninspiring. This rewrites the main README, architecture overview, and four package READMEs to lead with working code examples, convey the developer experience, and make the framework's value proposition immediately clear. Key changes: - README.md: Lead with a complete code example, show the full-stack DX (server, client, React, testing), replace bullet-point feature lists with narrative explanations of what you get - docs/architecture/overview.md: Add "the idea in 30 seconds" section with code, make abstractions concrete with usage context - packages/core/README.md: Show all four block kinds in action with real patterns (tools, history, rescue, routing) - packages/server/README.md: Lead with the 3-line API setup, organize around what you can do rather than what exists - packages/client/README.md: Show streaming and resume patterns, compare client variants in a table - packages/react/README.md: Lead with a complete chat UI example, explain the architecture (hooks wrap client, no transport in UI) https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- README.md | 302 ++++++++++++++++++++-------------- docs/architecture/overview.md | 116 ++++++++----- packages/client/README.md | 123 +++++++------- packages/core/README.md | 153 ++++++++++------- packages/react/README.md | 193 +++++++++++----------- packages/server/README.md | 157 ++++++++---------- 6 files changed, 582 insertions(+), 462 deletions(-) diff --git a/README.md b/README.md index 523a44a746..69fb51688e 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,200 @@ -# flow-state-dev -`@flow-state-dev` is a block-based AI workflow framework focused on typed flows, resumable streaming, and predictable execution behavior. - -This repository is the active implementation workspace for Phase 1. - -## Why this project exists - -Building AI features often means stitching together orchestration, retries, streaming, state, and UI glue in app-specific ways. -`@flow-state-dev` aims to make those concerns first-class framework primitives so teams can ship faster with less runtime drift. - -## Why this repo may be worth your time - -- You want a framework that doesn't prebake the patterns that you use to implement agentic systems, but instead the primitives that allow you to build your own. -- You want a typed flow model, not ad-hoc handler chains. -- You want advanced state and memory management for your agentic workflows and agents. -- You care about execution semantics (retry, rescue, lifecycle) being explicit and testable. -- You want item-first streaming with replay/resume, not one-off transport wiring. -- You want one stack across server, client, React UI, CLI, and tests. - -## Current maturity (Phase 1) - -- Core contracts and block builders are implemented. -- Server execution, stores, and streaming runtime are implemented. -- Client transport/session/SSE APIs are implemented and tested. -- React hook wrappers, renderer registry, and item render helpers are implemented and tested. -- Testing package APIs are implemented and validated. -- Canonical Wave K example flows are implemented in: - - `examples/hello-chat/src/flows/hello-chat/flow.ts` - - `examples/kitchen-sink/src/flows/kitchen-sink/flow.ts` -- CLI/devtool packages remain in active implementation. - -This is an implementation-phase repository, not a polished production release yet. - -## Core concepts - -- **Flow**: declared via `defineFlow`, with flow-level `actions`. -- **Block kinds**: exactly `handler`, `generator`, `sequencer`, `router`. -- **Generator**: loop-capable runtime unit with framework-managed execution. -- **Scopes**: request/session/user/project state + resource updates. -- **Execution entrypoint**: blocks execute via framework-owned `block.run(...)`. -- **Streaming model**: item/content lifecycle events with sequence-based replay. -- **Execution model**: normalized errors, retry policy, rescue routing, work convergence. - -## Package map - -- `@flow-state-dev/core`: builders, contracts, item/event taxonomy. -- `@flow-state-dev/server`: action runtime, stores, SSE streaming, orchestration. -- `@flow-state-dev/client`: isomorphic action/session/stream API client. -- `@flow-state-dev/react`: hooks and render/runtime bindings. -- `@flow-state-dev/testing`: flow/block/runtime test harnesses. -- `@flow-state-dev/cli`: `fsdev` CLI for running/inspecting flows. -- `apps/devtool`: first-party inspector app using public framework APIs. -- `examples/hello-chat`: minimal canonical chat flow example. -- `examples/kitchen-sink`: comprehensive canonical feature-reference flow example. - -## Repository layout - -```text -packages/ - core/ # Isomorphic builders, type contracts, item taxonomy - server/ # Action runtime, stores, SSE streaming - client/ # Isomorphic HTTP/SSE transport client - react/ # React hooks, renderers, context providers - testing/ # Test harnesses for blocks, flows, generators - cli/ # fsdev CLI for running/inspecting flows -apps/ - devtool/ # First-party inspector app - docs/ # Docusaurus documentation site -examples/ - hello-chat/ # Minimal canonical chat flow - kitchen-sink/ # Comprehensive feature-reference flow -docs/ - architecture/ # Framework developer reference (9 topic docs) - contributing/ # Standards, setup, process docs - internal/ # Wave plans, journals, changelogs +# @flow-state-dev + +**Build AI workflows with blocks. Get streaming, state, retries, and type safety for free.** + +```ts +import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; + +const chat = generator({ + name: "chat", + model: "gpt-5-mini", + prompt: "You are a helpful assistant.", + inputSchema: z.object({ message: z.string() }), + history: (_input, ctx) => ctx.session.items.llm(), + user: (input) => input.message, +}); + +const trackUsage = handler({ + name: "track-usage", + sessionStateSchema: z.object({ messageCount: z.number().default(0) }), + execute: async (input, ctx) => { + await ctx.session.incState({ messageCount: 1 }); + return input; + }, +}); + +const pipeline = sequencer({ name: "chat-pipeline" }) + .then(chat) + .then(trackUsage); + +export default defineFlow({ + kind: "my-app", + actions: { + chat: { block: pipeline, userMessage: (i) => i.message }, + }, + session: { stateSchema: z.object({ messageCount: z.number().default(0) }) }, +})({ id: "default" }); ``` -## Quick start +That's a streaming chat with conversation history, session state, and atomic counters. No transport wiring. No SSE plumbing. No retry logic. The framework handles all of it. + +## What you get + +**Four block primitives. Infinite compositions.** + +| Block | What it does | +|-------|-------------| +| **handler** | Pure logic — validate, transform, mutate state | +| **generator** | Call an LLM with managed tool loops, streaming, and structured output repair | +| **sequencer** | Compose blocks into pipelines with `.then()`, `.parallel()`, `.rescue()`, `.forEach()`, and 10 more DSL methods | +| **router** | Dispatch to different pipelines at runtime based on input or state | + +**Scoped state that scales.** Four isolation levels — request, session, user, project — each with atomic operations (`patchState`, `incState`, `pushState`, `atomicState`). Every block declares only the state fields it needs. Type-safe all the way down. + +**Resumable streaming out of the box.** Items stream over SSE as blocks execute. Disconnect mid-response? Reconnect with a sequence cursor and pick up exactly where you left off. No data loss. No duplicate events. + +**Resources and projections for data policy.** Resources are typed, named state containers. Projections are derived views — and the *only* way to expose data to clients. You can't accidentally leak internal state. + +**First-class error handling.** Retry policies per block. Type-based rescue routing. Non-aborting work queues for side-chain operations. Normalized error model with codes, scopes, and retry signals. + +**Full-stack type safety.** Define a schema once in Zod. It validates at runtime, infers at compile time, and flows from server blocks through the client SDK to React hooks. One type system, zero glue code. + +## The developer experience + +**Server** — Register flows and get a complete API with three lines: + +```ts +const registry = createFlowRegistry(); +registry.register(myFlow); +export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); +``` + +**Client** — Connect from anywhere, framework handles SSE and state sync: + +```ts +const client = createClient({ flowKind: "my-app", userId: "user_1" }); +await client.sendAction("chat", { message: "Hello" }); +``` + +**React** — Hooks that wire streaming, items, and projections to your UI: + +```tsx + + + + +function ChatUI() { + const flow = useFlow({ autoCreateSession: true }); + const session = useSession(flow.activeSessionId); + + return ( + <> + {session.items.map(item => )} + + + ); +} +``` + +**Testing** — Deterministic tests with generator mocks, no real LLM calls: -### Prerequisites +```ts +const result = await testBlock(pipeline, { + input: { message: "Hello" }, + session: { state: { messageCount: 0 } }, + generators: { "chat": mockGenerator({ script: [{ text: "Hi there!" }] }) }, +}); -- Node.js `>=18` (Node 20+ recommended) -- `pnpm@10.4.1` +expect(result.items).toContainItemOfType("message"); +expect(result.stateChanges[0].resultingState.messageCount).toBe(1); +``` + +## When this framework is for you + +- You're building AI-powered features and tired of reinventing orchestration, streaming, and state management every time. +- You want composable primitives, not a rigid agent framework that prescribes how you structure your AI. +- You care about execution semantics — retry, rescue, lifecycle hooks — being explicit and testable, not hidden in application glue. +- You want one coherent stack across server, client, React, CLI, and tests. +- You want the confidence that comes from end-to-end type safety with zero code generation. + +## Packages + +| Package | Purpose | +|---------|---------| +| [`@flow-state-dev/core`](packages/core) | Block builders, flow definitions, type contracts, item taxonomy | +| [`@flow-state-dev/server`](packages/server) | Execution runtime, stores, SSE streaming, HTTP routes | +| [`@flow-state-dev/client`](packages/client) | Isomorphic API client — actions, sessions, streams | +| [`@flow-state-dev/react`](packages/react) | React hooks and renderers | +| [`@flow-state-dev/testing`](packages/testing) | Test harnesses and generator mocks | +| [`@flow-state-dev/cli`](packages/cli) | Terminal interface (`fsdev`) | +| [`apps/devtool`](apps/devtool) | First-party flow inspector | -### Setup +## Quick start ```bash +# Prerequisites: Node.js >=18, pnpm@10.4.1 pnpm install pnpm typecheck pnpm test ``` -### Common commands +## Examples -- Run all tests: `pnpm test` -- Run all typechecks: `pnpm typecheck` -- Watch tests: `pnpm test:watch` -- Test one package: `pnpm --filter @flow-state-dev/server test` -- Typecheck one package: `pnpm --filter @flow-state-dev/core typecheck` +**[hello-chat](examples/hello-chat)** — Minimal chat flow. Generator + handler + sequencer in ~50 lines. Start here. -## Start here (new contributors) +**[kitchen-sink](examples/kitchen-sink)** — Everything the framework can do. Router-based dispatch, handler-backed tools, session resources with projections, rescue boundaries, and a full Next.js UI. -1. Read architecture overview: `docs/architecture/overview.md` -2. Browse topic docs: `docs/architecture/` (blocks, flows, state, streaming, etc.) -3. Review current progress: `changelog.md` -4. Review standards: `docs/contributing/best-practices.md` -5. For canonical edge cases: `../preperation/architecture/` +## Architecture -## Documentation map +The framework ships as six packages with strict dependency boundaries: -**Architecture reference** (`docs/architecture/`): -- [Overview](docs/architecture/overview.md) — package structure, core abstractions, data flow -- [Blocks](docs/architecture/blocks.md) — handler, generator, sequencer, router -- [Flows and Actions](docs/architecture/flows-and-actions.md) — defineFlow, actions, lifecycle -- [State and Scopes](docs/architecture/state-and-scopes.md) — 4 scopes, state ops, CAS -- [Streaming](docs/architecture/streaming.md) — item/content model, SSE protocol, resume -- [Execution and Errors](docs/architecture/execution-and-errors.md) — retry, rescue, work queue -- [Resources and Projections](docs/architecture/resources-and-projections.md) — typed data management -- [Sequencer DSL](docs/architecture/sequencer-dsl.md) — full method reference -- [Server and Client](docs/architecture/server-and-client.md) — routes, transport, React hooks +``` +core ← server ← testing +core ← client ← react ← apps/devtool +``` + +- `server` never depends on `client` or `react` +- `react` wraps `client` — no transport logic in the UI layer +- `apps/devtool` uses only public APIs + +Request lifecycle: +``` +POST /api/flows/{kind}/actions/{action} + → 202 Accepted (async execution) + → SSE stream: items, content deltas, status events + → request.completed + → Client refetches state snapshot +``` + +Resume after disconnect: `Last-Event-ID` or `starting_after` query param replays events from the sequence cursor. + +## Documentation + +**Architecture** (`docs/architecture/`): +- [Overview](docs/architecture/overview.md) — System architecture, data flow, core abstractions +- [Blocks](docs/architecture/blocks.md) — Handler, generator, sequencer, router deep dive +- [Flows and Actions](docs/architecture/flows-and-actions.md) — defineFlow, actions, lifecycle hooks +- [State and Scopes](docs/architecture/state-and-scopes.md) — Four scopes, atomic ops, CAS concurrency +- [Streaming](docs/architecture/streaming.md) — Item/content model, SSE protocol, resume semantics +- [Execution and Errors](docs/architecture/execution-and-errors.md) — Retry, rescue, work queue +- [Resources and Projections](docs/architecture/resources-and-projections.md) — Typed data containers and derived views +- [Sequencer DSL](docs/architecture/sequencer-dsl.md) — Full method reference +- [Server and Client](docs/architecture/server-and-client.md) — Routes, transport, React hooks **Contributing** (`docs/contributing/`): -- [Best Practices](docs/contributing/best-practices.md) — implementation standards (BP-001–BP-009) -- [Architecture Reference](docs/contributing/architecture-reference.md) — locked contracts quick reference -- [Development Setup](docs/contributing/development-setup.md) — monorepo setup and workflow -- [Wave Process](docs/contributing/wave-process.md) — wave execution protocol - -**Other**: -- Canonical architecture (authoritative for edge cases): `../preperation/architecture/` -- Package READMEs: `packages/*/README.md` -- Example READMEs: `examples/*/README.md` -- Changelog: `changelog.md` -- Agent protocol: `AGENTS.md` - -## Contributing notes - -- Keep onboarding-relevant changes reflected in this README. -- Keep implementation standards in `docs/contributing/best-practices.md`. -- Keep wave/process protocol in `AGENTS.md` (not in README). -- See `AGENTS.md` for the full documentation maintenance protocol. +- [Best Practices](docs/contributing/best-practices.md) — Implementation standards +- [Architecture Reference](docs/contributing/architecture-reference.md) — Locked contracts +- [Development Setup](docs/contributing/development-setup.md) — Monorepo workflow +- [Wave Process](docs/contributing/wave-process.md) — Wave execution protocol + +## Current status + +Phase 1 (Foundation) — Waves 1.a through 1.k are complete. Core contracts, block builders, server runtime, client transport, React bindings, and testing utilities are all implemented and tested. CLI and devtool are in active development. + +## Contributing + +- See [`AGENTS.md`](AGENTS.md) for the process protocol +- See [`docs/contributing/`](docs/contributing/) for standards and setup +- Keep implementation standards in `docs/contributing/best-practices.md` diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 95ffcf24d9..fa0de655a1 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,12 +1,42 @@ # Architecture Overview -`@flow-state-dev` is a block-based AI workflow framework. You define **flows** composed of **blocks**, and the framework handles execution, streaming, state persistence, retries, and client rendering. +`@flow-state-dev` gives you four composable block primitives — **handler**, **generator**, **sequencer**, **router** — and a runtime that handles execution, streaming, state persistence, retries, and client rendering so you don't have to. + +You define flows composed of blocks. The framework does the rest. This document provides the system-level view. For deep dives into each subsystem, see the companion docs linked throughout. -## Package Structure +## The idea in 30 seconds -The framework ships as six packages plus one first-party app: +Every AI feature needs the same infrastructure: call an LLM, stream the response, manage state, handle errors, sync with the UI. Teams rebuild this for every project. `@flow-state-dev` makes these concerns framework primitives. + +```ts +// Define blocks +const chat = generator({ name: "chat", model: "gpt-5-mini", prompt: "..." }); +const track = handler({ name: "track", execute: async (input, ctx) => { + await ctx.session.incState({ count: 1 }); + return input; +}}); + +// Compose into a pipeline +const pipeline = sequencer({ name: "pipeline" }) + .then(chat) + .then(track) + .rescue([{ when: [Error], block: fallback }]); + +// Expose as a flow +export default defineFlow({ + kind: "my-app", + actions: { chat: { block: pipeline } }, + session: { stateSchema }, +})({ id: "default" }); +``` + +The framework gives you: SSE streaming with resume, atomic state operations, retry policies, rescue boundaries, lifecycle hooks, typed client SDK, React hooks — all from this definition. + +## Package structure + +Six packages with strict dependency boundaries: ``` @flow-state-dev/core Isomorphic builders, type contracts, item taxonomy @@ -18,7 +48,7 @@ The framework ships as six packages plus one first-party app: apps/devtool First-party inspector app ``` -## Dependency Graph +## Dependency graph ``` core ─────────────────────────────────┐ @@ -36,29 +66,29 @@ core ───────────────────────── └── client ``` -**Boundary rules:** -- `server` never depends on `react` or `client` -- `client` never depends on `server` or `react` -- `react` has no transport logic — it wraps `client` +**Boundary rules (locked):** +- `server` never depends on `react` or `client` — server knows nothing about transport consumers +- `client` never depends on `server` or `react` — works in any JavaScript environment +- `react` has no transport logic — it wraps `client` with hooks and renderers - `cli` uses `server` + `testing`, never `react` or `client` - `apps/devtool` uses only public APIs from `client` and `react` -## Core Abstractions +## Core abstractions -### Blocks +### Blocks — the four primitives -Four block kinds compose all framework behavior: +Every piece of logic in the framework is one of exactly four block kinds: -| Kind | Purpose | Example | -|------|---------|---------| -| **handler** | Synchronous logic: `input → execute → output` | Validate input, transform data, update state | -| **generator** | LLM call with framework-managed tool loop | Chat completion, structured extraction, agent tool use | -| **sequencer** | Fluent DSL composing blocks into pipelines | `then`, `parallel`, `forEach`, `rescue`, `work` | -| **router** | Runtime block selection | Route to different pipelines based on input/state | +| Kind | What it does | When to use it | +|------|-------------|----------------| +| **handler** | `input → execute → output` | Validation, data transforms, state mutations, tool implementations | +| **generator** | LLM call with framework-managed tool loop | Chat, structured extraction, agent tool use, any AI generation | +| **sequencer** | Fluent DSL composing blocks into pipelines | Building multi-step workflows with branching, parallelism, error recovery | +| **router** | Runtime block selection based on input or state | Dispatching to different pipelines based on mode, intent, or conditions | -All blocks share the same execution contract: `block.run(input, ctx)`. See [Blocks](./blocks.md). +All blocks share the same execution contract: `block.run(input, ctx)`. This uniformity means any block can be composed with any other block. See [Blocks](./blocks.md). -### Flows +### Flows — the entry point A flow ties blocks to **actions** (entry points), **scopes** (state containers), and **lifecycle hooks**: @@ -69,36 +99,46 @@ const myFlow = defineFlow({ actions: { chat: { inputSchema, block: chatPipeline, userMessage: (i) => i.message } }, - session: { stateSchema } + session: { stateSchema, resources: { ... }, projections: { ... } }, + user: { stateSchema, projections: { ... } }, }); ``` -See [Flows and Actions](./flows-and-actions.md). +Actions are the flow's public API. Clients call them by name. Each action maps to a root block that the framework executes. See [Flows and Actions](./flows-and-actions.md). -### Scopes +### Scopes — state that scales -Four nested state scopes with typed operations: +Four nested state scopes, each with typed atomic operations: ``` request → session → user → project +(one run) (conversation) (across sessions) (shared across users) ``` -Each scope provides atomic state operations (`patchState`, `incState`, `pushState`, etc.) with CAS-based concurrency. See [State and Scopes](./state-and-scopes.md). +Each scope provides `patchState`, `setState`, `incState`, `pushState`, `atomicState`, and more — all CAS-guarded for concurrency safety. Blocks declare only the state fields they need via partial schemas, so a counter block doesn't need to know about a preferences block's state. See [State and Scopes](./state-and-scopes.md). -### Streaming +### Streaming — resilient by default -SSE-based item/content streaming model: +SSE-based item/content streaming with built-in resume: -- Items have types (`message`, `reasoning`, `component`, `status`, `error`, etc.) -- Content streams within items via delta events -- Sequence-number cursors enable replay/resume -- Item types determine audience routing (client, LLM, devtools) +- **Items** have types (`message`, `reasoning`, `component`, `status`, `error`, etc.) and lifecycle states (`in_progress` → `completed`) +- **Content** streams within items via delta events — text appears token-by-token +- **Sequence-number cursors** enable replay after disconnect — no data loss, no duplicates +- **Item types determine audience routing** — some items go to the UI, some to the LLM context, some to devtools See [Streaming](./streaming.md). -## Data Flow +### Resources and projections — data with policy + +**Resources** are named, typed state containers scoped to sessions, users, or projects. Think of them as structured data stores that blocks can read and write. + +**Projections** are derived views computed from state and resources — and the *only* way to expose data to clients. This is a deliberate architectural choice: you can't accidentally leak internal state because projections are the sole data gateway. + +See [Resources and Projections](./resources-and-projections.md). + +## Data flow -A typical request flows through the system like this: +A typical request flows through the system: ``` Client Server Store @@ -123,12 +163,12 @@ Client Server Store ``` Key points: -1. POST returns `202 Accepted` immediately — execution is async -2. Items stream live via SSE as blocks execute -3. Client refetches state snapshot on `request.completed` (correctness path) -4. Resume after disconnect uses `Last-Event-ID` or `starting_after` query param +1. **Async by design** — POST returns `202 Accepted` immediately. Execution happens in the background. +2. **Live streaming** — Items stream via SSE as blocks execute. The client sees results as they're produced. +3. **Correctness path** — Client refetches the state snapshot on `request.completed` to get the authoritative final state. +4. **Resilient resume** — Reconnect after disconnect using `Last-Event-ID` or `starting_after` query param. The server replays missed events from the sequence cursor. -## Locked Contracts (Phase 1) +## Locked contracts (Phase 1) These decisions are canonical and cannot change without architecture review: @@ -141,6 +181,6 @@ These decisions are canonical and cannot change without architecture review: - Generator provider: Vercel AI SDK in Phase 1 - Observational hooks: past tense (`onStarted`, `onCompleted`, `onErrored`, `onFinished`) -## Canonical Authority +## Canonical authority For edge cases and detailed contracts, the canonical specs in `../preperation/architecture/` are authoritative. The docs in this directory are adapted summaries — when in doubt, check the source spec. diff --git a/packages/client/README.md b/packages/client/README.md index 71e2d14b71..3833a69edf 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -1,95 +1,100 @@ # @flow-state-dev/client -Isomorphic transport/API client for Flow State Dev. +**Connect to flows from anywhere. Actions, sessions, streaming — no framework lock-in on the client side.** -`@flow-state-dev/client` owns framework network access: -- action execution -- session CRUD + session request listing -- session state snapshots (scope state + scope-grouped projections + optional items) -- request/user SSE consumption +Works in Node, the browser, edge runtimes. No React dependency. No DOM dependency. Just HTTP and SSE. -No React or DOM dependency. - -## Public API +```ts +import { createClient } from "@flow-state-dev/client"; -- `createClient(options)` -- `createTypedClient(options)` -- `createSessionClient(options)` -- `createSSEClient(options)` -- `createUserSSEClient(options)` -- `ClientHttpError` +const client = createClient({ flowKind: "my-app", userId: "user_1" }); -## `createClient` vs `createTypedClient` +// Send an action and get back a request ID +const { requestId } = await client.sendAction("chat", { message: "Hello" }); -`createClient`: -- dynamic action names (`sendAction("run", input)`) -- best for tooling and generic UIs +// Or use a typed client for compile-time action safety +const typed = createTypedClient({ flow: myFlowDefinition, userId: "user_1" }); +await typed.actions.chat({ message: "Hello" }); +``` -`createTypedClient`: -- flow-bound action methods (`actions.run(input)`) -- best when a flow definition is available at compile time +## Streaming -## Usage +Subscribe to a request's SSE stream with typed event handlers: ```ts -import { createClient } from "@flow-state-dev/client"; +import { createSSEClient } from "@flow-state-dev/client"; -const client = createClient({ - flowKind: "demo", - userId: "devuser", +const stream = createSSEClient({ + url: `/api/flows/my-app/requests/${requestId}/stream`, + onItemAdded: (event) => { + // New item appeared (message, reasoning, component, etc.) + }, + onContentDelta: (event) => { + // Text chunk arrived — append to the current item's content + }, + onRequestStatus: (event) => { + if (event.status === "completed") { + // Refetch state snapshot for the authoritative final state + } + }, }); - -await client.sendAction("run", { value: "hello" }, { sessionId: "sess_1" }); ``` -Typed client: +Resume after disconnect — pass a sequence cursor and the server replays missed events: ```ts -import { createTypedClient } from "@flow-state-dev/client"; - -const typed = createTypedClient({ flow, userId: "devuser" }); -await typed.actions.run({ value: "hello" }); +const stream = createSSEClient({ + url: `/api/flows/my-app/requests/${requestId}/stream?starting_after=${lastSeq}`, + // ...handlers +}); ``` -Snapshot API with query controls: +## Session management ```ts -const sessions = createSessionClient(); +import { createSessionClient } from "@flow-state-dev/client"; + +const sessions = createSessionClient({ flowKind: "my-app", userId: "user_1" }); +// State snapshot with projections and items const snapshot = await sessions.getSessionState("sess_1", { includeItems: true, - projections: ["session.artifactsList", "user.topics"], + projections: ["session.artifactsList", "user.preferences"], }); ``` -### SSE Stream Client +## `createClient` vs `createTypedClient` -```ts -import { createSSEClient } from "@flow-state-dev/client"; +| | `createClient` | `createTypedClient` | +|--|----------------|---------------------| +| Action calls | `sendAction("chat", input)` | `actions.chat(input)` | +| Type safety | Runtime only | Compile-time + runtime | +| Best for | Generic UIs, devtools | App code with known flow definitions | -const stream = createSSEClient({ - url: `/api/flows/my-flow/requests/${requestId}/stream`, - onItemAdded: (event) => { /* handle new item */ }, - onContentDelta: (event) => { /* handle text chunk */ }, - onRequestStatus: (event) => { - if (event.status === "completed") { /* refetch state */ } - }, -}); -``` +## Public API + +- `createClient(options)` — Dynamic action client +- `createTypedClient(options)` — Flow-bound typed client +- `createSessionClient(options)` — Session CRUD and state snapshots +- `createSSEClient(options)` — Request stream consumer +- `createUserSSEClient(options)` — User-level stream consumer +- `ClientHttpError` — Typed HTTP error class ## Notes -- `userId` is required for Phase 1 action/session calls. -- Request stream resume supports both `Last-Event-ID` and `starting_after`. -- When both resume inputs are supplied, `starting_after` takes precedence. +- `userId` is required for Phase 1 action/session calls +- Stream resume supports both `Last-Event-ID` header and `starting_after` query param +- When both are supplied, `starting_after` takes precedence -## Architecture Reference +## Scripts -- [Server and Client](../../docs/architecture/server-and-client.md) — routes, transport, React hooks contract -- [Streaming](../../docs/architecture/streaming.md) — item/content model, SSE protocol, resume +```bash +pnpm --filter @flow-state-dev/client build +pnpm --filter @flow-state-dev/client typecheck +pnpm --filter @flow-state-dev/client test +``` -## Scripts +## Architecture reference -- `pnpm --filter @flow-state-dev/client build` -- `pnpm --filter @flow-state-dev/client typecheck` -- `pnpm --filter @flow-state-dev/client test` +- [Server and Client](../../docs/architecture/server-and-client.md) — Routes, transport, React hooks contract +- [Streaming](../../docs/architecture/streaming.md) — Item/content model, SSE protocol, resume semantics diff --git a/packages/core/README.md b/packages/core/README.md index d94ffb205d..ab24af18b6 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,93 +1,119 @@ # @flow-state-dev/core -Isomorphic builders, type contracts, and item taxonomy for Flow State Dev. +**The building blocks. Define handlers, generators, sequencers, routers, and flows — all with end-to-end type safety.** -This is the foundation package — every other package depends on it. It defines the block builders, flow model, type system, and item/event taxonomy used across the framework. +This is the foundation package. Every other package depends on it. It's isomorphic — runs in Node, the browser, edge runtimes, anywhere JavaScript runs. -## What This Package Is For - -Use `@flow-state-dev/core` to: -- Define blocks (`handler`, `generator`, `sequencer`, `router`) -- Define flows (`defineFlow`) -- Define resources and projections (`defineResource`, `defineProjection`) -- Import shared types and item definitions - -This package is **isomorphic** — no platform-specific code (Node, browser, etc.). - -## Quick Start +## What you can build ```ts -import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; +import { defineFlow, generator, handler, sequencer, router } from "@flow-state-dev/core"; import { z } from "zod"; +``` -// Define a generator block -const chatGen = generator({ - name: "chat", +**A generator that calls an LLM with tools, history, and streaming:** + +```ts +const agent = generator({ + name: "agent", model: "gpt-5-mini", prompt: "You are a helpful assistant.", inputSchema: z.object({ message: z.string() }), + history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, + tools: [readDoc, writeDoc], + emit: { reasoning: true, messages: true }, }); +``` + +**A handler that validates and transforms:** -// Define a handler block +```ts const counter = handler({ name: "counter", - inputSchema: z.string(), - outputSchema: z.string(), sessionStateSchema: z.object({ count: z.number().default(0) }), execute: async (input, ctx) => { - await ctx.session.patchState({ count: (ctx.session.state.count ?? 0) + 1 }); + await ctx.session.incState({ count: 1 }); return input; }, }); +``` -// Compose into a pipeline -const pipeline = sequencer({ name: "chat-pipeline", inputSchema: z.object({ message: z.string() }) }) - .then(chatGen) - .then(counter); +**A sequencer that composes them into a pipeline with error recovery:** -// Define the flow -const flow = defineFlow({ - kind: "my-chat", +```ts +const pipeline = sequencer({ name: "chat-pipeline", inputSchema }) + .then(analyzeInput) + .thenIf((result) => result.needsContext, enrichWithContext) + .then(agent) + .then(counter) + .rescue([{ when: [ModelError], block: fallback }]); +``` + +**A router that dispatches to different pipelines at runtime:** + +```ts +const dispatch = router({ + name: "mode-router", + routes: [chatPipeline, planPipeline, reviewPipeline], + execute: (input, ctx) => { + const mode = ctx.session.state.mode; + if (mode === "plan") return planPipeline; + if (mode === "review") return reviewPipeline; + return chatPipeline; + }, +}); +``` + +**A flow that ties it all together:** + +```ts +export default defineFlow({ + kind: "my-app", requireUser: true, actions: { chat: { inputSchema: z.object({ message: z.string() }), - block: pipeline, + block: dispatch, userMessage: (input) => input.message, }, }, session: { - stateSchema: z.object({ count: z.number().default(0) }), + stateSchema: z.object({ mode: z.string().default("chat"), count: z.number().default(0) }), + resources: { artifacts: { stateSchema: artifactSchema, writable: true } }, + projections: { + artifactsList: { + client: true, + compute: (ctx) => /* derive list from resource state */, + }, + }, }, -}); - -export default flow({ id: "default" }); +})({ id: "default" }); ``` ## Exports ### Main (`@flow-state-dev/core`) -**Block Builders:** -- `handler(config)` — Synchronous logic block -- `generator(config)` — LLM call with tool loop -- `sequencer(config)` — Fluent composition DSL -- `router(config)` — Runtime block selection +**Block builders:** +- `handler(config)` — Synchronous/async logic block +- `generator(config)` — LLM call with framework-managed tool loop, streaming, and structured output repair +- `sequencer(config)` — Fluent composition DSL (14 methods: `then`, `thenIf`, `parallel`, `forEach`, `doUntil`, `doWhile`, `map`, `tap`, `tapIf`, `rescue`, `branch`, `work`, `waitForWork`, `loopBack`) +- `router(config)` — Runtime block selection from declared routes **Flow:** -- `defineFlow(definition)` — Create a flow type +- `defineFlow(definition)` — Create a flow type with actions, scopes, resources, and projections -**Resources & Projections:** +**Resources and projections:** - `defineResource(config)` — Portable resource definition - `defineProjection(config)` — Portable projection definition -- `resource(uri, opts?)` — Resource slot reference for generators -- `projection(uri, opts?)` — Projection slot reference -- `projectionText(uri, opts?)` — Text projection reference -- `projectionData(uri, opts?)` — Data projection reference -- `projectionMessages(uri, opts?)` — Message projection reference +- `resource(uri)` — Resource slot reference for generators +- `projection(uri)` — Projection slot reference +- `projectionText(uri)` — Text projection for LLM context +- `projectionData(uri)` — Structured data projection +- `projectionMessages(uri)` — Message-pair projection -**Type Helpers:** +**Type helpers:** - `StateOf` — Extract state type from schema or resource - `ContextOf` — Get context handle type for scope/resource - `ResourceContext` — Resource context type @@ -95,27 +121,36 @@ export default flow({ id: "default" }); ### Types (`@flow-state-dev/core/types`) -Block, flow, resource, scope, streaming, and model type definitions. Use this subpath for type-only imports in client/react code. +Block, flow, resource, scope, streaming, and model type definitions. Use this subpath for type-only imports. ### Items (`@flow-state-dev/core/items`) -Canonical output item unions, content types, and stream event helpers. Use this subpath for item-related type imports. +Output item unions, content types, and stream event helpers. Item types: `message`, `reasoning`, `component`, `context`, `status`, `state_change`, `resource_change`, `block_output`, `error`, `step_error`. + +## Key design decisions + +**Partial state schemas.** Each block declares only the state fields it touches. A counter block doesn't need to know about a preferences block's state. This keeps blocks reusable and self-documenting about their dependencies. + +**Silent by default.** Blocks emit nothing to the client unless they explicitly call `ctx.emitMessage()`, `ctx.emitComponent()`, or `ctx.emitStatus()`. Generators are the exception — they auto-emit messages and reasoning. This gives you precise control over what the user sees. + +**Projections as data policy.** Projections are the *only* way to expose data to clients. Internal state, resources, and intermediate values stay server-side unless you deliberately project them. Security by architecture, not by convention. ## Dependencies -- `zod` ^3.24.1 — Schema validation +- `zod` ^3.24.1 ## Scripts -- `pnpm --filter @flow-state-dev/core build` -- `pnpm --filter @flow-state-dev/core typecheck` -- `pnpm --filter @flow-state-dev/core test` +```bash +pnpm --filter @flow-state-dev/core build +pnpm --filter @flow-state-dev/core typecheck +pnpm --filter @flow-state-dev/core test +``` -## Architecture Reference +## Architecture reference -See `docs/architecture/` for detailed documentation: -- [Blocks](../../docs/architecture/blocks.md) -- [Flows and Actions](../../docs/architecture/flows-and-actions.md) -- [Sequencer DSL](../../docs/architecture/sequencer-dsl.md) -- [State and Scopes](../../docs/architecture/state-and-scopes.md) -- [Resources and Projections](../../docs/architecture/resources-and-projections.md) +- [Blocks](../../docs/architecture/blocks.md) — Deep dive into all four block kinds +- [Flows and Actions](../../docs/architecture/flows-and-actions.md) — defineFlow, actions, lifecycle hooks +- [Sequencer DSL](../../docs/architecture/sequencer-dsl.md) — Full method reference for the composition DSL +- [State and Scopes](../../docs/architecture/state-and-scopes.md) — Scoped state, atomic operations, CAS +- [Resources and Projections](../../docs/architecture/resources-and-projections.md) — Data containers and derived views diff --git a/packages/react/README.md b/packages/react/README.md index 5b746e7366..fef0b62b92 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -1,175 +1,165 @@ # @flow-state-dev/react -React bindings for Flow State Dev. - -`@flow-state-dev/react` is a UI-layer package: -- wraps `@flow-state-dev/client` transport APIs with React hooks -- provides renderer/context helpers for `fsd:block_output` items -- keeps transport logic out of React components - -## Install - -```bash -pnpm add @flow-state-dev/react -``` - -Peer dependency: `react ^18.0.0 || ^19.0.0` - -## Quick Start +**React hooks and renderers for Flow State Dev. Wire AI workflows to your UI in minutes.** ```tsx -import { - FlowProvider, - ItemRenderer, - useFlow, - useProjections, - useSession, -} from "@flow-state-dev/react"; +import { FlowProvider, useFlow, useSession, ItemRenderer } from "@flow-state-dev/react"; function App() { return ( - - + + ); } -function AgentUI() { +function Chat() { const flow = useFlow({ autoCreateSession: true }); - const session = useSession(flow.activeSessionId, { - items: { visibility: "ui" }, - }); - - const projections = useProjections(session, { - session: ["artifactsList", "planStatus"], - }); + const session = useSession(flow.activeSessionId); return (
+ {session.items.map(item => ( + + ))} - -
{JSON.stringify(projections.session?.planStatus, null, 2)}
- - {session.items.map((item) => ( - - ))}
); } ``` +That's a streaming chat UI. Items appear in real time as the LLM generates them. State syncs automatically. Reconnection is handled. No SSE wiring, no manual refetches. + +## Install + +```bash +pnpm add @flow-state-dev/react +``` + +Peer dependency: `react ^18.0.0 || ^19.0.0` + +## How it works + +`@flow-state-dev/react` wraps the [`@flow-state-dev/client`](../client) transport layer with React hooks. All network communication goes through the client — no transport logic lives in this package. This means: + +- Hooks manage lifecycle and reactivity, not HTTP or SSE +- You can swap transport behavior by configuring the client +- The same flow definitions work across React, vanilla JS, and Node + ## FlowProvider -Use `` to set defaults and register renderers. +Wrap your app (or a subtree) with `` to set defaults and register custom renderers: + +```tsx + + + +``` Props: -- `flowKind?: string` -- `sessionId?: string` -- `userId?: string` -- `baseUrl?: string` -- `renderers?: RendererRegistry` — custom renderers keyed by item type (or by component key for `component`/`container` types) +- `flowKind?: string` — Default flow kind for child hooks +- `sessionId?: string` — Default session ID +- `userId?: string` — Required for Phase 1 +- `baseUrl?: string` — API base URL +- `renderers?: RendererRegistry` — Custom renderers keyed by item type or component key - `children: ReactNode` -Nested providers merge `renderers` (child keys override parent keys). +Nested providers merge `renderers` — child keys override parent keys. ## Hooks ### `useFlow(options?)` -Session lifecycle helper (list/create/select sessions). +Session lifecycle — list, create, and select sessions: + +```ts +const flow = useFlow({ autoCreateSession: true }); +// flow.activeSessionId, flow.sessions, flow.createSession(), flow.selectSession() +``` ### `useSession(sessionId, options?)` -Primary session hook. `flowKind` defaults to `useFlowContext().flowKind` and can be overridden via options. +The primary hook. Gives you everything about a session — items, state, streaming status, and the ability to send actions: ```ts const session = useSession(sessionId, { - items: true, + items: { visibility: "ui", includeTransient: false }, }); ``` -`items` options: -- `true` (default) -- `false` -- `{ visibility?: ItemVisibility; includeTransient?: boolean }` - -Return shape: -- `detail` (`SessionDetail | null`) -- `snapshot` (`SessionStateSnapshotResponse | null`) -- `items`, `messages`, `blockOutputs`, `functionCalls` -- `isLoading`, `isStreaming`, `error` -- `sendAction(action, input)` -- `refresh()` +Returns: +- `detail` — Session metadata +- `snapshot` — Current state snapshot with projections +- `items`, `messages`, `blockOutputs`, `functionCalls` — Filtered item views +- `isLoading`, `isStreaming`, `error` — Status flags +- `sendAction(action, input)` — Trigger an action +- `refresh()` — Manually refetch ### `useProjections(session, options)` -Reads scope-grouped projection values from `session.snapshot`. +Read typed projection values from the session snapshot: ```ts const projections = useProjections(session, { - session: ["artifactsList"], - user: ["topics"], + session: ["artifactsList", "modeStatus"], + user: ["preferences"], project: ["sharedConfig"], }); -``` - -Typed mode: -```ts +// Or with schemas for runtime validation: const projections = useProjections(session, { - session: { - artifactsList: artifactsListSchema, - }, + session: { artifactsList: artifactsListSchema }, }); ``` ### `useAction(options)` -Low-level action execution hook for direct action calls. +Low-level hook for direct action execution without session management. ### `useRequestStream(options)` -Low-level request-stream hook with reactive item/status views. - -## Render Helpers +Low-level hook for subscribing to a request's SSE stream with reactive item/status views. -- `ItemRenderer` — renders a single output item (registry → built-in fallback → JSON dev) -- `ItemsRenderer` — renders a list of output items in the order provided +## Render helpers -All custom renderers receive `{ item }` as their prop. Type the item to the -kind you expect: +`ItemRenderer` and `ItemsRenderer` handle the dispatch from item types to your registered renderers: ```tsx -import type { MessageItem } from "@flow-state-dev/core/items"; +// Single item + -function ChatMessage({ item }: { item: MessageItem }) { - return

{item.role}: {item.content[0]?.text}

; -} - -const renderers: RendererRegistry = { message: ChatMessage }; +// List of items + ``` -Pass `false` to suppress a type (overrides built-in fallbacks): +Custom renderers receive `{ item }` as their prop: ```tsx -const renderers: RendererRegistry = { status: false }; -``` +import type { MessageItem } from "@flow-state-dev/core/items"; -## Architecture Reference +function ChatBubble({ item }: { item: MessageItem }) { + return ( +
+ {item.content[0]?.text} +
+ ); +} +``` -- [Server and Client](../../docs/architecture/server-and-client.md) — React hooks contract, FlowProvider, rendering -- [Streaming](../../docs/architecture/streaming.md) — item types, content model, transience +Register renderers via `FlowProvider` or pass them directly to `ItemRenderer`. ## Scripts @@ -178,3 +168,8 @@ pnpm --filter @flow-state-dev/react build pnpm --filter @flow-state-dev/react typecheck pnpm --filter @flow-state-dev/react test ``` + +## Architecture reference + +- [Server and Client](../../docs/architecture/server-and-client.md) — React hooks contract, FlowProvider, rendering +- [Streaming](../../docs/architecture/streaming.md) — Item types, content model, transience diff --git a/packages/server/README.md b/packages/server/README.md index 595cf731ba..a8e29036a2 100644 --- a/packages/server/README.md +++ b/packages/server/README.md @@ -1,62 +1,13 @@ # @flow-state-dev/server -Server runtime for Flow State Dev. - -This package owns: -- action execution orchestration -- in-memory and filesystem store adapters -- request streaming and replay utilities -- flow registry and canonical route adapters -- runtime error normalization - -## What This Package Is For - -Use `@flow-state-dev/server` inside framework-integrated server environments to: -- register flows -- execute actions -- expose canonical `/api/flows` routes -- persist and query state across request/session/user/project scopes - -## Public API Areas - -Context/runtime: -- `createExecutionContext` -- `runAction` -- `executeBlock` -- `DEFAULT_RUNTIME_LOGGER`, `summarizeForLog` (structured execution logging helpers) - -Stores: -- `createInMemoryStores` -- `createFilesystemStores` -- scope store factories and CAS/state ops - -Streaming: -- `createResponseEmitter` -- `encodeStreamEvent` -- `serializeSSEFrame` -- `replayRequestEvents` - -Registry/routes: -- `createFlowRegistry` -- `createFlowApiRouter` -- `parseFlowRoute` - -Errors: -- `FlowError` and canonical subclasses -- `normalizeError` - -## Quick Start - -### Next.js Catch-All Route +**The runtime. Register flows, execute actions, stream results — three lines to a complete API.** ```ts -// app/api/flows/[...path]/route.ts import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; -import myFlow from "@/flows/my-flow/flow"; +import myFlow from "./flows/my-flow"; const registry = createFlowRegistry(); registry.register(myFlow); - const router = createFlowApiRouter({ registry }); export const GET = router.GET; @@ -64,70 +15,104 @@ export const POST = router.POST; export const DELETE = router.DELETE; ``` -### Custom Model Resolution +That's a full API with action execution, session management, SSE streaming with resume, and state snapshots. Drop it into a Next.js catch-all route and you're done. -```ts -import { createFlowApiRouter, createAiSdkModelResolver } from "@flow-state-dev/server"; +## What this package does -const router = createFlowApiRouter({ - registry, - modelResolver: createAiSdkModelResolver((modelId) => myModels.resolve(modelId)), -}); -``` +- **Action execution** — Validates input, resolves sessions, runs block pipelines, emits items +- **SSE streaming** — Items stream live as blocks execute, with sequence-number cursors for resume +- **State persistence** — In-memory and filesystem store adapters with CAS-guarded atomic writes +- **Flow registry** — Register multiple flows, routes are derived automatically +- **Error normalization** — All errors become typed `FlowError` instances with codes, retry signals, and scope context +- **Structured logging** — Every action execution logs flow/action/block IDs, attempt numbers, timing, and summarized payloads -### Store Configuration +## Store configuration ```ts -import { createFlowApiRouter, createFilesystemStores, createInMemoryStores } from "@flow-state-dev/server"; +import { createFilesystemStores, createInMemoryStores } from "@flow-state-dev/server"; -// Production: filesystem (default) +// Default: filesystem persistence const router = createFlowApiRouter({ registry }); -// Testing: in-memory +// Testing: in-memory (fast, no cleanup) const router = createFlowApiRouter({ registry, stores: createInMemoryStores() }); ``` +## Custom model resolution -## Runtime Logs +```ts +import { createFlowApiRouter, createAiSdkModelResolver } from "@flow-state-dev/server"; -`runAction` and `executeBlock` emit structured logs by default (flow/action/block IDs, attempt numbers, summarized input/output payloads, retries, and terminal errors). +const router = createFlowApiRouter({ + registry, + modelResolver: createAiSdkModelResolver((modelId) => myModels.resolve(modelId)), +}); +``` + +## Custom logging -Pass `logger` in `runAction(...)` or `executeBlock(...)` to route logs to your preferred sink: +`runAction` and `executeBlock` emit structured logs by default — flow/action/block IDs, attempt numbers, summarized payloads, retries, and terminal errors. ```ts await runAction({ flow, - actionName: "reply", + actionName: "chat", input, userId: "user_123", stores, logger: { - info: (message, context) => appLogger.info({ ...context }, message), - warn: (message, context) => appLogger.warn({ ...context }, message), - error: (message, context) => appLogger.error({ ...context }, message) - } + info: (msg, ctx) => appLogger.info({ ...ctx }, msg), + warn: (msg, ctx) => appLogger.warn({ ...ctx }, msg), + error: (msg, ctx) => appLogger.error({ ...ctx }, msg), + }, }); ``` -Use `summarizeForLog(value)` when you need the same bounded payload summaries in custom observers/middleware. +Use `summarizeForLog(value)` for the same bounded payload summaries in custom middleware. -## Scripts +## Public API + +**Runtime:** +- `createExecutionContext` — Build a block execution context +- `runAction` — Execute a flow action end-to-end +- `executeBlock` — Execute a single block with context + +**Stores:** +- `createInMemoryStores` — Fast, ephemeral stores for testing +- `createFilesystemStores` — Persistent stores for development and production +- Scope store factories and CAS/state ops -- `pnpm --filter @flow-state-dev/server build` -- `pnpm --filter @flow-state-dev/server typecheck` -- `pnpm --filter @flow-state-dev/server test` +**Streaming:** +- `createResponseEmitter` — Create an SSE emitter for a request +- `encodeStreamEvent` / `serializeSSEFrame` — Low-level SSE encoding +- `replayRequestEvents` — Replay events from a sequence cursor + +**Registry/routes:** +- `createFlowRegistry` — Register flow instances +- `createFlowApiRouter` — Generate HTTP route handlers from a registry +- `parseFlowRoute` — Parse incoming request paths + +**Errors:** +- `FlowError` and canonical subclasses +- `normalizeError` — Wrap any thrown value into a typed FlowError ## Notes -- Phase 1 requires caller-provided `userId` for action/session routes. -- Request stream replay supports `Last-Event-ID` and `starting_after`. -- User stream remains capability-gated and disabled in current Phase 1 implementation. -- Generator blocks resolve models through `ctx.resolveModel`. -- By default, server runtime uses a built-in Vercel AI Gateway resolver (`AI_GATEWAY_API_KEY` or Vercel OIDC). -- `createAiSdkModelResolver` and `createDefaultModelResolver` are available when you need explicit model routing behavior. +- Phase 1 requires caller-provided `userId` for all action/session routes +- Stream resume supports both `Last-Event-ID` header and `starting_after` query param +- Generator blocks resolve models through `ctx.resolveModel` — default uses Vercel AI Gateway +- `createAiSdkModelResolver` and `createDefaultModelResolver` available for explicit model routing + +## Scripts + +```bash +pnpm --filter @flow-state-dev/server build +pnpm --filter @flow-state-dev/server typecheck +pnpm --filter @flow-state-dev/server test +``` -## Architecture Reference +## Architecture reference -- [Server and Client](../../docs/architecture/server-and-client.md) — routes, transport, React hooks contract -- [Execution and Errors](../../docs/architecture/execution-and-errors.md) — retry, rescue, work queue -- [Streaming](../../docs/architecture/streaming.md) — item/content model, SSE protocol, resume +- [Server and Client](../../docs/architecture/server-and-client.md) — Routes, transport, React hooks contract +- [Execution and Errors](../../docs/architecture/execution-and-errors.md) — Retry, rescue, work queue +- [Streaming](../../docs/architecture/streaming.md) — Item/content model, SSE protocol, resume semantics From e055f5bfead2fea063d09d649e18d832a21f128c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 00:27:29 +0000 Subject: [PATCH 02/15] Rewrite Docusaurus docs site to be compelling and developer-focused MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs site read like technical specs — accurate but uninspiring. This rewrites 13 files across the entire site to lead with narrative, show real code first, and make the framework's power immediately tangible. Landing page (index.tsx + CSS): - New hero: "Stop wiring. Start building." with a clear value prop - Rewritten feature cards with punchy titles and practical descriptions - Replaced single code preview with 4-step code showcase (Define, Serve, Render, Test) showing the full developer experience - Added CTA section at bottom - Gradient hero background, step numbers, responsive styles Config & intro: - New tagline: "Composable AI workflows for TypeScript. Blocks in. Streaming out." - Intro page opens with the problem, shows a complete code example, then walks through what you get and why each piece matters Concept pages (blocks, flows, actions, state, streaming, testing): - Every page now opens with a "why this matters" hook instead of jumping straight to definitions - Blocks page explains what the framework manages for each kind - Streaming page leads with "most frameworks bolt streaming on as an afterthought" contrast - Testing page opens with "LLMs aren't deterministic. But your tests should be." - State page opens with the real problem (state is messy in AI apps) Guides: - Quick start adds conversation history to the example and explains what the framework handles at each step - Building a chat app guide adds projections, better test examples, and explains the "why" alongside the "how" Blog: - Welcome post rewritten from placeholder to a real "Introducing Flow State Dev" announcement with the core idea, what's different, and current status Verified: `pnpm --filter docs build` passes cleanly. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- apps/docs/blog/2026-02-26-welcome.md | 43 +++- apps/docs/docs/concepts/actions.md | 80 ++++--- apps/docs/docs/concepts/blocks.md | 118 +++++----- apps/docs/docs/concepts/flows.md | 80 ++++--- apps/docs/docs/concepts/state.md | 106 +++++---- apps/docs/docs/concepts/streaming.md | 83 ++++--- apps/docs/docs/concepts/testing.md | 63 ++++-- apps/docs/docs/getting-started/quick-start.md | 91 ++++---- apps/docs/docs/guides/building-a-chat-app.md | 102 ++++++--- apps/docs/docs/intro.md | 107 ++++++--- apps/docs/docusaurus.config.ts | 2 +- apps/docs/src/pages/index.module.css | 80 ++++++- apps/docs/src/pages/index.tsx | 209 +++++++++++++----- 13 files changed, 783 insertions(+), 381 deletions(-) diff --git a/apps/docs/blog/2026-02-26-welcome.md b/apps/docs/blog/2026-02-26-welcome.md index e3abd4e404..6cf37dcd2b 100644 --- a/apps/docs/blog/2026-02-26-welcome.md +++ b/apps/docs/blog/2026-02-26-welcome.md @@ -1,14 +1,49 @@ --- slug: welcome -title: Welcome to Flow State Dev +title: "Introducing Flow State Dev: AI Workflows Without the Plumbing" authors: [flowstatedev] tags: [announcement] --- -Flow State Dev is a block-based AI workflow framework for TypeScript. +We've been building AI features for a while now. And every time, we end up writing the same infrastructure: orchestrate LLM calls, wire up SSE streaming, manage conversation state, handle retries, sync everything to the frontend. It's tedious. It's error-prone. And it has nothing to do with what the AI actually does. + +Flow State Dev is our answer: a TypeScript framework that makes orchestration, streaming, state, and error handling **composable primitives** instead of application glue. -We're building a framework that makes AI workflow concerns — orchestration, retries, streaming, state, and UI rendering — first-class primitives so teams can ship faster with less runtime drift. +## The core idea + +Four block types — **handler**, **generator**, **sequencer**, **router** — compose into any AI workflow. The framework handles execution, streaming, state persistence, retries, and client rendering. + +```ts +const pipeline = sequencer({ name: "chat-pipeline" }) + .then(analyzeInput) + .thenIf((result) => result.needsContext, enrichWithContext) + .then(agentGenerator) + .then(trackUsage) + .rescue([{ when: [ModelError], block: fallback }]); +``` + +That pipeline analyzes input, conditionally enriches it, calls an LLM with tool access, tracks usage, and recovers from model errors. Every step streams results to the client in real time over SSE with automatic resume on disconnect. + +## What's different + +**You compose primitives, not configure a framework.** Most AI frameworks give you an opinionated agent architecture and ask you to fill in the blanks. Flow State Dev gives you four building blocks and a composition DSL. You decide what your AI does. The framework handles how it runs. + +**Streaming is structural, not bolted on.** Items (messages, tool calls, state changes, custom components) stream as blocks execute, with sequence-number cursors for replay. This isn't an afterthought — it's the core delivery mechanism. + +**State is scoped and typed.** Four isolation levels (request, session, user, project) with atomic operations and CAS concurrency. Each block declares only the state it needs. Projections are the only way to expose data to clients — security by architecture. + +**One type system, server to screen.** Zod schemas defined once, validated at runtime, inferred at compile time. From block definitions through the client SDK to React hooks. No glue code. + +## Where we are + +Phase 1 (Foundation) is largely complete: core contracts, block builders, server runtime with stores and streaming, client transport, React hooks and renderers, and a testing package with deterministic generator mocks. Two canonical examples — [hello-chat](https://github.com/flow-state-dev/flow-state-dev) and [kitchen-sink](https://github.com/flow-state-dev/flow-state-dev) — demonstrate the full stack. + +CLI and devtool are in active development. + +## What's next + +We're focused on developer experience polish, cross-package validation, and getting the documentation site to a point where you can go from zero to a running AI app without friction. -Stay tuned for updates as we progress through our roadmap. +If you're building AI features in TypeScript and tired of reinventing the same infrastructure, [give it a try](/docs/getting-started/quick-start). diff --git a/apps/docs/docs/concepts/actions.md b/apps/docs/docs/concepts/actions.md index fc6eaf7f99..00bfdf3a02 100644 --- a/apps/docs/docs/concepts/actions.md +++ b/apps/docs/docs/concepts/actions.md @@ -4,11 +4,11 @@ sidebar_position: 3 # Actions -Actions are the entry points into a flow. When a client wants to do something — send a message, reset state, trigger processing — it invokes an action. +Actions are how the outside world talks to your flow. When a client sends a message, resets state, or triggers any processing — it invokes an action. Actions are the flow's public API: named entry points with validated input and a block to execute. -## Defining Actions +## Defining actions -Actions are defined inside `defineFlow`: +Actions live inside `defineFlow`: ```ts const myFlow = defineFlow({ @@ -23,28 +23,32 @@ const myFlow = defineFlow({ inputSchema: z.object({}), block: resetHandler, }, + saveArtifact: { + inputSchema: artifactInputSchema, + block: updateArtifact, + }, }, }); ``` Each action has: -- **`inputSchema`** — Zod schema for validating action input -- **`block`** — The block (or pipeline) to execute -- **`userMessage`** (optional) — Extracts a user message string from the input, emitted as a `message` item before block execution +- **`inputSchema`** — Zod schema that validates every incoming request. Invalid input is rejected before any block runs. +- **`block`** — The block (or pipeline) to execute. This is where the work happens. +- **`userMessage`** (optional) — Extracts a display string from the input. The framework emits it as a user-role `message` item before execution begins, so the conversation history shows what the user said. -## Invoking Actions +## Invoking actions -### From the client +### From the client SDK ```ts import { createClient } from "@flow-state-dev/client"; -const client = createClient({ flowKind: "my-app", userId: "devuser" }); +const client = createClient({ flowKind: "my-app", userId: "user_1" }); -// Dynamic action name +// New session (auto-created) await client.sendAction("chat", { message: "Hello!" }); -// With an existing session +// Existing session await client.sendAction("chat", { message: "Hello!" }, { sessionId: "sess_123" }); ``` @@ -52,14 +56,10 @@ await client.sendAction("chat", { message: "Hello!" }, { sessionId: "sess_123" } ```tsx const session = useSession(sessionId); - -// Primary pattern — via useSession await session.sendAction("chat", { message: "Hello!" }); ``` -### HTTP API - -Actions are exposed at: +### Over HTTP ``` POST /api/flows/:kind/actions/:action # New session @@ -72,41 +72,39 @@ The server returns `202 Accepted` immediately with a `requestId`. Execution happ GET /api/flows/:kind/requests/:requestId/stream ``` -## Execution Flow +## How an action executes ``` Client Server - │ │ - ├─ POST /actions/chat ──────►│ - │ { input, userId } ├─ validate input - │ ├─ resolve/create session - │◄── 202 { requestId } ──────┤ - │ ├─ execute block (async) - ├─ GET /requests/:id/stream ►│ - │◄── SSE events ─────────────┤ item.added, content.delta, ... - │◄── request.completed ──────┤ - │ │ + | | + |-- POST /actions/chat ------>| + | { input, userId } |-- validate input + | |-- resolve/create session + |<-- 202 { requestId } ------| + | |-- execute block (async) + |-- GET /requests/:id/stream->| + |<-- SSE events --------------| item.added, content.delta, ... + |<-- request.completed -------| + | | ``` -## Action Lifecycle - -1. **Validate** — Input is checked against `inputSchema` -2. **Session** — Resolved from `sessionId` or created new -3. **User message** — `userMessage(input)` emitted if defined -4. **Execute** — Block runs asynchronously -5. **Complete or Error** — Lifecycle hooks fire, stream closes +Step by step: +1. **Validate** — Input is checked against `inputSchema`. Bad input returns 400. +2. **Session** — Resolved from `sessionId` or created new. +3. **User message** — If `userMessage` is defined, a user-role message item is emitted to the stream. +4. **Execute** — The root block runs asynchronously. Items stream to the client as they're produced. +5. **Complete** — Lifecycle hooks fire. The stream emits `request.completed` (or `request.errored`). -## Typed Actions +## Typed actions -For compile-time type safety, use `createTypedClient`: +For compile-time type safety, use `createTypedClient` — it generates action methods from your flow definition: ```ts import { createTypedClient } from "@flow-state-dev/client"; -const client = createTypedClient({ flow: myFlow, userId: "devuser" }); +const client = createTypedClient({ flow: myFlow, userId: "user_1" }); -// Type-safe action methods -await client.actions.chat({ message: "Hello!" }); -// TypeScript error: Property 'invalid' does not exist -await client.actions.invalid({ message: "Hello!" }); +await client.actions.chat({ message: "Hello!" }); // Type-checked +await client.actions.reset({}); // Type-checked +await client.actions.invalid({ message: "Hello!" }); // TypeScript error ``` diff --git a/apps/docs/docs/concepts/blocks.md b/apps/docs/docs/concepts/blocks.md index ead1fc13d8..411a04f8ec 100644 --- a/apps/docs/docs/concepts/blocks.md +++ b/apps/docs/docs/concepts/blocks.md @@ -4,13 +4,15 @@ sidebar_position: 1 # Blocks -Blocks are the runtime units of Flow State Dev. Every piece of work — calling an LLM, validating input, transforming data, choosing a path — is a block. +Everything in Flow State Dev is a block. Every LLM call, every data transform, every branching decision, every multi-step pipeline — it's all composed from four block kinds. No more, no less. -## Four Block Kinds +This constraint is the point. Four primitives that compose freely means you can build any AI workflow without inventing new abstractions. -### Handler +## The four kinds -Synchronous logic blocks for validation, state updates, and transformations. +### Handler — pure logic + +Handlers do the work that isn't AI: validate input, transform data, update state, implement tool logic. They take input, run `execute`, and return output. ```ts import { handler } from "@flow-state-dev/core"; @@ -22,40 +24,43 @@ const counter = handler({ outputSchema: z.string(), sessionStateSchema: z.object({ count: z.number().default(0) }), execute: async (input, ctx) => { - await ctx.session.patchState({ count: (ctx.session.state.count ?? 0) + 1 }); + await ctx.session.incState({ count: 1 }); return input; }, }); ``` -### Generator +Handlers are **silent by default** — they don't emit anything to the client unless you explicitly call `ctx.emitMessage()` or `ctx.emitComponent()`. This gives you precise control over what the user sees. + +### Generator — the AI block -LLM-calling blocks with tool loops, structured output, and streaming. +Generators call LLMs. But unlike a raw API call, the framework manages everything around it: prompt assembly, conversation history, tool execution loops, streaming, structured output with schema repair. ```ts import { generator } from "@flow-state-dev/core"; import { z } from "zod"; -const chatGen = generator({ - name: "chat", +const agent = generator({ + name: "agent", model: "gpt-5-mini", prompt: "You are a helpful assistant.", inputSchema: z.object({ message: z.string() }), - outputSchema: z.object({ response: z.string() }), + history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, - tools: [searchTool, calculatorTool], + tools: [searchTool, createArtifactTool], + emit: { reasoning: true, messages: true }, }); ``` -Generators handle: -- Prompt assembly (system, context, history, user messages) -- Tool execution loops (call tools, feed results back, repeat) -- Structured output with schema repair -- Streaming content deltas to the client +What the framework handles for you: +- **Prompt assembly** from four slots: system prompt, context entries, conversation history, and user message +- **Tool execution loops** — tools are handler blocks, auto-compiled to provider-native format +- **Streaming** — content deltas flow to the client as they're generated +- **Structured output repair** — if the LLM returns invalid JSON, the framework can auto-retry or route to a rescue block -### Sequencer +### Sequencer — the composition engine -Pipeline composition using a fluent DSL for chaining, branching, parallelism, and error recovery. +Sequencers compose blocks into pipelines using a fluent DSL. Each step's output feeds into the next step's input. ```ts import { sequencer } from "@flow-state-dev/core"; @@ -64,73 +69,82 @@ const pipeline = sequencer({ name: "chat-pipeline", inputSchema: z.object({ message: z.string() }), }) - .then(validateBlock) - .then(chatGen) + .then(analyzeInput) + .thenIf((result) => result.needsContext, enrichWithContext) + .then(agent) .tap(analyticsBlock) .rescue([ - { when: [NetworkError], block: retryBlock }, + { when: [NetworkError], block: retryWithBackup }, + { when: [ModelError], block: fallbackModel }, + { block: genericRecovery }, ]); ``` -See [Sequencer Patterns](/docs/guides/sequencer-patterns) for composition recipes. +The DSL has 14 methods: `then`, `thenIf`, `parallel`, `forEach`, `doUntil`, `doWhile`, `map`, `tap`, `tapIf`, `rescue`, `branch`, `work`, `waitForWork`, `loopBack`. See [Sequencer Patterns](/docs/guides/sequencer-patterns) for recipes. -### Router +### Router — runtime dispatch -Runtime block selection based on input or state. +Routers inspect input or state and pick which block (or pipeline) to run next. Routes are declared statically so the framework can validate them, but selection happens at runtime. ```ts import { router } from "@flow-state-dev/core"; const modeRouter = router({ name: "mode-router", - inputSchema: z.object({ message: z.string(), mode: z.string() }), - routes: { - chat: chatPipeline, - agent: agentPipeline, - search: searchPipeline, - }, - execute: async (input, ctx) => { - return input.mode; // returns the route key + inputSchema, + outputSchema: z.string(), + sessionStateSchema: z.object({ mode: modeSchema }), + routes: [chatPipeline, planPipeline, reviewPipeline], + execute: (input, ctx) => { + const mode = ctx.session.state.mode; + if (mode === "plan") return planPipeline; + if (mode === "review") return reviewPipeline; + return chatPipeline; }, }); ``` -## Block Context +## The block context -Every block receives a `BlockContext` with access to scopes and framework services: +Every block's `execute` function receives a context object with access to scoped state, resources, and framework services: ```ts execute: async (input, ctx) => { - // Scope access - ctx.session.state; // Read session state - await ctx.session.patchState({...}); // Update state + // Read and write scoped state + const mode = ctx.session.state.mode; + await ctx.session.patchState({ mode: "agent" }); + + // Access resources + const plan = ctx.session.resources.get("plan"); + await ctx.session.resources.plan.patchState({ status: "active" }); - // Resources - ctx.session.resources.plan.state; // Read resource - await ctx.session.resources.plan.patchState({...}); + // Emit items to the client + await ctx.emitMessage("Processing your request..."); + await ctx.emitComponent("progress-bar", { percent: 50 }); - // Framework services - ctx.resolveModel(modelId); // Resolve AI model - ctx.emit(item); // Emit stream item + // Resolve AI models + const model = ctx.resolveModel("gpt-5-mini"); } ``` -## Blocks Are Composable +## Blocks are composable -Any block can be used wherever a block is expected. A sequencer is a block. A router is a block. This means you can nest them freely: +A sequencer is a block. A router is a block. This means you can nest them freely — a sequencer can contain routers, a router can dispatch to sequencers, sequencers can nest inside sequencers: ```ts -const innerPipeline = sequencer({ name: "inner", ... }) +const innerPipeline = sequencer({ name: "inner" }) .then(blockA) .then(blockB); -const outerPipeline = sequencer({ name: "outer", ... }) - .then(innerPipeline) // Sequencer inside sequencer +const outerPipeline = sequencer({ name: "outer" }) + .then(innerPipeline) // Sequencer inside sequencer + .then(modeRouter) // Router inside sequencer .then(blockC); ``` -## Key Rules +## Key rules -- **Execute via `block.run()`** — Never call `block.config.execute` directly. The framework manages validation, retry, and lifecycle through `block.run()`. -- **Schemas define the contract** — `inputSchema` and `outputSchema` are validated at runtime. Trust the types. -- **Names must be unique** — Each block within a flow needs a unique `name` for provenance tracking and debugging. +- **Always use `block.run()`** — never call `block.config.execute` directly. The framework manages validation, retry, lifecycle, and streaming through `block.run()`. +- **Schemas are contracts** — `inputSchema` and `outputSchema` are validated at runtime. TypeScript catches mismatches at compile time. +- **Names must be unique** — within a flow, each block needs a unique `name` for provenance tracking and debugging. +- **Partial state schemas** — each block declares only the state fields it touches, not the full flow-level schema. This keeps blocks reusable. diff --git a/apps/docs/docs/concepts/flows.md b/apps/docs/docs/concepts/flows.md index ffbbae3236..65e348ccfc 100644 --- a/apps/docs/docs/concepts/flows.md +++ b/apps/docs/docs/concepts/flows.md @@ -4,17 +4,19 @@ sidebar_position: 2 # Flows -A **flow** is the top-level unit in Flow State Dev. It declares what actions are available, what state is managed, and how blocks execute. +A flow is the top-level unit — the thing you register with the server and clients connect to. It ties together your blocks, actions, state, resources, and projections into a single, deployable definition. -## Defining a Flow +Think of a flow as the complete specification of an AI-powered feature: what actions users can trigger, what state is tracked, and what data is exposed to the frontend. + +## Defining a flow ```ts -import { defineFlow, sequencer, generator } from "@flow-state-dev/core"; +import { defineFlow } from "@flow-state-dev/core"; import { z } from "zod"; const chatFlow = defineFlow({ - kind: "my-chat", // Unique identifier - requireUser: true, // Require userId on requests + kind: "my-chat", // Unique identifier — becomes the URL path + requireUser: true, // Require userId on every request actions: { chat: { @@ -22,35 +24,54 @@ const chatFlow = defineFlow({ block: chatPipeline, userMessage: (input) => input.message, }, + reset: { + inputSchema: z.object({}), + block: resetHandler, + }, }, session: { stateSchema: z.object({ messageCount: z.number().default(0), }), + resources: { + artifacts: { stateSchema: artifactSchema, writable: true }, + }, + projections: { + messageCount: { + client: true, + compute: (ctx) => ctx.session.state.messageCount ?? 0, + }, + }, + }, + + user: { + stateSchema: z.object({ + preferences: z.object({ theme: z.string() }).default({}), + }), }, }); export default chatFlow({ id: "default" }); ``` -## Flow Type vs Flow Instance +## FlowType vs FlowInstance -`defineFlow()` returns a **FlowType** — a factory function. Calling it with `{ id }` creates a **FlowInstance**: +`defineFlow()` returns a **FlowType** — a factory. Calling it with `{ id }` creates a **FlowInstance** — the thing you actually register with the server: ```ts -// FlowType — the factory +// FlowType — the blueprint const chatFlow = defineFlow({ kind: "my-chat", ... }); -// FlowInstance — what you register with the server +// FlowInstance — what you register and deploy export default chatFlow({ id: "default" }); ``` -This separation lets you create multiple instances of the same flow type with different configurations. +This separation lets you create multiple instances of the same flow type with different configurations if needed. -## Actions +## Actions — the flow's public API -Actions are the entry points into a flow. Each action defines its input schema, the block to execute, and optional lifecycle hooks. +Each action is an entry point that maps a name to an input schema and a root block. Clients call actions by name — that's the only way to trigger execution. ```ts actions: { @@ -59,11 +80,10 @@ actions: { block: chatPipeline, userMessage: (input) => input.message, - // Lifecycle hooks - onCompleted: async (result, ctx) => { /* ... */ }, - onErrored: async (error, ctx) => { /* ... */ }, + // Lifecycle hooks — observe, don't control + onCompleted: async (result, ctx) => { /* succeeded */ }, + onErrored: async (error, ctx) => { /* failed */ }, }, - reset: { inputSchema: z.object({}), block: resetHandler, @@ -71,16 +91,18 @@ actions: { }, ``` -When an action is executed: +When an action executes: 1. Input is validated against `inputSchema` 2. Session is resolved or created -3. `userMessage` is emitted as a user message item (if defined) -4. The block executes asynchronously +3. `userMessage(input)` emits a user message item (if defined) +4. The root block executes asynchronously 5. Lifecycle hooks fire on completion or error -## Session Configuration +See [Actions](/docs/concepts/actions) for the full picture. -Flows declare session-level state, resources, and projections: +## Session configuration + +Sessions carry state, resources, and projections that persist across requests in a conversation: ```ts session: { @@ -110,12 +132,12 @@ session: { See [State](/docs/concepts/state) for details on scopes, resources, and projections. -## Lifecycle Hooks +## Lifecycle hooks -Both actions and requests support lifecycle hooks: +Observe execution at both the action and request level: ```ts -// Action-level hooks +// Action-level actions: { chat: { onCompleted: async (result, ctx) => { /* action succeeded */ }, @@ -123,17 +145,19 @@ actions: { }, }, -// Request-level hooks +// Request-level request: { onStarted: async (ctx) => { /* request began */ }, onCompleted: async (ctx) => { /* request succeeded */ }, onErrored: async (error, ctx) => { /* request failed */ }, - onFinished: async (ctx) => { /* always fires */ }, + onFinished: async (ctx) => { /* always fires, success or failure */ }, onStepErrored: async (error, ctx) => { /* non-terminal step failure */ }, }, ``` -## Flow Registration +Hooks are **observational** — they run after the fact and can't modify the result. The past-tense naming (`onCompleted`, not `onComplete`) makes this intent clear. + +## Registration Flows are registered with a server registry to be served via HTTP: @@ -147,4 +171,4 @@ registry.register(agentFlow); const router = createFlowApiRouter({ registry }); ``` -The registry discovers flows by `kind` and routes requests to the right flow instance. +The registry discovers flows by `kind` and routes requests automatically. Multiple flows can coexist in the same server. diff --git a/apps/docs/docs/concepts/state.md b/apps/docs/docs/concepts/state.md index 50ee942634..3902181ffd 100644 --- a/apps/docs/docs/concepts/state.md +++ b/apps/docs/docs/concepts/state.md @@ -4,43 +4,43 @@ sidebar_position: 4 # State Management -Flow State Dev provides structured state management across four scope levels with typed operations, resources, and projections. +State in AI applications is messy. Conversation history, user preferences, shared configuration, intermediate processing data — all at different lifetimes, all needing different isolation guarantees. Flow State Dev gives you four scoped levels with typed operations, resources for structured data, and projections to control exactly what the client can see. ## Scopes State is organized into four hierarchical scopes: -| Scope | Lifetime | Use For | +| Scope | Lifetime | Example | |-------|----------|---------| -| **Request** | Single action execution | Temporary processing data | -| **Session** | Across requests in a conversation | Chat history, current mode, plan state | -| **User** | Across sessions for a user | Preferences, accumulated knowledge | +| **Request** | Single action execution | Temporary processing data, intermediate results | +| **Session** | Across requests in a conversation | Chat history, current mode, plan state, counters | +| **User** | Across sessions for a user | Preferences, accumulated knowledge, model choices | | **Project** | Across users in a project | Shared configuration, global data | -Each scope has its own state, resources, and projections. +Each scope has its own state, resources, and projections. Most of your state lives at the session level. -## State Operations +## State operations -State is managed through scope handles in `BlockContext`: +Every scope provides the same set of atomic operations via the block context: ```ts execute: async (input, ctx) => { - // Read state + // Read state — always available, always typed const mode = ctx.session.state.mode; - // Patch state (merge fields) + // Patch — merge fields into existing state await ctx.session.patchState({ mode: "agent" }); - // Replace state entirely + // Replace — overwrite the entire state await ctx.session.setState({ mode: "chat", count: 0 }); - // Increment numeric fields + // Increment — atomic numeric increment await ctx.session.incState({ messageCount: 1 }); - // Push to array fields + // Push — append to array fields await ctx.session.pushState({ history: newEntry }); - // Functional update + // Functional update — read-modify-write with CAS safety await ctx.session.updateState((current) => ({ ...current, processedAt: Date.now(), @@ -48,11 +48,11 @@ execute: async (input, ctx) => { } ``` -All state operations use **CAS (Compare-and-Swap)** semantics — concurrent updates are retried automatically to prevent lost writes. +All operations use **CAS (Compare-and-Swap)** semantics — if two blocks try to update the same state concurrently, one will automatically retry. No lost writes. -## Defining State Schemas +## Defining state schemas -State schemas are declared in the flow definition: +State schemas are declared at the flow level: ```ts const myFlow = defineFlow({ @@ -67,23 +67,40 @@ const myFlow = defineFlow({ stateSchema: z.object({ preferences: z.object({ theme: z.enum(["light", "dark"]).default("dark"), + preferredModel: z.string().default("gpt-5-mini"), }).default({}), }), }, }); ``` +**Partial schemas** are the key pattern: each block declares only the state fields it needs, not the full flow-level schema. A counter block that only touches `messageCount` doesn't need to know about `mode`: + +```ts +const counter = handler({ + name: "counter", + sessionStateSchema: z.object({ messageCount: z.number().default(0) }), + execute: async (input, ctx) => { + // ctx.session.state is typed as { messageCount: number } + await ctx.session.incState({ messageCount: 1 }); + return input; + }, +}); +``` + +This keeps blocks reusable and self-documenting about their dependencies. + ## Resources -Resources are named, schema-typed data containers attached to a scope. They're ideal for structured data that needs independent lifecycle from the main state: +Resources are named, schema-typed data containers attached to a scope. Use them for structured data that needs its own lifecycle — artifacts, plans, documents, collections: ```ts session: { resources: { - plan: { + artifacts: { stateSchema: z.object({ - steps: z.array(z.string()).default([]), - status: z.enum(["draft", "active", "complete"]).default("draft"), + byId: z.record(z.object({ title: z.string(), content: z.string() })).default({}), + order: z.array(z.string()).default([]), }), writable: true, }, @@ -91,51 +108,66 @@ session: { } ``` -Access resources through scope handles: +Access resources through scope handles — they have the same atomic operations as state: ```ts -const plan = ctx.session.resources.plan; -const steps = plan.state.steps; +const artifacts = ctx.session.resources.get("artifacts"); +const titles = artifacts.state.order.map(id => artifacts.state.byId[id]?.title); -await plan.patchState({ status: "active" }); +await artifacts.patchState({ + byId: { "doc-1": { title: "Design Doc", content: "..." } }, + order: [...artifacts.state.order, "doc-1"], +}); ``` ## Projections -Projections are derived views computed from state and resources. They're the **only way** to expose values to the client: +Projections are derived views computed from state and resources. They're the **only way** to expose data to clients: ```ts session: { projections: { - activePlan: { - client: true, // Visible to the client - compute: (ctx) => ctx.session.resources.plan?.state ?? null, + artifactsList: { + client: true, // Visible to the frontend + compute: (ctx) => { + const artifacts = ctx.session.resources.get("artifacts")?.state; + return artifacts?.order.map(id => ({ + id, + title: artifacts.byId[id]?.title ?? "Untitled", + })) ?? []; + }, + }, + messageCount: { + client: true, + compute: (ctx) => ctx.session.state.messageCount ?? 0, }, - messageCount: (ctx) => ctx.session.state.messageCount ?? 0, }, } ``` -On the client side, read projections via `useProjections`: +On the client, read projections via `useProjections`: ```tsx const projections = useProjections(session, { - session: ["activePlan", "messageCount"], + session: ["artifactsList", "messageCount"], + user: ["preferences"], }); -// projections.session.activePlan → { steps: [...], status: "active" } +// projections.session?.artifactsList → [{ id: "doc-1", title: "Design Doc" }] ``` -## Client Visibility +## Why projections matter -The client reads state through projections, not raw state. The state snapshot endpoint returns projections grouped by scope: +Raw state never reaches the client. The state snapshot endpoint returns projections grouped by scope: ```json { "projections": { - "session": { "activePlan": [...], "messageCount": 5 }, + "session": { "artifactsList": [...], "messageCount": 5 }, "user": { "preferences": { "theme": "dark" } } } } ``` -During streaming, `state_change` and `resource_change` events signal that projections may be stale — the client refetches on `request.completed`. +This is a deliberate architectural choice. Internal state — intermediate processing data, raw resource contents, block-specific fields — stays on the server. You decide exactly what the client sees by writing `compute` functions. Security by architecture, not by convention. + +During streaming, `state_change` and `resource_change` events signal that projections may be stale — the client refetches the authoritative snapshot on `request.completed`. diff --git a/apps/docs/docs/concepts/streaming.md b/apps/docs/docs/concepts/streaming.md index 746f2bda6e..5e51d83669 100644 --- a/apps/docs/docs/concepts/streaming.md +++ b/apps/docs/docs/concepts/streaming.md @@ -4,22 +4,22 @@ sidebar_position: 5 # Streaming -Flow State Dev uses an **item-first streaming model** over Server-Sent Events (SSE). Instead of streaming raw text, the framework streams structured items — messages, tool calls, state changes, components — that clients render as they arrive. +Most frameworks bolt streaming on as an afterthought — raw text over a WebSocket, maybe some SSE. Flow State Dev makes streaming structural. Instead of raw text, the framework streams **typed items**: messages, tool calls, state changes, reasoning, custom components. Each item has a lifecycle and a sequence number, so clients can disconnect and resume without losing a single event. -## How Streaming Works +## How it works -When an action executes, the server creates a request stream. The client connects to it via SSE: +When a client invokes an action, the server starts executing blocks and streaming results immediately: ``` -POST /api/flows/:kind/actions/:action → 202 { requestId } -GET /api/flows/:kind/requests/:requestId/stream → SSE events +POST /api/flows/:kind/actions/:action --> 202 { requestId } +GET /api/flows/:kind/requests/:requestId/stream --> SSE events ``` -Events flow in real-time as blocks execute: +Events flow in real time as blocks execute: ``` event: item.added -data: { "item": { "type": "message", "role": "assistant", ... } } +data: { "item": { "type": "message", "role": "assistant", "status": "in_progress" } } event: content.delta data: { "itemId": "msg_1", "delta": { "text": "Hello" } } @@ -27,30 +27,37 @@ data: { "itemId": "msg_1", "delta": { "text": "Hello" } } event: content.delta data: { "itemId": "msg_1", "delta": { "text": " there!" } } +event: item.updated +data: { "item": { "type": "message", "role": "assistant", "status": "completed" } } + event: request.status data: { "status": "completed" } ``` -## Item Types +The client assembles content progressively from deltas. Text appears token by token. When the request completes, the client refetches the state snapshot for the authoritative final state. + +## Item types + +Every streamed event is a typed item. This means the client always knows what it's rendering: -| Type | What It Is | +| Type | What it is | |------|-----------| | `message` | Chat message (user or assistant) with content parts | -| `reasoning` | Model reasoning/thinking (often hidden from end users) | +| `reasoning` | Model reasoning/thinking tokens | | `block_output` | Structured output from any block | -| `component` | Custom UI component with props | -| `container` | Groups child items for UI layout | +| `component` | Custom UI component with typed props | +| `container` | Groups child items for visual layout | | `tool_call` | Tool invocation with arguments | | `tool_result` | Tool execution result | | `state_change` | State mutation notification | | `resource_change` | Resource mutation notification | | `step_error` | Non-terminal error in a pipeline step | | `error` | Terminal request error | -| `status` | Request lifecycle status | +| `status` | Transient progress updates | -## Content Model +## Content model -Message and reasoning items have a **content array** of typed parts: +Message and reasoning items have a **content array** with typed parts: ```ts { @@ -63,45 +70,55 @@ Message and reasoning items have a **content array** of typed parts: } ``` -Content is streamed via `content.delta` events — the client assembles the full content progressively. +Content is assembled progressively from `content.delta` events — the framework handles buffering and assembly so you don't have to. -## Resume and Replay +## Resume and replay -Every stream event has a **sequence number**. Clients can resume from where they left off: +This is where Flow State Dev's streaming really shines. Every event has a **sequence number**. When a client disconnects — network blip, tab backgrounded, mobile app suspended — it can resume from exactly where it left off: ``` GET /api/flows/:kind/requests/:requestId/stream Last-Event-ID: 42 ``` -The server replays all events after sequence 42, then switches to live streaming. This makes reconnection seamless — no lost data. +The server replays all events after sequence 42, then switches to live streaming. No data loss. No duplicate events. No application-level retry logic needed. + +You can also use the `starting_after` query parameter: + +``` +GET /api/flows/:kind/requests/:requestId/stream?starting_after=42 +``` -## Item Visibility +## Item visibility -Items have a `visibility` field: +Not all items are for the user. Items have a `visibility` field that controls who sees them: -| Visibility | Meaning | -|------------|---------| -| `ui` | Shown to the user in the UI | -| `internal` | Available in stream but not rendered by default | +| Visibility | Who sees it | +|------------|------------| +| `ui` | Rendered in the user-facing UI | +| `internal` | Available in the stream but not rendered by default | | `devtool` | Only visible in developer tools | -Transient items (like in-progress content) are replaced by their final versions when the block completes. +Generators also contribute items to the LLM context via `session.items.llm()` — the framework automatically filters to items the LLM should see (messages, tool results) and excludes UI-only items (status, components). -## React Integration +## React integration -On the React side, streaming is automatic through hooks: +On the React side, streaming is automatic. The `useSession` hook connects to the SSE stream, processes events, and updates items reactively: ```tsx const session = useSession(sessionId); -// session.items — all items from the current session -// session.isStreaming — true while a request is active -// session.messages — filtered to message items only - +// Items update in real time as the stream delivers them {session.items.map((item) => ( ))} + +// Filtered views +{session.messages.map(...)} // Only message items +{session.blockOutputs.map(...)} // Only block outputs + +// Status +{session.isStreaming && } ``` -The `useSession` hook connects to the SSE stream, processes events, and updates items reactively. No manual stream management needed. +No manual stream management. No event listeners. No reconnection logic. The hooks handle all of it. diff --git a/apps/docs/docs/concepts/testing.md b/apps/docs/docs/concepts/testing.md index c0d6098997..cd92dd07a4 100644 --- a/apps/docs/docs/concepts/testing.md +++ b/apps/docs/docs/concepts/testing.md @@ -4,11 +4,11 @@ sidebar_position: 6 # Testing -Flow State Dev includes a dedicated testing package with deterministic test harnesses for blocks, flows, and generators. +LLMs aren't deterministic. But your tests should be. Flow State Dev ships a dedicated testing package that lets you write fully deterministic tests for blocks, pipelines, and complete flows — no real LLM calls, no network, no flaky tests. -## Test Harnesses +## Test harnesses -### Testing a Block +### Testing a block ```ts import { handler } from "@flow-state-dev/core"; @@ -31,7 +31,7 @@ expect(result.output).toEqual({ counted: true }); expect(result.session.state.count).toBe(1); ``` -### Testing a Flow +### Testing a flow end-to-end ```ts import { testFlow } from "@flow-state-dev/testing"; @@ -50,9 +50,10 @@ const result = await testFlow({ expect(result.items).toContainEqual( expect.objectContaining({ type: "message" }) ); +expect(result.session.state.messageCount).toBe(1); ``` -### Testing a Sequencer +### Testing a sequencer ```ts import { testSequencer } from "@flow-state-dev/testing"; @@ -66,36 +67,53 @@ const result = await testSequencer(pipeline, { }); ``` -## Mocking Generators +## Mocking generators -Generators call LLMs, which aren't deterministic. The testing package provides scripted mocks: +The testing package replaces real LLM calls with scripted responses. You control exactly what the generator returns: ```ts import { mockGenerator } from "@flow-state-dev/testing"; +// Simple: just the output const mock = mockGenerator({ name: "chat-gen", output: { response: "Mocked response" }, +}); + +// With items: control what gets emitted to the stream +const mock = mockGenerator({ + name: "chat-gen", + output: "Mocked response", items: [ { type: "message", role: "assistant", content: [{ type: "text", text: "Mocked response" }] }, ], }); + +// Scripted sequence: different responses for successive calls +const mock = mockGenerator({ + name: "chat-gen", + script: [ + { text: "First response" }, + { text: "Second response" }, + ], +}); ``` -In test harnesses, mock generators by name: +In test harnesses, pass mocks by generator name: ```ts -const result = await testBlock(myBlock, { +const result = await testBlock(myPipeline, { input: { message: "hello" }, generators: { - "chat-gen": { output: { response: "Mocked!" } }, + "chat-gen": { output: "Mocked!" }, + "summary-gen": { output: "Brief summary." }, }, }); ``` -## Seeding State +## Seeding state and resources -All test harnesses support seeding scope state and resources: +All test harnesses support seeding scoped state and resources to set up the scenario you want to test: ```ts const result = await testFlow({ @@ -105,7 +123,7 @@ const result = await testFlow({ userId: "testuser", seed: { session: { - state: { mode: "agent" }, + state: { mode: "agent", messageCount: 5 }, resources: { plan: { steps: ["step1"], status: "active" }, }, @@ -114,27 +132,30 @@ const result = await testFlow({ state: { preferredModel: "gpt-4o-mini" }, }, }, + generators: { + "agent-gen": { output: "Done!" }, + }, }); ``` -## Item Assertions +## Item assertions -Use `testItems` for assertions on emitted items: +Use `testItems` for expressive assertions on emitted items: ```ts import { testItems } from "@flow-state-dev/testing"; const items = testItems(result.items); -// Check item types expect(items.messages()).toHaveLength(2); expect(items.blockOutputs()).toHaveLength(1); expect(items.ofType("tool_call")).toHaveLength(3); +expect(items.ofType("state_change")).not.toHaveLength(0); ``` -## Key Principles +## What makes this different -- **Deterministic** — Generator mocks ensure reproducible tests -- **Isolated** — Each test harness creates an isolated runtime context with in-memory stores -- **Framework-contract focused** — Test harnesses validate the same contracts the runtime enforces -- **No network required** — Everything runs in-process with mocked LLM responses +- **Deterministic** — Generator mocks produce the same output every time. No flaky tests from LLM variance. +- **Isolated** — Each test harness creates a fresh runtime context with in-memory stores. No shared state between tests. +- **Full-contract testing** — Test harnesses enforce the same validation, lifecycle, and execution contracts as the production runtime. If it passes in tests, it'll behave the same way in production. +- **No network** — Everything runs in-process. No HTTP servers, no SSE connections, no external dependencies. diff --git a/apps/docs/docs/getting-started/quick-start.md b/apps/docs/docs/getting-started/quick-start.md index 6ca0b9015e..82260a38b2 100644 --- a/apps/docs/docs/getting-started/quick-start.md +++ b/apps/docs/docs/getting-started/quick-start.md @@ -4,69 +4,80 @@ sidebar_position: 1 # Quick Start -Build your first flow in 5 minutes. This guide walks you through defining a simple chat flow, setting up the server, and connecting a React frontend. +Build a streaming chat app in 5 minutes. By the end, you'll have an LLM-powered chat with conversation history, session state, and a React UI — all type-safe, all streaming. ## Prerequisites - Node.js >= 18 (Node 20+ recommended) - pnpm (or npm/yarn) -## 1. Install Packages +## 1. Install packages ```bash pnpm add @flow-state-dev/core @flow-state-dev/server @flow-state-dev/client @flow-state-dev/react zod ``` -## 2. Define a Flow +## 2. Define your flow -Create a file for your flow definition: +This is where you describe what your AI does. A generator calls the LLM. A handler tracks state. A sequencer wires them together. `defineFlow` makes it deployable. ```ts title="src/flows/hello-chat/flow.ts" -import { defineFlow, generator, sequencer } from "@flow-state-dev/core"; +import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; import { z } from "zod"; -// Define a generator block for LLM interaction +const inputSchema = z.object({ message: z.string() }); + +// Generator: calls the LLM with conversation history const chatGen = generator({ name: "chat", model: "gpt-5-mini", prompt: "You are a helpful assistant.", - inputSchema: z.object({ message: z.string() }), + inputSchema, + history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, }); -// Create a pipeline -const pipeline = sequencer({ - name: "chat-pipeline", - inputSchema: z.object({ message: z.string() }), -}).then(chatGen); +// Handler: increments a message counter after each exchange +const counter = handler({ + name: "counter", + inputSchema: z.string(), + outputSchema: z.string(), + sessionStateSchema: z.object({ messageCount: z.number().default(0) }), + execute: async (input, ctx) => { + await ctx.session.incState({ messageCount: 1 }); + return input; + }, +}); -// Define and export the flow +// Pipeline: generator → counter +const pipeline = sequencer({ name: "chat-pipeline", inputSchema }) + .then(chatGen) + .then(counter); + +// Flow definition const chatFlow = defineFlow({ kind: "hello-chat", + requireUser: true, actions: { chat: { - inputSchema: z.object({ message: z.string() }), + inputSchema, block: pipeline, userMessage: (input) => input.message, }, }, session: { - stateSchema: z.object({}), + stateSchema: z.object({ messageCount: z.number().default(0) }), }, }); export default chatFlow({ id: "default" }); ``` -**What's happening here:** -- `generator` creates an LLM-calling block with a prompt and input schema -- `sequencer` chains blocks into a pipeline -- `defineFlow` declares the flow with its actions and session config -- The final `chatFlow({ id: "default" })` creates a flow instance +**What's happening:** The generator handles the LLM call — prompt assembly, streaming, conversation history. The handler is a pure function that bumps a counter. The sequencer pipes the generator's output into the handler. `defineFlow` wraps it all with actions, session state, and lifecycle management. -## 3. Set Up the Server +## 3. Set up the server -Create an API route that registers your flow and handles requests: +One catch-all route gives you a complete API with SSE streaming: ```ts title="app/api/flows/[...path]/route.ts" import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; @@ -82,9 +93,11 @@ export const POST = router.POST; export const DELETE = router.DELETE; ``` -This gives you a full REST API with SSE streaming at `/api/flows/`. +That's it. You now have action execution, session management, SSE streaming with resume, and state snapshots at `/api/flows/`. + +## 4. Connect the React frontend -## 4. Connect the React Frontend +The hooks handle streaming, reconnection, and state sync. You just render: ```tsx title="src/app/page.tsx" import { FlowProvider, ItemRenderer, useFlow, useSession } from "@flow-state-dev/react"; @@ -117,7 +130,7 @@ function ChatUI() { > @@ -125,27 +138,25 @@ function ChatUI() { } ``` -**What's happening here:** -- `FlowProvider` sets up the flow context with `flowKind` and `userId` -- `useFlow` manages session lifecycle (creates one automatically) -- `useSession` provides items, streaming status, and `sendAction` -- `ItemRenderer` renders each streamed item using registered renderers +**What's happening:** `FlowProvider` sets up the flow context. `useFlow` creates a session automatically. `useSession` gives you live-updating items, streaming status, and `sendAction`. `ItemRenderer` renders each streamed item. The framework handles SSE connection, reconnection, and state sync behind the scenes. -## 5. Run It +## 5. Run it ```bash pnpm dev ``` -Open your browser and start chatting. The framework handles: -- Action dispatch and validation -- SSE streaming with automatic reconnection -- Session state persistence +Open your browser and start chatting. The framework is handling: +- Input validation against your Zod schema +- Action dispatch and async block execution +- SSE streaming with automatic reconnection and resume +- Session state persistence across requests +- Conversation history assembly for the LLM - Item rendering in the UI -## Next Steps +## Next steps -- [Installation](/docs/getting-started/installation) — Package options and configuration -- [Project Structure](/docs/getting-started/project-structure) — How to organize your flow project -- [Concepts: Blocks](/docs/concepts/blocks) — Deep dive into the four block kinds -- [Guide: Building a Chat App](/docs/guides/building-a-chat-app) — Complete walkthrough with state, tools, and UI +- **[Installation](/docs/getting-started/installation)** — Package options, peer dependencies, TypeScript config +- **[Project Structure](/docs/getting-started/project-structure)** — How to organize flows, blocks, and tools +- **[Blocks](/docs/concepts/blocks)** — Deep dive into handler, generator, sequencer, and router +- **[Building a Chat App](/docs/guides/building-a-chat-app)** — Full walkthrough with state, projections, tools, and tests diff --git a/apps/docs/docs/guides/building-a-chat-app.md b/apps/docs/docs/guides/building-a-chat-app.md index 247b0ef728..3695b61493 100644 --- a/apps/docs/docs/guides/building-a-chat-app.md +++ b/apps/docs/docs/guides/building-a-chat-app.md @@ -4,19 +4,20 @@ sidebar_position: 1 # Building a Chat App -This guide walks you through building a complete chat application with Flow State Dev — from flow definition to React UI. +This guide walks you through building a complete chat application — from blocks to React UI to deterministic tests. Along the way, you'll see how conversation history, session state, projections, and streaming fit together. -## What We're Building +## What we're building -A chat app with: -- LLM-powered responses via a generator block -- Message counting via a handler block -- Session state persistence -- Streaming responses in a React UI +A chat app where: +- An LLM generates responses via a generator block +- A handler tracks message count in session state +- A projection exposes the count to the React UI +- Items stream to the frontend in real time +- Tests run deterministically with mocked generators -## 1. Define the Blocks +## 1. Define the blocks -### Generator Block +### The generator — talks to the LLM ```ts title="src/flows/hello-chat/blocks/chat-gen.ts" import { generator } from "@flow-state-dev/core"; @@ -27,11 +28,14 @@ export const chatGen = generator({ model: "gpt-5-mini", prompt: "You are a helpful assistant. Be concise and friendly.", inputSchema: z.object({ message: z.string() }), + history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, }); ``` -### Counter Handler +The `history` slot loads prior conversation from persisted request items. `session.items.llm()` returns completed messages in `{role, content}` format — the framework handles filtering and formatting. The `user` slot extracts the current message from input. + +### The handler — tracks usage ```ts title="src/flows/hello-chat/blocks/counter.ts" import { handler } from "@flow-state-dev/core"; @@ -49,7 +53,9 @@ export const counter = handler({ }); ``` -## 2. Compose the Pipeline +Notice the **partial state schema** — this handler only declares `messageCount`. It doesn't need to know about any other session state fields. `incState` is an atomic increment — safe even under concurrent requests. + +## 2. Compose the pipeline and flow ```ts title="src/flows/hello-chat/flow.ts" import { defineFlow, sequencer } from "@flow-state-dev/core"; @@ -57,10 +63,9 @@ import { z } from "zod"; import { chatGen } from "./blocks/chat-gen"; import { counter } from "./blocks/counter"; -const pipeline = sequencer({ - name: "chat-pipeline", - inputSchema: z.object({ message: z.string() }), -}) +const inputSchema = z.object({ message: z.string() }); + +const pipeline = sequencer({ name: "chat-pipeline", inputSchema }) .then(chatGen) .then(counter); @@ -70,7 +75,7 @@ const chatFlow = defineFlow({ actions: { chat: { - inputSchema: z.object({ message: z.string() }), + inputSchema, block: pipeline, userMessage: (input) => input.message, }, @@ -93,12 +98,12 @@ const chatFlow = defineFlow({ export default chatFlow({ id: "default" }); ``` -**What this does:** -- The sequencer chains `chatGen` → `counter`, so every chat message gets an LLM response and increments the count -- `userMessage: (input) => input.message` emits the user's input as a visible message item -- The `messageCount` projection exposes the count to the React UI +Key details: +- The sequencer chains `chatGen` then `counter` — every message gets an LLM response and increments the count +- `userMessage: (input) => input.message` tells the framework to emit a user-role message item before execution, so the conversation stream shows what the user said +- The `messageCount` projection exposes the count to the React UI — this is the *only* way the client sees this value -## 3. Set Up the Server +## 3. Set up the server ```ts title="app/api/flows/[...path]/route.ts" import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; @@ -114,6 +119,8 @@ export const POST = router.POST; export const DELETE = router.DELETE; ``` +Three lines of setup. You now have action execution, session management, SSE streaming, and state snapshots. + ## 4. Build the React UI ```tsx title="src/components/ChatApp.tsx" @@ -157,7 +164,7 @@ function ChatUI() {

Chat

- Messages: {projections.session?.messageCount ?? 0} + {projections.session?.messageCount ?? 0} messages
@@ -173,7 +180,7 @@ function ChatUI() { autoComplete="off" />
@@ -181,13 +188,20 @@ function ChatUI() { } ``` -## 5. Test It +What each hook does: +- `useFlow({ autoCreateSession: true })` — creates a session on mount, tracks the active session ID +- `useSession(id, { items: { visibility: "ui" } })` — connects to the SSE stream, delivers items in real time, provides `sendAction` and `isStreaming` +- `useProjections(session, { session: ["messageCount"] })` — reads the `messageCount` projection from the latest state snapshot + +## 5. Write tests + +No real LLM calls. No network. Deterministic results: ```ts title="src/flows/hello-chat/__tests__/flow.test.ts" import { testFlow } from "@flow-state-dev/testing"; import chatFlow from "../flow"; -test("chat action increments message count", async () => { +test("chat action streams a response and increments count", async () => { const result = await testFlow({ flow: chatFlow, action: "chat", @@ -198,15 +212,43 @@ test("chat action increments message count", async () => { }, }); - expect(result.session.state.messageCount).toBe(1); + // User message was emitted expect(result.items).toContainEqual( expect.objectContaining({ type: "message", role: "user" }) ); + + // Assistant message was emitted + expect(result.items).toContainEqual( + expect.objectContaining({ type: "message", role: "assistant" }) + ); + + // State was updated + expect(result.session.state.messageCount).toBe(1); +}); + +test("message count accumulates across requests", async () => { + const result = await testFlow({ + flow: chatFlow, + action: "chat", + input: { message: "Second message" }, + userId: "testuser", + seed: { + session: { state: { messageCount: 3 } }, + }, + generators: { + chat: { output: "Response" }, + }, + }); + + expect(result.session.state.messageCount).toBe(4); }); ``` -## Next Steps +The test harness creates an isolated runtime with in-memory stores, mocks the generator, and executes the full action pipeline — validation, session resolution, block execution, state persistence, lifecycle hooks. Same contracts as production. + +## Next steps -- Add [custom renderers](/docs/guides/react-integration) for message styling -- Add tools to the generator for [function calling](/docs/concepts/blocks#generator) -- Use [sequencer patterns](/docs/guides/sequencer-patterns) for branching and error recovery +- Add **[custom renderers](/docs/guides/react-integration)** to style messages, reasoning, and components +- Add **tools** to the generator for [function calling](/docs/concepts/blocks#generator--the-ai-block) (search, create artifacts, etc.) +- Use **[sequencer patterns](/docs/guides/sequencer-patterns)** for conditional logic, parallelism, and error recovery +- Add **resources and projections** for richer state — see the [kitchen-sink example](https://github.com/flow-state-dev/flow-state-dev) for a full demonstration diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.md index f219f75699..11af5b247f 100644 --- a/apps/docs/docs/intro.md +++ b/apps/docs/docs/intro.md @@ -3,45 +3,92 @@ sidebar_position: 1 slug: /intro --- -# Introduction +# Why Flow State Dev? -Flow State Dev is a block-based AI workflow framework for TypeScript. It gives you typed building blocks for AI interactions, composable pipelines, resumable streaming, and scoped state management — all with one type system from server to UI. +Every AI feature needs the same infrastructure: call an LLM, stream the response, manage state across turns, handle errors gracefully, sync everything to the UI. Teams rebuild this from scratch every time — ad-hoc orchestration, hand-rolled SSE, application-specific retry logic, state scattered across closures and databases. -## Why Flow State Dev? +Flow State Dev makes these concerns **framework primitives**. You write the logic that matters. The framework handles everything else. -Building AI features typically means stitching together orchestration, retries, streaming, state, and UI rendering in application-specific ways. Flow State Dev makes these concerns first-class framework primitives: +## What it looks like -- **Typed blocks** — Define handlers, generators, sequencers, and routers with input/output schemas that are validated at runtime and inferred at compile time. -- **Composable flows** — Chain blocks into pipelines with branching, parallelism, error recovery, and background work using a fluent DSL. -- **Resumable streaming** — Item-first SSE streaming with sequence-number replay. Clients reconnect mid-stream without losing data. -- **Scoped state** — Four scope levels (request, session, user, project) with typed state operations, resources, and projections. -- **Full-stack TypeScript** — One type system across server execution, client transport, and React UI. Schemas defined once, validated everywhere. +```ts +import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; -## How It Works +const chat = generator({ + name: "chat", + model: "gpt-5-mini", + prompt: "You are a helpful assistant.", + history: (_input, ctx) => ctx.session.items.llm(), + user: (input) => input.message, + tools: [searchDocs, createArtifact], +}); -A **flow** is the top-level unit. It declares **actions** (entry points) that execute **blocks** (the runtime units). Blocks come in four kinds: +const pipeline = sequencer({ name: "pipeline" }) + .then(chat) + .then(trackUsage) + .rescue([{ when: [ModelError], block: fallback }]); -| Block | Purpose | -|-------|---------| -| **Handler** | Synchronous logic — validation, state updates, transformations | -| **Generator** | LLM calls with tool loops, structured output, and streaming | -| **Sequencer** | Pipeline composition — chaining, branching, parallelism | -| **Router** | Runtime block selection based on input or state | +export default defineFlow({ + kind: "my-app", + actions: { chat: { block: pipeline, userMessage: (i) => i.message } }, + session: { stateSchema, resources, projections }, +})({ id: "default" }); +``` -Blocks compose into pipelines via the **sequencer DSL**. Pipelines execute on the **server**, stream results to the **client** via SSE, and render in **React** through hooks and renderers. +That gives you: streaming over SSE with resume, conversation history, tool loops, atomic state operations, typed projections to the client, error recovery, and lifecycle hooks. From that one definition. -## Package Overview +## What you get -| Package | Purpose | -|---------|---------| -| `@flow-state-dev/core` | Block builders, flow definitions, type contracts | -| `@flow-state-dev/server` | Action runtime, stores, SSE streaming | -| `@flow-state-dev/client` | HTTP/SSE transport client (no React dependency) | -| `@flow-state-dev/react` | React hooks, renderers, context providers | -| `@flow-state-dev/testing` | Test harnesses for blocks, flows, generators | +### Four block primitives -## Next Steps +Every piece of logic — calling an LLM, validating input, choosing a path, composing a pipeline — is one of exactly four block kinds: -- [Quick Start](/docs/getting-started/quick-start) — Build your first flow in 5 minutes -- [Concepts](/docs/concepts/blocks) — Understand the core abstractions -- [Guides](/docs/guides/building-a-chat-app) — Build a complete chat application +| Block | What it does | When to reach for it | +|-------|-------------|---------------------| +| **Handler** | Pure logic: validate, transform, mutate state | Data processing, state updates, tool implementations | +| **Generator** | LLM calls with managed tool loops and streaming | Chat, extraction, any AI generation | +| **Sequencer** | Compose blocks into pipelines | Multi-step workflows with branching, parallelism, error recovery | +| **Router** | Dispatch to different pipelines at runtime | Mode switching, intent routing, conditional flows | + +All blocks share the same contract: `block.run(input, ctx)`. Any block composes with any other block. + +### Resumable streaming + +Items stream over SSE as blocks execute — messages, reasoning, tool calls, state changes, custom components. Every event has a sequence number. Disconnect mid-response? Reconnect with a cursor and pick up exactly where you left off. No data loss. No duplicates. No manual SSE plumbing. + +### Scoped state that scales + +Four isolation levels with atomic operations: + +| Scope | Lifetime | Example | +|-------|----------|---------| +| **Request** | Single action execution | Temporary processing data | +| **Session** | Across requests in a conversation | Chat history, mode, counters | +| **User** | Across sessions for a user | Preferences, accumulated knowledge | +| **Project** | Shared across users | Configuration, global data | + +Each block declares only the state fields it needs via partial schemas. A counter block doesn't need to know about a preferences block's state. + +### Resources and projections + +**Resources** are typed data containers — think artifacts, plans, documents — scoped to sessions, users, or projects. **Projections** are derived views computed from state and resources, and the *only* way to expose data to clients. You can't accidentally leak internal state because projections are the sole data gateway. + +### Full-stack type safety + +Define a Zod schema once. It validates at runtime, infers at compile time, and flows from server blocks through the client SDK to React hooks. One type system. Zero glue code. No code generation step. + +## The full stack + +| Package | What it does | +|---------|-------------| +| [`@flow-state-dev/core`](/docs/api/core) | Block builders, flow definitions, type contracts | +| [`@flow-state-dev/server`](/docs/api/server) | Execution runtime, stores, SSE streaming, HTTP routes | +| [`@flow-state-dev/client`](/docs/api/client) | Isomorphic API client — works in Node, browser, edge | +| [`@flow-state-dev/react`](/docs/api/react) | React hooks and renderers — wraps client, no transport logic | +| [`@flow-state-dev/testing`](/docs/api/testing) | Deterministic test harnesses with generator mocks | + +## Next steps + +- **[Quick Start](/docs/getting-started/quick-start)** — Build a streaming chat app in 5 minutes +- **[Blocks](/docs/concepts/blocks)** — Deep dive into the four primitives +- **[Building a Chat App](/docs/guides/building-a-chat-app)** — Complete walkthrough from blocks to React UI to tests diff --git a/apps/docs/docusaurus.config.ts b/apps/docs/docusaurus.config.ts index f09ec556a3..03328db775 100644 --- a/apps/docs/docusaurus.config.ts +++ b/apps/docs/docusaurus.config.ts @@ -4,7 +4,7 @@ import type * as Preset from "@docusaurus/preset-classic"; const config: Config = { title: "Flow State Dev", - tagline: "Block-based AI workflow framework for TypeScript", + tagline: "Composable AI workflows for TypeScript. Blocks in. Streaming out.", favicon: "img/favicon.ico", url: "https://flowstatedev.com", diff --git a/apps/docs/src/pages/index.module.css b/apps/docs/src/pages/index.module.css index 8eed17f32e..ec2178e039 100644 --- a/apps/docs/src/pages/index.module.css +++ b/apps/docs/src/pages/index.module.css @@ -1,32 +1,92 @@ .heroBanner { - padding: 4rem 0; + padding: 6rem 0 4rem; text-align: center; position: relative; overflow: hidden; + background: linear-gradient( + 180deg, + var(--ifm-color-primary-darkest) 0%, + var(--ifm-background-color) 100% + ); +} + +.heroTitle { + font-size: 3rem; + font-weight: 800; + letter-spacing: -0.02em; + margin-bottom: 1rem; +} + +.heroSubtitle { + font-size: 1.25rem; + max-width: 640px; + margin: 0 auto 2rem; + color: var(--ifm-color-emphasis-700); + line-height: 1.6; } .buttons { display: flex; align-items: center; justify-content: center; + gap: 1rem; margin-top: 1.5rem; } .features { display: flex; align-items: center; - padding: 2rem 0; + padding: 3rem 0; } -.codePreview { +.sectionSubtext { + color: var(--ifm-color-emphasis-600); + max-width: 600px; +} + +.codeShowcase { padding: 2rem 0 4rem; } -.codeBlock { - background: var(--ifm-code-background); - border-radius: var(--ifm-code-border-radius); - padding: 1.5rem; - font-size: 0.875rem; - line-height: 1.6; - overflow-x: auto; +.codeStep { + margin-bottom: 2rem; +} + +.codeStepLabel { + display: flex; + align-items: center; + gap: 0.75rem; + font-size: 1.1rem; + font-weight: 600; + margin-bottom: 0.75rem; + color: var(--ifm-color-emphasis-800); +} + +.codeStepNumber { + display: inline-flex; + align-items: center; + justify-content: center; + width: 1.75rem; + height: 1.75rem; + border-radius: 50%; + background: var(--ifm-color-primary); + color: #fff; + font-size: 0.85rem; + font-weight: 700; + flex-shrink: 0; +} + +.ctaSection { + padding: 4rem 0 5rem; + border-top: 1px solid var(--ifm-color-emphasis-200); +} + +@media (max-width: 768px) { + .heroTitle { + font-size: 2.2rem; + } + + .heroSubtitle { + font-size: 1.1rem; + } } diff --git a/apps/docs/src/pages/index.tsx b/apps/docs/src/pages/index.tsx index aa33c6dc36..7cb554478c 100644 --- a/apps/docs/src/pages/index.tsx +++ b/apps/docs/src/pages/index.tsx @@ -1,33 +1,35 @@ import clsx from "clsx"; import Link from "@docusaurus/Link"; -import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; import Layout from "@theme/Layout"; import Heading from "@theme/Heading"; +import CodeBlock from "@theme/CodeBlock"; import styles from "./index.module.css"; function HomepageHeader() { - const { siteConfig } = useDocusaurusContext(); return ( -
+
- - {siteConfig.title} + + Stop wiring. Start building. -

{siteConfig.tagline}

+

+ Flow State Dev is a TypeScript framework that turns AI orchestration, + streaming, state, and error handling into composable primitives — + so you can focus on what your AI actually does. +

Get Started - Learn More + Why Flow State Dev?
@@ -35,6 +37,84 @@ function HomepageHeader() { ); } +const defineFlowExample = `import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; + +// An LLM-powered chat with conversation history and tools +const chat = generator({ + name: "chat", + model: "gpt-5-mini", + prompt: "You are a helpful assistant.", + history: (_input, ctx) => ctx.session.items.llm(), + user: (input) => input.message, + tools: [searchDocs, createArtifact], +}); + +// Track usage with atomic state operations +const trackUsage = handler({ + name: "track-usage", + sessionStateSchema: z.object({ messageCount: z.number().default(0) }), + execute: async (input, ctx) => { + await ctx.session.incState({ messageCount: 1 }); + return input; + }, +}); + +// Compose into a pipeline with error recovery +const pipeline = sequencer({ name: "chat-pipeline" }) + .then(chat) + .then(trackUsage) + .rescue([{ when: [ModelError], block: fallback }]); + +// Define the flow — streaming, state, retries all handled +export default defineFlow({ + kind: "my-app", + actions: { + chat: { block: pipeline, userMessage: (i) => i.message }, + }, + session: { stateSchema, resources, projections }, +})({ id: "default" });`; + +const serverExample = `import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; +import myFlow from "./flows/my-flow"; + +const registry = createFlowRegistry(); +registry.register(myFlow); + +export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); +// That's it. Full REST API with SSE streaming.`; + +const reactExample = `function Chat() { + const flow = useFlow({ autoCreateSession: true }); + const session = useSession(flow.activeSessionId); + const { session: proj } = useProjections(session, { + session: ["messageCount"], + }); + + return ( + <> + {session.items.map(item => )} + {proj?.messageCount} messages + + + ); +}`; + +const testExample = `const result = await testBlock(pipeline, { + input: { message: "Hello" }, + session: { state: { messageCount: 0 } }, + generators: { + chat: mockGenerator({ script: [{ text: "Hi there!" }] }), + }, +}); + +expect(result.items).toContainItemOfType("message"); +expect(result.session.state.messageCount).toBe(1);`; + type FeatureItem = { title: string; description: string; @@ -42,24 +122,24 @@ type FeatureItem = { const FeatureList: FeatureItem[] = [ { - title: "Typed Blocks, Composable Flows", + title: "Four primitives. Infinite compositions.", description: - "Define handlers, generators, sequencers, and routers as typed building blocks. Compose them into flows with a fluent DSL that catches errors at build time.", + "Handler, generator, sequencer, router — every AI workflow reduces to these four blocks. Compose them into pipelines with branching, parallelism, loops, and error recovery using a fluent DSL.", }, { - title: "Resumable Streaming", + title: "Streaming that just works.", description: - "Item-first streaming with sequence-number replay. Clients reconnect mid-stream without losing data. SSE protocol with content deltas, tool calls, and status events.", + "Items stream over SSE as blocks execute — messages, tool calls, state changes, custom components. Disconnect mid-response? Reconnect with a sequence cursor. No data loss. No duplicates.", }, { - title: "Scoped State Management", + title: "State that scales with your app.", description: - "Four scope levels — request, session, user, project — with CAS-based state operations. Resources and projections provide typed data management with client visibility control.", + "Four isolation levels — request, session, user, project — each with atomic operations. Resources hold structured data. Projections are the only way to expose state to clients. Security by architecture.", }, { - title: "Full-Stack TypeScript", + title: "Type safety from schema to screen.", description: - "One type system from server execution through client transport to React UI. Schemas defined once, validated everywhere. No glue code between layers.", + "Define a Zod schema once. It validates at runtime, infers at compile time, and flows from server blocks through the client SDK to React hooks. No glue code. No type drift.", }, ]; @@ -88,43 +168,40 @@ function HomepageFeatures() { ); } -function HomepageCodePreview() { +type CodeTab = { + label: string; + code: string; + language: string; +}; + +const codeTabs: CodeTab[] = [ + { label: "Define", code: defineFlowExample, language: "ts" }, + { label: "Serve", code: serverExample, language: "ts" }, + { label: "Render", code: reactExample, language: "tsx" }, + { label: "Test", code: testExample, language: "ts" }, +]; + +function HomepageCodeShowcase() { return ( -
+
-
- - Define a flow in minutes +
+ + From definition to UI in four steps -
-              {`import { defineFlow, generator, sequencer } from "@flow-state-dev/core";
-import { z } from "zod";
-
-const chatGen = generator({
-  name: "chat",
-  model: "gpt-5-mini",
-  prompt: "You are a helpful assistant.",
-  inputSchema: z.object({ message: z.string() }),
-  user: (input) => input.message,
-});
-
-const pipeline = sequencer({
-  name: "chat-pipeline",
-  inputSchema: z.object({ message: z.string() }),
-}).then(chatGen);
-
-export default defineFlow({
-  kind: "my-chat",
-  actions: {
-    chat: {
-      inputSchema: z.object({ message: z.string() }),
-      block: pipeline,
-      userMessage: (input) => input.message,
-    },
-  },
-});`}
-            
+

+ Define your blocks and flows. Register with the server. Wire up React hooks. Write deterministic tests. Each layer is independent and composable. +

+ {codeTabs.map((tab, idx) => ( +
+
+ {idx + 1} + {tab.label} +
+ {tab.code} +
+ ))}
@@ -132,14 +209,38 @@ export default defineFlow({ ); } +function HomepageCTA() { + return ( +
+
+ Ready to build? +

+ Get a streaming chat app running in under 5 minutes. No boilerplate. No plumbing. +

+
+ + Quick Start Guide + +
+
+
+ ); +} + export default function Home(): React.ReactElement { - const { siteConfig } = useDocusaurusContext(); return ( - +
- + +
); From 2ab6415839b69254a2cb2526b56b23dd06d774f6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 13:41:33 +0000 Subject: [PATCH 03/15] Highlight tools-as-blocks, hybrid resources, ecosystem, and flows-as-APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Weaves four key differentiators throughout the docs that were previously underrepresented: 1. Tools are blocks (including sequencers): A generator's tools array accepts any block, so a single tool call can trigger an entire multi-step pipeline. Added dedicated "Tools are blocks" section to blocks.md with concrete examples, updated feature cards, intro, and README. 2. Resources as hybrid memory/filesystem: Resources combine rich text content with structured atomic state — like files that carry metadata. Rewrote the resources section in state.md to lead with this model, updated intro and README descriptions. 3. Ecosystem by design: Blocks and flows are portable. The uniform contract and partial state schemas mean community blocks compose without adapters. Added "Blocks are portable" section to blocks.md, new "Built for an ecosystem" feature card and README section. 4. Flows are full APIs: Register a flow and get complete REST endpoints with zero route wiring. Added "Flows are full APIs" section to intro, new feature card on landing page, updated server code example to show multiple flows with route comments, updated README. Landing page now has 6 feature cards in a 3-column grid (was 4 in 2-column). Code showcase updated to show a research assistant with sequencer-as-tool and resource with content+metadata. Verified: pnpm --filter docs build passes cleanly. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- README.md | 15 +++-- apps/docs/docs/concepts/blocks.md | 40 ++++++++++++- apps/docs/docs/concepts/state.md | 33 +++++++++-- apps/docs/docs/intro.md | 24 +++++++- apps/docs/src/pages/index.tsx | 93 ++++++++++++++++++++----------- 5 files changed, 157 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 69fb51688e..eafa5b047a 100644 --- a/README.md +++ b/README.md @@ -44,16 +44,18 @@ That's a streaming chat with conversation history, session state, and atomic cou | Block | What it does | |-------|-------------| -| **handler** | Pure logic — validate, transform, mutate state | +| **handler** | Pure logic — validate, transform, mutate state, implement tools | | **generator** | Call an LLM with managed tool loops, streaming, and structured output repair | | **sequencer** | Compose blocks into pipelines with `.then()`, `.parallel()`, `.rescue()`, `.forEach()`, and 10 more DSL methods | | **router** | Dispatch to different pipelines at runtime based on input or state | +Tools are blocks too — including sequencers. A single tool call can trigger an entire multi-step pipeline. This means your AI's tools can be as sophisticated as any other part of your workflow. + **Scoped state that scales.** Four isolation levels — request, session, user, project — each with atomic operations (`patchState`, `incState`, `pushState`, `atomicState`). Every block declares only the state fields it needs. Type-safe all the way down. **Resumable streaming out of the box.** Items stream over SSE as blocks execute. Disconnect mid-response? Reconnect with a sequence cursor and pick up exactly where you left off. No data loss. No duplicate events. -**Resources and projections for data policy.** Resources are typed, named state containers. Projections are derived views — and the *only* way to expose data to clients. You can't accidentally leak internal state. +**Resources: hybrid memory and filesystem.** Each resource combines rich text content with structured atomic state — like files that carry metadata. An artifact can hold a document's full text alongside its title, tags, and timestamps. Scoped to sessions, users, or projects. Projections derive client-safe views — the *only* way to expose data. You can't accidentally leak internal state. **First-class error handling.** Retry policies per block. Type-based rescue routing. Non-aborting work queues for side-chain operations. Normalized error model with codes, scopes, and retry signals. @@ -61,7 +63,9 @@ That's a streaming chat with conversation history, session state, and atomic cou ## The developer experience -**Server** — Register flows and get a complete API with three lines: +**Flows are full APIs.** Register a flow and you get action execution, session management, SSE streaming, and state snapshots — zero route wiring: + +**Server** — Three lines to a complete API: ```ts const registry = createFlowRegistry(); @@ -111,13 +115,16 @@ expect(result.items).toContainItemOfType("message"); expect(result.stateChanges[0].resultingState.messageCount).toBe(1); ``` +**Built for an ecosystem.** Blocks and flows are portable. Share a tool block, a validation handler, or a complete agentic flow across projects. The uniform block contract means community blocks compose with yours out of the box. + ## When this framework is for you - You're building AI-powered features and tired of reinventing orchestration, streaming, and state management every time. - You want composable primitives, not a rigid agent framework that prescribes how you structure your AI. +- You want tools that can be as powerful as your workflows — multi-step pipelines, not just function wrappers. +- You want your AI to have a real workspace: persistent resources with rich content and typed state, not just chat history. - You care about execution semantics — retry, rescue, lifecycle hooks — being explicit and testable, not hidden in application glue. - You want one coherent stack across server, client, React, CLI, and tests. -- You want the confidence that comes from end-to-end type safety with zero code generation. ## Packages diff --git a/apps/docs/docs/concepts/blocks.md b/apps/docs/docs/concepts/blocks.md index 411a04f8ec..c360ea1d28 100644 --- a/apps/docs/docs/concepts/blocks.md +++ b/apps/docs/docs/concepts/blocks.md @@ -54,10 +54,42 @@ const agent = generator({ What the framework handles for you: - **Prompt assembly** from four slots: system prompt, context entries, conversation history, and user message -- **Tool execution loops** — tools are handler blocks, auto-compiled to provider-native format +- **Tool execution loops** — tools are blocks, auto-compiled to provider-native format (see below) - **Streaming** — content deltas flow to the client as they're generated - **Structured output repair** — if the LLM returns invalid JSON, the framework can auto-retry or route to a rescue block +#### Tools are blocks + +This is one of the most powerful ideas in the framework. A generator's `tools` array accepts any block — handlers, sequencers, even routers. That means a single tool call can trigger an entire multi-step pipeline: + +```ts +// A tool that's a simple handler +const readDoc = handler({ + name: "read-doc", + inputSchema: z.object({ docId: z.string() }), + outputSchema: z.string(), + execute: async (input, ctx) => { + const doc = ctx.session.resources.get("docs")?.state.byId[input.docId]; + return doc?.content ?? "Document not found."; + }, +}); + +// A tool that's an entire pipeline — search, rank, summarize +const deepResearch = sequencer({ name: "deep-research" }) + .then(searchIndex) + .then(rankResults) + .then(summarize); + +// Both work as tools — the framework handles the rest +const agent = generator({ + name: "agent", + tools: [readDoc, deepResearch], + // ... +}); +``` + +When the LLM calls `deep-research`, the framework runs the full sequencer pipeline, collects the output, and feeds it back to the LLM as the tool result — all within the generator's tool loop. Your tools can be as sophisticated as any other part of your workflow. + ### Sequencer — the composition engine Sequencers compose blocks into pipelines using a fluent DSL. Each step's output feeds into the next step's input. @@ -142,6 +174,12 @@ const outerPipeline = sequencer({ name: "outer" }) .then(blockC); ``` +## Blocks are portable + +Because every block has the same contract — typed input, typed output, declared state dependencies — blocks are inherently shareable. A handler that validates email addresses, a sequencer that does multi-step research, a generator pre-configured for code review — each can be packaged independently and composed into any flow. + +This is by design. The framework's four-primitive constraint and partial state schemas mean blocks don't leak assumptions about the flows they live in. A block from a shared package composes with your blocks the same way your own blocks compose with each other. + ## Key rules - **Always use `block.run()`** — never call `block.config.execute` directly. The framework manages validation, retry, lifecycle, and streaming through `block.run()`. diff --git a/apps/docs/docs/concepts/state.md b/apps/docs/docs/concepts/state.md index 3902181ffd..005ab4bd42 100644 --- a/apps/docs/docs/concepts/state.md +++ b/apps/docs/docs/concepts/state.md @@ -90,16 +90,23 @@ const counter = handler({ This keeps blocks reusable and self-documenting about their dependencies. -## Resources +## Resources — hybrid memory and filesystem -Resources are named, schema-typed data containers attached to a scope. Use them for structured data that needs its own lifecycle — artifacts, plans, documents, collections: +Resources are more than key-value stores. Each resource combines **rich text content** with **structured atomic state** — think of them as files that carry metadata. This hybrid model gives your AI a persistent, typed workspace. + +Consider an artifacts resource: each artifact has a `content` field (the "file" — a document, code snippet, plan, or any rich text) alongside structured fields like `title`, `tags`, and `updatedAt` (the "metadata"). Both live in the same typed container with the same atomic operations: ```ts session: { resources: { artifacts: { stateSchema: z.object({ - byId: z.record(z.object({ title: z.string(), content: z.string() })).default({}), + byId: z.record(z.object({ + title: z.string(), + content: z.string(), // The "file" — rich text content + tags: z.array(z.string()), // Structured metadata + updatedAt: z.number(), // Structured metadata + })).default({}), order: z.array(z.string()).default([]), }), writable: true, @@ -112,14 +119,28 @@ Access resources through scope handles — they have the same atomic operations ```ts const artifacts = ctx.session.resources.get("artifacts"); -const titles = artifacts.state.order.map(id => artifacts.state.byId[id]?.title); +// Read content and metadata together +const doc = artifacts.state.byId["design-doc"]; +console.log(doc.content); // The full document text +console.log(doc.tags); // ["architecture", "v2"] + +// Write with atomic state operations await artifacts.patchState({ - byId: { "doc-1": { title: "Design Doc", content: "..." } }, - order: [...artifacts.state.order, "doc-1"], + byId: { + "design-doc": { + title: "Design Doc v2", + content: "# Architecture\n\nThe system is composed of...", + tags: ["architecture", "v2"], + updatedAt: Date.now(), + }, + }, + order: [...artifacts.state.order, "design-doc"], }); ``` +Resources are scoped — session-level resources persist across requests in a conversation, user-level resources persist across sessions, project-level resources are shared across users. This gives you a natural hierarchy: scratch artifacts in a session, personal notes per user, shared knowledge bases per project. + ## Projections Projections are derived views computed from state and resources. They're the **only way** to expose data to clients: diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.md index 11af5b247f..869fc4ba23 100644 --- a/apps/docs/docs/intro.md +++ b/apps/docs/docs/intro.md @@ -50,7 +50,19 @@ Every piece of logic — calling an LLM, validating input, choosing a path, comp | **Sequencer** | Compose blocks into pipelines | Multi-step workflows with branching, parallelism, error recovery | | **Router** | Dispatch to different pipelines at runtime | Mode switching, intent routing, conditional flows | -All blocks share the same contract: `block.run(input, ctx)`. Any block composes with any other block. +All blocks share the same contract: `block.run(input, ctx)`. Any block composes with any other block. This includes tools — a generator's tools are blocks, which means a single tool call can trigger a handler, a sequencer pipeline, or even a router that dispatches to different strategies. Your AI's tools can be as simple or as sophisticated as any other part of your workflow. + +### Flows are full APIs + +Define a flow, register it with the server, and you have a complete REST API — action execution, session management, SSE streaming, state snapshots — with zero route wiring. Every flow you register becomes instantly callable from any client: + +``` +POST /api/flows/my-app/actions/chat → Execute an action +GET /api/flows/my-app/requests/:id/stream → Stream results via SSE +GET /api/flows/my-app/sessions/:id/state → State snapshot with projections +``` + +Multiple flows can coexist in the same server. Each one is self-contained with its own actions, state, and resources. ### Resumable streaming @@ -69,9 +81,15 @@ Four isolation levels with atomic operations: Each block declares only the state fields it needs via partial schemas. A counter block doesn't need to know about a preferences block's state. -### Resources and projections +### Resources: hybrid memory and filesystem + +**Resources** are more than key-value stores. Each resource combines rich text content with structured atomic state — like a file that carries metadata. An artifact resource can hold a document's full text alongside its title, tags, and timestamps, all in one typed container with atomic operations. Scoped to sessions, users, or projects, resources give your AI a persistent, typed workspace. + +**Projections** are derived views computed from state and resources, and the *only* way to expose data to clients. You can't accidentally leak internal state because projections are the sole data gateway. + +### Built for an ecosystem -**Resources** are typed data containers — think artifacts, plans, documents — scoped to sessions, users, or projects. **Projections** are derived views computed from state and resources, and the *only* way to expose data to clients. You can't accidentally leak internal state because projections are the sole data gateway. +Blocks and flows are portable by design. A tool block, a validation handler, a complete agentic workflow — each is a self-contained unit with typed inputs, outputs, and declared state dependencies. Share them across projects or publish them as packages. The uniform block contract means community blocks compose with yours without adapters or glue code. ### Full-stack type safety diff --git a/apps/docs/src/pages/index.tsx b/apps/docs/src/pages/index.tsx index 7cb554478c..f7495cfc06 100644 --- a/apps/docs/src/pages/index.tsx +++ b/apps/docs/src/pages/index.tsx @@ -39,49 +39,64 @@ function HomepageHeader() { const defineFlowExample = `import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; -// An LLM-powered chat with conversation history and tools -const chat = generator({ - name: "chat", +// Tools are blocks — even sequencers. This tool is a multi-step pipeline. +const deepResearch = sequencer({ name: "deep-research" }) + .then(searchIndex) + .then(rankResults) + .then(summarize); + +// Resources give your AI a persistent workspace: text + structured state +// Think files with metadata, scoped to sessions, users, or projects. +const docResource = { + stateSchema: z.object({ + byId: z.record(z.object({ + title: z.string(), + content: z.string(), // Rich text — the "file" part + tags: z.array(z.string()), // Structured state — the "metadata" part + })).default({}), + order: z.array(z.string()).default([]), + }), + writable: true, +}; + +// Generator with tool access — tools run as blocks in the framework +const agent = generator({ + name: "agent", model: "gpt-5-mini", - prompt: "You are a helpful assistant.", + prompt: "You are a research assistant.", history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, - tools: [searchDocs, createArtifact], + tools: [deepResearch, readDoc, writeDoc], // Blocks as tools }); -// Track usage with atomic state operations -const trackUsage = handler({ - name: "track-usage", - sessionStateSchema: z.object({ messageCount: z.number().default(0) }), - execute: async (input, ctx) => { - await ctx.session.incState({ messageCount: 1 }); - return input; - }, -}); - -// Compose into a pipeline with error recovery -const pipeline = sequencer({ name: "chat-pipeline" }) - .then(chat) - .then(trackUsage) - .rescue([{ when: [ModelError], block: fallback }]); - -// Define the flow — streaming, state, retries all handled +// Define the flow — this becomes a full API instantly export default defineFlow({ - kind: "my-app", + kind: "research-assistant", actions: { - chat: { block: pipeline, userMessage: (i) => i.message }, + chat: { block: agent, userMessage: (i) => i.message }, + }, + session: { + stateSchema, + resources: { docs: docResource }, + projections: { + docList: { client: true, compute: (ctx) => /* derived view */ }, + }, }, - session: { stateSchema, resources, projections }, })({ id: "default" });`; const serverExample = `import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; -import myFlow from "./flows/my-flow"; +import researchFlow from "./flows/research-assistant"; +import chatFlow from "./flows/chat"; const registry = createFlowRegistry(); -registry.register(myFlow); +registry.register(researchFlow); +registry.register(chatFlow); // Register as many flows as you need export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); -// That's it. Full REST API with SSE streaming.`; +// Each flow is now a full API: actions, sessions, streaming, state snapshots. +// POST /api/flows/research-assistant/actions/chat +// GET /api/flows/research-assistant/requests/:id/stream +// GET /api/flows/research-assistant/sessions/:id/state`; const reactExample = `function Chat() { const flow = useFlow({ autoCreateSession: true }); @@ -124,17 +139,27 @@ const FeatureList: FeatureItem[] = [ { title: "Four primitives. Infinite compositions.", description: - "Handler, generator, sequencer, router — every AI workflow reduces to these four blocks. Compose them into pipelines with branching, parallelism, loops, and error recovery using a fluent DSL.", + "Handler, generator, sequencer, router — every AI workflow reduces to these four blocks. Tools are blocks too — even sequencers, so a single tool call can trigger an entire pipeline. Compose freely with branching, parallelism, loops, and error recovery.", }, { - title: "Streaming that just works.", + title: "Flows are full APIs.", description: - "Items stream over SSE as blocks execute — messages, tool calls, state changes, custom components. Disconnect mid-response? Reconnect with a sequence cursor. No data loss. No duplicates.", + "Define a flow, register it, and you have a complete REST API with SSE streaming, session management, and state snapshots. No route wiring. No transport plumbing. Every flow is instantly callable from any client.", }, { - title: "State that scales with your app.", + title: "Resources: hybrid memory + filesystem.", description: - "Four isolation levels — request, session, user, project — each with atomic operations. Resources hold structured data. Projections are the only way to expose state to clients. Security by architecture.", + "Resources combine rich text content with atomic structured state — like files that carry metadata. Scoped to sessions, users, or projects. Projections derive client-safe views. Your AI gets a persistent, typed workspace.", + }, + { + title: "Built for an ecosystem.", + description: + "Blocks and flows are portable by design. Share a tool block, a validation handler, or an entire flow across projects. The uniform block contract means community blocks compose with yours out of the box.", + }, + { + title: "Streaming that just works.", + description: + "Items stream over SSE as blocks execute — messages, tool calls, state changes, custom components. Disconnect mid-response? Reconnect with a sequence cursor. No data loss. No duplicates.", }, { title: "Type safety from schema to screen.", @@ -145,7 +170,7 @@ const FeatureList: FeatureItem[] = [ function Feature({ title, description }: FeatureItem) { return ( -
+
{title}

{description}

From 3beeba88a2256b71a9153565c55836acee733869 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 15:55:24 +0000 Subject: [PATCH 04/15] =?UTF-8?q?Fix=20incorrect=20session=20state=20route?= =?UTF-8?q?=20=E2=80=94=20sessions=20endpoint=20has=20no=20kind=20segment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The session state snapshot route is GET /api/flows/sessions/:id/state, not /api/flows/:kind/sessions/:id/state. Fixed in the landing page server example and the intro page route listing. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- apps/docs/docs/intro.md | 2 +- apps/docs/src/pages/index.tsx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.md index 869fc4ba23..33e40af11c 100644 --- a/apps/docs/docs/intro.md +++ b/apps/docs/docs/intro.md @@ -59,7 +59,7 @@ Define a flow, register it with the server, and you have a complete REST API — ``` POST /api/flows/my-app/actions/chat → Execute an action GET /api/flows/my-app/requests/:id/stream → Stream results via SSE -GET /api/flows/my-app/sessions/:id/state → State snapshot with projections +GET /api/flows/sessions/:id/state → State snapshot with projections ``` Multiple flows can coexist in the same server. Each one is self-contained with its own actions, state, and resources. diff --git a/apps/docs/src/pages/index.tsx b/apps/docs/src/pages/index.tsx index f7495cfc06..b8a3eff75e 100644 --- a/apps/docs/src/pages/index.tsx +++ b/apps/docs/src/pages/index.tsx @@ -96,7 +96,7 @@ export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); // Each flow is now a full API: actions, sessions, streaming, state snapshots. // POST /api/flows/research-assistant/actions/chat // GET /api/flows/research-assistant/requests/:id/stream -// GET /api/flows/research-assistant/sessions/:id/state`; +// GET /api/flows/sessions/:id/state`; const reactExample = `function Chat() { const flow = useFlow({ autoCreateSession: true }); From a124c47424066ec388cb63ef279140c7fdef770d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 18:13:13 +0000 Subject: [PATCH 05/15] Stylize as flow-state.dev, fix branding, improve examples, add connectors docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Branding: - Stylize framework name as "flow-state.dev" throughout — site title, navbar, hero subtitle, meta description - Add .brandName CSS class: monospace font, bold, primary-light color to give the lowercase name visual distinction - URL changed to https://flow-state.dev - Copyright changed to Fixpoint Labs, LLC Projection example: - Replace messageCount projection (trivially computable client-side) with docList — a projection that derives a document list from a resource, showing the real value of projections - React example now shows a research assistant with a sidebar of documents derived from server-side resources - Test example updated to match: seeds resource state, asserts on tool_call items Tools messaging: - Reword "tools are blocks too" to "any block or sequence of blocks can be used as a tool" — clearer, less confusing - Updated in landing page (feature card + code comments), README, intro.md, and blocks.md concept page Block connectors: - Add "Connecting blocks with different shapes" section to blocks.md explaining how blocks with incompatible types work together - Covers sequencer connectors (the primary pattern), block-level connectInput/connectOutput, and why connectors matter for portability - Concrete examples: reshaping output for the next block, parallel with mixed connectors, adapting community blocks Verified: pnpm --filter docs build passes cleanly. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- README.md | 2 +- apps/docs/docs/concepts/blocks.md | 73 +++++++++++++++++++++++++--- apps/docs/docs/intro.md | 2 +- apps/docs/docusaurus.config.ts | 8 +-- apps/docs/src/pages/index.module.css | 7 +++ apps/docs/src/pages/index.tsx | 54 +++++++++++++------- 6 files changed, 116 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index eafa5b047a..1a876714f3 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ That's a streaming chat with conversation history, session state, and atomic cou | **sequencer** | Compose blocks into pipelines with `.then()`, `.parallel()`, `.rescue()`, `.forEach()`, and 10 more DSL methods | | **router** | Dispatch to different pipelines at runtime based on input or state | -Tools are blocks too — including sequencers. A single tool call can trigger an entire multi-step pipeline. This means your AI's tools can be as sophisticated as any other part of your workflow. +Any block or sequence of blocks can be used as a tool. A single tool call can trigger an entire multi-step pipeline — your AI's tools can be as sophisticated as any other part of your workflow. **Scoped state that scales.** Four isolation levels — request, session, user, project — each with atomic operations (`patchState`, `incState`, `pushState`, `atomicState`). Every block declares only the state fields it needs. Type-safe all the way down. diff --git a/apps/docs/docs/concepts/blocks.md b/apps/docs/docs/concepts/blocks.md index c360ea1d28..2784e10804 100644 --- a/apps/docs/docs/concepts/blocks.md +++ b/apps/docs/docs/concepts/blocks.md @@ -58,12 +58,12 @@ What the framework handles for you: - **Streaming** — content deltas flow to the client as they're generated - **Structured output repair** — if the LLM returns invalid JSON, the framework can auto-retry or route to a rescue block -#### Tools are blocks +#### Any block can be a tool -This is one of the most powerful ideas in the framework. A generator's `tools` array accepts any block — handlers, sequencers, even routers. That means a single tool call can trigger an entire multi-step pipeline: +Any block or sequence of blocks can be used as a tool. A generator's `tools` array accepts handlers, sequencers, routers — anything with the block contract. That means a single tool call can trigger an entire multi-step pipeline: ```ts -// A tool that's a simple handler +// A simple handler as a tool const readDoc = handler({ name: "read-doc", inputSchema: z.object({ docId: z.string() }), @@ -74,13 +74,13 @@ const readDoc = handler({ }, }); -// A tool that's an entire pipeline — search, rank, summarize +// A full pipeline as a tool — search, rank, summarize const deepResearch = sequencer({ name: "deep-research" }) .then(searchIndex) .then(rankResults) .then(summarize); -// Both work as tools — the framework handles the rest +// Both work as tools — the framework compiles them for the LLM const agent = generator({ name: "agent", tools: [readDoc, deepResearch], @@ -88,7 +88,7 @@ const agent = generator({ }); ``` -When the LLM calls `deep-research`, the framework runs the full sequencer pipeline, collects the output, and feeds it back to the LLM as the tool result — all within the generator's tool loop. Your tools can be as sophisticated as any other part of your workflow. +When the LLM calls `deep-research`, the framework runs the full sequencer pipeline, collects the output, and feeds it back as the tool result — all within the generator's tool loop. Your tools can be as sophisticated as any other part of your workflow. ### Sequencer — the composition engine @@ -174,11 +174,70 @@ const outerPipeline = sequencer({ name: "outer" }) .then(blockC); ``` +## Connecting blocks with different shapes + +An immediate question: if blocks have typed inputs and outputs, how do they fit together when their types don't match? The answer is **connectors** — lightweight functions that transform one block's output into the next block's input. + +### Sequencer connectors + +The most common pattern. Pass a transform function before the block in any sequencer method: + +```ts +const pipeline = sequencer({ name: "pipeline", inputSchema }) + // Block A outputs { text: string, metadata: {...} } + // Block B expects { query: string } + .then(blockA) + .then( + (output) => ({ query: output.text }), // Connector: reshape the data + blockB + ); +``` + +Connectors receive the previous step's output and the block context, and return the shape the next block expects. They work across the entire sequencer DSL: + +```ts +pipeline + .then((output) => ({ query: output.text }), searchBlock) // then + .thenIf(needsReview, (output) => output.results, reviewBlock) // thenIf + .parallel({ // parallel + summary: summaryBlock, + tags: { connector: (output) => output.text, block: tagBlock }, + }) + .forEach((output) => output.items, processBlock) // forEach +``` + +The type system tracks these transformations — TypeScript knows the connector's return type must match the next block's input schema. + +### Block-level connections + +You can also attach transforms directly to a block with `connectInput` and `connectOutput`. This is useful when you want a block to always accept a different input shape: + +```ts +// Create an adapted version of searchBlock that accepts a string +const searchFromText = searchBlock.connectInput( + (text: string) => ({ query: text, limit: 10 }) +); + +// Now it fits directly in the pipeline without a sequencer connector +pipeline.then(searchFromText); +``` + +### Why this matters for portability + +Connectors are how blocks from different packages work together. A community search block expects `{ query: string, limit: number }`. Your pipeline produces `{ text: string, metadata: object }`. A one-line connector bridges the gap — no wrapper blocks, no adapters, no type gymnastics: + +```ts +pipeline.then( + (output) => ({ query: output.text, limit: 5 }), + communitySearchBlock +); +``` + ## Blocks are portable Because every block has the same contract — typed input, typed output, declared state dependencies — blocks are inherently shareable. A handler that validates email addresses, a sequencer that does multi-step research, a generator pre-configured for code review — each can be packaged independently and composed into any flow. -This is by design. The framework's four-primitive constraint and partial state schemas mean blocks don't leak assumptions about the flows they live in. A block from a shared package composes with your blocks the same way your own blocks compose with each other. +Connectors make this practical: when types don't align, a simple transform function bridges the gap. No wrapper blocks, no inheritance hierarchies. The framework's four-primitive constraint and partial state schemas mean blocks don't leak assumptions about the flows they live in. ## Key rules diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.md index 33e40af11c..fc3176e91b 100644 --- a/apps/docs/docs/intro.md +++ b/apps/docs/docs/intro.md @@ -50,7 +50,7 @@ Every piece of logic — calling an LLM, validating input, choosing a path, comp | **Sequencer** | Compose blocks into pipelines | Multi-step workflows with branching, parallelism, error recovery | | **Router** | Dispatch to different pipelines at runtime | Mode switching, intent routing, conditional flows | -All blocks share the same contract: `block.run(input, ctx)`. Any block composes with any other block. This includes tools — a generator's tools are blocks, which means a single tool call can trigger a handler, a sequencer pipeline, or even a router that dispatches to different strategies. Your AI's tools can be as simple or as sophisticated as any other part of your workflow. +All blocks share the same contract: `block.run(input, ctx)`. Any block composes with any other block — and any block or sequence of blocks can be used as a tool. That means a single tool call can trigger a handler, a multi-step sequencer pipeline, or even a router that dispatches to different strategies. Your AI's tools can be as simple or as sophisticated as any other part of your workflow. ### Flows are full APIs diff --git a/apps/docs/docusaurus.config.ts b/apps/docs/docusaurus.config.ts index 03328db775..7d51ed82d1 100644 --- a/apps/docs/docusaurus.config.ts +++ b/apps/docs/docusaurus.config.ts @@ -3,11 +3,11 @@ import type { Config } from "@docusaurus/types"; import type * as Preset from "@docusaurus/preset-classic"; const config: Config = { - title: "Flow State Dev", + title: "flow-state.dev", tagline: "Composable AI workflows for TypeScript. Blocks in. Streaming out.", favicon: "img/favicon.ico", - url: "https://flowstatedev.com", + url: "https://flow-state.dev", baseUrl: "/", organizationName: "flow-state-dev", @@ -49,7 +49,7 @@ const config: Config = { themeConfig: { navbar: { - title: "Flow State Dev", + title: "flow-state.dev", items: [ { type: "docSidebar", @@ -101,7 +101,7 @@ const config: Config = { ], }, ], - copyright: `Copyright ${new Date().getFullYear()} Flow State Dev. Built with Docusaurus.`, + copyright: `Copyright ${new Date().getFullYear()} Fixpoint Labs, LLC. Built with Docusaurus.`, }, prism: { theme: prismThemes.github, diff --git a/apps/docs/src/pages/index.module.css b/apps/docs/src/pages/index.module.css index ec2178e039..3b6e81e46a 100644 --- a/apps/docs/src/pages/index.module.css +++ b/apps/docs/src/pages/index.module.css @@ -25,6 +25,13 @@ line-height: 1.6; } +.brandName { + font-family: var(--ifm-font-family-monospace); + font-weight: 700; + color: var(--ifm-color-primary-light); + letter-spacing: -0.01em; +} + .buttons { display: flex; align-items: center; diff --git a/apps/docs/src/pages/index.tsx b/apps/docs/src/pages/index.tsx index b8a3eff75e..de78fb1b00 100644 --- a/apps/docs/src/pages/index.tsx +++ b/apps/docs/src/pages/index.tsx @@ -14,7 +14,7 @@ function HomepageHeader() { Stop wiring. Start building.

- Flow State Dev is a TypeScript framework that turns AI orchestration, + flow-state.dev is a TypeScript framework that turns AI orchestration, streaming, state, and error handling into composable primitives — so you can focus on what your AI actually does.

@@ -29,7 +29,7 @@ function HomepageHeader() { className="button button--secondary button--lg" to="/docs/intro" > - Why Flow State Dev? + Why flow-state.dev?
@@ -39,7 +39,8 @@ function HomepageHeader() { const defineFlowExample = `import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; -// Tools are blocks — even sequencers. This tool is a multi-step pipeline. +// Any block or sequence of blocks can be used as a tool. +// This tool is a full multi-step pipeline. const deepResearch = sequencer({ name: "deep-research" }) .then(searchIndex) .then(rankResults) @@ -59,14 +60,14 @@ const docResource = { writable: true, }; -// Generator with tool access — tools run as blocks in the framework +// Pass any block as a tool — the framework compiles it for the LLM const agent = generator({ name: "agent", model: "gpt-5-mini", prompt: "You are a research assistant.", history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, - tools: [deepResearch, readDoc, writeDoc], // Blocks as tools + tools: [deepResearch, readDoc, writeDoc], }); // Define the flow — this becomes a full API instantly @@ -98,37 +99,56 @@ export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); // GET /api/flows/research-assistant/requests/:id/stream // GET /api/flows/sessions/:id/state`; -const reactExample = `function Chat() { +const reactExample = `function ResearchApp() { const flow = useFlow({ autoCreateSession: true }); const session = useSession(flow.activeSessionId); + + // Projections derive client-safe views from server-side resources const { session: proj } = useProjections(session, { - session: ["messageCount"], + session: ["docList"], }); return ( <> + {/* Items stream in real time as the AI works */} {session.items.map(item => )} - {proj?.messageCount} messages + + {/* Projection: derived from resource state, updated after each request */} + + ); }`; -const testExample = `const result = await testBlock(pipeline, { - input: { message: "Hello" }, - session: { state: { messageCount: 0 } }, +const testExample = `// Deterministic tests — no real LLM calls, no network +const result = await testFlow({ + flow: researchFlow, + action: "chat", + input: { message: "Summarize the design doc" }, + userId: "testuser", + seed: { + session: { + resources: { + docs: { byId: { "design-doc": { title: "Design", content: "..." } } }, + }, + }, + }, generators: { - chat: mockGenerator({ script: [{ text: "Hi there!" }] }), + agent: mockGenerator({ script: [{ text: "The design doc covers..." }] }), }, }); expect(result.items).toContainItemOfType("message"); -expect(result.session.state.messageCount).toBe(1);`; +expect(result.items).toContainItemOfType("tool_call");`; type FeatureItem = { title: string; @@ -137,9 +157,9 @@ type FeatureItem = { const FeatureList: FeatureItem[] = [ { - title: "Four primitives. Infinite compositions.", + title: "Four primitives. Compose freely.", description: - "Handler, generator, sequencer, router — every AI workflow reduces to these four blocks. Tools are blocks too — even sequencers, so a single tool call can trigger an entire pipeline. Compose freely with branching, parallelism, loops, and error recovery.", + "Handler, generator, sequencer, router — every AI workflow reduces to these four blocks. Any block or sequence of blocks can be used as a tool, so a single tool call can trigger an entire pipeline. Compose freely with branching, parallelism, loops, and error recovery.", }, { title: "Flows are full APIs.", @@ -259,7 +279,7 @@ export default function Home(): React.ReactElement { return (
From c93a5c756131ea483d29ad69d2757df456a4effb Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 18:17:39 +0000 Subject: [PATCH 06/15] Rewrite blog post to reflect framework vision: exploring new AI patterns The blog post now frames flow-state.dev as a framework for pushing the boundaries of AI agent architectures, not just making existing patterns easier. Emphasizes composable primitives for experimentation, building together as an ecosystem, and solid infrastructure for bold experiments. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- apps/docs/blog/2026-02-26-welcome.md | 69 +++++++++++++++++++--------- 1 file changed, 47 insertions(+), 22 deletions(-) diff --git a/apps/docs/blog/2026-02-26-welcome.md b/apps/docs/blog/2026-02-26-welcome.md index 6cf37dcd2b..105588ec76 100644 --- a/apps/docs/blog/2026-02-26-welcome.md +++ b/apps/docs/blog/2026-02-26-welcome.md @@ -1,49 +1,74 @@ --- slug: welcome -title: "Introducing Flow State Dev: AI Workflows Without the Plumbing" +title: "We Don't Know What the Best AI Agents Look Like Yet" authors: [flowstatedev] tags: [announcement] --- -We've been building AI features for a while now. And every time, we end up writing the same infrastructure: orchestrate LLM calls, wire up SSE streaming, manage conversation state, handle retries, sync everything to the frontend. It's tedious. It's error-prone. And it has nothing to do with what the AI actually does. +Most AI frameworks start from the same premise: here's how agents work, here's the pattern, fill in the blanks. ReAct loops. Tool-calling chains. RAG pipelines. These are well-understood patterns, and there are plenty of good frameworks for executing them. -Flow State Dev is our answer: a TypeScript framework that makes orchestration, streaming, state, and error handling **composable primitives** instead of application glue. +We're building something different. **flow-state.dev** exists because we believe the most powerful AI agent architectures haven't been discovered yet — and the only way to find them is to give developers the right primitives to explore. -## The core idea +## The frontier is wide open -Four block types — **handler**, **generator**, **sequencer**, **router** — compose into any AI workflow. The framework handles execution, streaming, state persistence, retries, and client rendering. +We're still in the early days of what AI agents can do. The patterns that dominate today — single-agent loops, linear chains, fixed tool sets — are starting points, not endpoints. The teams pushing boundaries are the ones experimenting with novel architectures: agents that spawn sub-agents with their own tool pipelines, workflows where a single tool call triggers a multi-step research process, systems where AI has a persistent workspace it can read, write, and organize across conversations. + +But experimenting is hard when your framework assumes you already know the shape of your solution. Most tools lock you into their mental model. You can configure what they anticipated. Everything else is a workaround. + +## Primitives, not patterns + +**flow-state.dev** takes a different approach. Instead of prescribing agent architectures, we give you four composable primitives — **handler**, **generator**, **sequencer**, **router** — and a powerful composition system. That's it. Every AI workflow you can imagine reduces to combinations of these four blocks. + +The constraint is liberating. Want an agent whose tools are themselves multi-step pipelines? Compose a sequencer, pass it as a tool. Want a router that dispatches to entirely different agent architectures based on runtime state? That's just a router block with sequencer routes. Want to give your AI a persistent workspace with rich documents and structured metadata it can manipulate across sessions? That's resources — hybrid memory that combines text content with atomic state. ```ts -const pipeline = sequencer({ name: "chat-pipeline" }) - .then(analyzeInput) - .thenIf((result) => result.needsContext, enrichWithContext) - .then(agentGenerator) - .then(trackUsage) - .rescue([{ when: [ModelError], block: fallback }]); +// A tool that's a full research pipeline — not just a function wrapper +const deepResearch = sequencer({ name: "deep-research" }) + .then(searchIndex) + .then(rankResults) + .then(summarize); + +// An agent whose tools are as sophisticated as the agent itself +const agent = generator({ + name: "agent", + model: "gpt-5-mini", + tools: [deepResearch, readDoc, writeDoc], + // ... +}); ``` -That pipeline analyzes input, conditionally enriches it, calls an LLM with tool access, tracks usage, and recovers from model errors. Every step streams results to the client in real time over SSE with automatic resume on disconnect. +We didn't design this to make existing patterns easier to implement (though it does). We designed it so you can explore patterns that don't have names yet. + +## Built to build together + +Exploring new boundaries alone is slow. The real acceleration happens when discoveries compound — when one team's novel tool pipeline becomes another team's building block, when an agent architecture that works brilliantly in one domain gets adapted to another. + +That's why **flow-state.dev** is built for an ecosystem from day one. Every block has the same contract: typed input, typed output, declared state dependencies. A handler, a sequencer pipeline, an entire agent flow — each is a portable unit that composes with anything else. Connectors bridge incompatible types with a single function. No wrappers. No adapters. No inheritance hierarchies. -## What's different +When someone discovers a powerful new pattern — a novel retrieval strategy, an innovative agent coordination mechanism, a breakthrough in structured output handling — they can package it as blocks and share it. And those blocks compose with yours immediately, because the contracts are universal. -**You compose primitives, not configure a framework.** Most AI frameworks give you an opinionated agent architecture and ask you to fill in the blanks. Flow State Dev gives you four building blocks and a composition DSL. You decide what your AI does. The framework handles how it runs. +## Solid ground for bold experiments -**Streaming is structural, not bolted on.** Items (messages, tool calls, state changes, custom components) stream as blocks execute, with sequence-number cursors for replay. This isn't an afterthought — it's the core delivery mechanism. +Exploring new frontiers requires solid infrastructure underneath. You shouldn't have to reinvent streaming, state management, and error handling every time you want to try a new agent architecture. So we made these framework-level concerns: -**State is scoped and typed.** Four isolation levels (request, session, user, project) with atomic operations and CAS concurrency. Each block declares only the state it needs. Projections are the only way to expose data to clients — security by architecture. +- **Resumable SSE streaming** with sequence-number cursors — disconnect mid-experiment and pick up exactly where you left off +- **Scoped state** at four isolation levels with atomic operations — your agent's workspace is reliable even under concurrent access +- **Resources** that combine rich text with structured state — give your AI a real workspace, not just a chat log +- **Type safety from schema to screen** — one Zod schema flows from server blocks through client SDK to React hooks +- **Deterministic testing** — mock generators, seed state, assert on items and state changes without real LLM calls -**One type system, server to screen.** Zod schemas defined once, validated at runtime, inferred at compile time. From block definitions through the client SDK to React hooks. No glue code. +The framework handles execution semantics — retry, rescue, lifecycle hooks, streaming — so you can focus entirely on the architecture of your AI. Every experiment runs on battle-tested infrastructure. ## Where we are -Phase 1 (Foundation) is largely complete: core contracts, block builders, server runtime with stores and streaming, client transport, React hooks and renderers, and a testing package with deterministic generator mocks. Two canonical examples — [hello-chat](https://github.com/flow-state-dev/flow-state-dev) and [kitchen-sink](https://github.com/flow-state-dev/flow-state-dev) — demonstrate the full stack. +Phase 1 (Foundation) is largely complete: core contracts, block builders, server runtime with stores and streaming, client transport, React hooks and renderers, and a testing package with deterministic generator mocks. CLI and devtool are in active development. -CLI and devtool are in active development. +## Come build with us -## What's next +We're not here to tell you how AI agents should work. We're here to give you the tools to figure that out — and to make it easy to share what you discover. -We're focused on developer experience polish, cross-package validation, and getting the documentation site to a point where you can go from zero to a running AI app without friction. +The best agent architectures of 2027 probably don't look like anything we'd design today. But they'll be built from composable primitives, on solid infrastructure, by developers who had the freedom to experiment. -If you're building AI features in TypeScript and tired of reinventing the same infrastructure, [give it a try](/docs/getting-started/quick-start). +[Get started](/docs/getting-started/quick-start) and see what you can build. From 15967b867ca6e07f7f0ec3f1085add0c0fd6a219 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 18:30:35 +0000 Subject: [PATCH 07/15] Redesign landing page: dark theme, modern layout, mobile-friendly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Dark-first design with deep backgrounds, subtle radial gradients, and glassmorphism feature cards with hover effects - Pill-shaped buttons with glow on primary, glass on secondary - Proper mobile spacing (1.25-1.5rem padding), responsive text sizing down to 480px breakpoint, stacked buttons on small screens - Feature grid: 3-col → 2-col → 1-col responsive with glass cards - Tabbed code showcase (Define/Serve/Render/Test) instead of showing all 4 code blocks sequentially — much less scrolling on mobile - Subtle gradient dividers between sections - Frosted glass navbar in dark mode - Light theme fallbacks for all custom styles https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- apps/docs/src/css/custom.css | 14 + apps/docs/src/pages/index.module.css | 515 ++++++++++++++++++++++++--- apps/docs/src/pages/index.tsx | 252 ++++++------- 3 files changed, 612 insertions(+), 169 deletions(-) diff --git a/apps/docs/src/css/custom.css b/apps/docs/src/css/custom.css index 93042edb50..0a079ca266 100644 --- a/apps/docs/src/css/custom.css +++ b/apps/docs/src/css/custom.css @@ -18,5 +18,19 @@ --ifm-color-primary-light: #a5b4fc; --ifm-color-primary-lighter: #c7d2fe; --ifm-color-primary-lightest: #e0e7ff; + --ifm-background-color: #0a0a0f; + --ifm-background-surface-color: #111118; + --ifm-navbar-background-color: rgba(10, 10, 15, 0.8); + --ifm-footer-background-color: #06060a; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); } + +[data-theme="dark"] .navbar { + backdrop-filter: blur(12px); + -webkit-backdrop-filter: blur(12px); + border-bottom: 1px solid rgba(255, 255, 255, 0.06); +} + +[data-theme="dark"] .footer { + border-top: 1px solid rgba(255, 255, 255, 0.06); +} diff --git a/apps/docs/src/pages/index.module.css b/apps/docs/src/pages/index.module.css index 3b6e81e46a..01afdf03b7 100644 --- a/apps/docs/src/pages/index.module.css +++ b/apps/docs/src/pages/index.module.css @@ -1,99 +1,520 @@ +/* ── Hero ── */ + .heroBanner { - padding: 6rem 0 4rem; - text-align: center; position: relative; + padding: 8rem 2rem 6rem; + text-align: center; overflow: hidden; - background: linear-gradient( - 180deg, - var(--ifm-color-primary-darkest) 0%, - var(--ifm-background-color) 100% + background: radial-gradient( + ellipse 80% 60% at 50% -10%, + rgba(99, 102, 241, 0.15) 0%, + transparent 70% + ), + var(--ifm-background-color); +} + +.heroBanner::before { + content: ""; + position: absolute; + inset: 0; + background: radial-gradient( + circle at 30% 80%, + rgba(129, 140, 248, 0.06) 0%, + transparent 50% ); + pointer-events: none; } .heroTitle { - font-size: 3rem; - font-weight: 800; - letter-spacing: -0.02em; - margin-bottom: 1rem; + font-size: 3.5rem; + font-weight: 700; + letter-spacing: -0.035em; + line-height: 1.1; + margin-bottom: 1.5rem; + background: linear-gradient( + 135deg, + #fff 0%, + rgba(255, 255, 255, 0.7) 100% + ); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; +} + +[data-theme="light"] .heroTitle { + background: linear-gradient( + 135deg, + #1a1a2e 0%, + #3730a3 100% + ); + -webkit-background-clip: text; + background-clip: text; } .heroSubtitle { - font-size: 1.25rem; - max-width: 640px; - margin: 0 auto 2rem; - color: var(--ifm-color-emphasis-700); - line-height: 1.6; + font-size: 1.15rem; + max-width: 560px; + margin: 0 auto 2.5rem; + color: rgba(255, 255, 255, 0.55); + line-height: 1.7; + font-weight: 400; +} + +[data-theme="light"] .heroSubtitle { + color: var(--ifm-color-emphasis-600); } .brandName { font-family: var(--ifm-font-family-monospace); - font-weight: 700; + font-weight: 600; color: var(--ifm-color-primary-light); letter-spacing: -0.01em; } +/* ── Buttons ── */ + .buttons { display: flex; align-items: center; justify-content: center; - gap: 1rem; - margin-top: 1.5rem; + gap: 0.75rem; + flex-wrap: wrap; } -.features { - display: flex; +.primaryBtn, +.secondaryBtn { + display: inline-flex; align-items: center; - padding: 3rem 0; + justify-content: center; + padding: 0.7rem 1.75rem; + border-radius: 9999px; + font-size: 0.925rem; + font-weight: 600; + text-decoration: none; + transition: all 0.2s ease; + cursor: pointer; + border: none; } -.sectionSubtext { +.primaryBtn { + background: var(--ifm-color-primary); + color: #fff; + box-shadow: 0 0 24px rgba(99, 102, 241, 0.25); +} + +.primaryBtn:hover { + background: var(--ifm-color-primary-dark); + box-shadow: 0 0 32px rgba(99, 102, 241, 0.4); + color: #fff; + text-decoration: none; + transform: translateY(-1px); +} + +.secondaryBtn { + background: rgba(255, 255, 255, 0.06); + color: rgba(255, 255, 255, 0.8); + border: 1px solid rgba(255, 255, 255, 0.1); +} + +.secondaryBtn:hover { + background: rgba(255, 255, 255, 0.1); + color: #fff; + text-decoration: none; + transform: translateY(-1px); +} + +[data-theme="light"] .secondaryBtn { + background: rgba(0, 0, 0, 0.04); + color: var(--ifm-color-emphasis-700); + border: 1px solid rgba(0, 0, 0, 0.12); +} + +[data-theme="light"] .secondaryBtn:hover { + background: rgba(0, 0, 0, 0.08); + color: var(--ifm-color-emphasis-900); +} + +/* ── Features ── */ + +.features { + padding: 5rem 2rem; + position: relative; +} + +.features::before { + content: ""; + position: absolute; + top: 0; + left: 50%; + transform: translateX(-50%); + width: min(100%, 800px); + height: 1px; + background: linear-gradient( + 90deg, + transparent 0%, + rgba(255, 255, 255, 0.08) 50%, + transparent 100% + ); +} + +[data-theme="light"] .features::before { + background: linear-gradient( + 90deg, + transparent 0%, + rgba(0, 0, 0, 0.08) 50%, + transparent 100% + ); +} + +.featureGrid { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 1.25rem; + max-width: 1100px; + margin: 0 auto; +} + +.featureCard { + padding: 1.75rem; + border-radius: 16px; + background: rgba(255, 255, 255, 0.03); + border: 1px solid rgba(255, 255, 255, 0.06); + transition: all 0.25s ease; +} + +.featureCard:hover { + background: rgba(255, 255, 255, 0.05); + border-color: rgba(129, 140, 248, 0.2); + transform: translateY(-2px); +} + +[data-theme="light"] .featureCard { + background: rgba(0, 0, 0, 0.02); + border-color: rgba(0, 0, 0, 0.08); +} + +[data-theme="light"] .featureCard:hover { + background: rgba(0, 0, 0, 0.04); + border-color: var(--ifm-color-primary-lighter); +} + +.featureTitle { + font-size: 1.05rem; + font-weight: 600; + margin-bottom: 0.6rem; + color: var(--ifm-color-primary-light); +} + +[data-theme="light"] .featureTitle { + color: var(--ifm-color-primary-dark); +} + +.featureDesc { + font-size: 0.9rem; + line-height: 1.6; + color: rgba(255, 255, 255, 0.5); + margin: 0; +} + +[data-theme="light"] .featureDesc { color: var(--ifm-color-emphasis-600); - max-width: 600px; } +/* ── Code Showcase ── */ + .codeShowcase { - padding: 2rem 0 4rem; + padding: 4rem 2rem 5rem; + position: relative; } -.codeStep { - margin-bottom: 2rem; +.codeShowcase::before { + content: ""; + position: absolute; + top: 0; + left: 50%; + transform: translateX(-50%); + width: min(100%, 800px); + height: 1px; + background: linear-gradient( + 90deg, + transparent 0%, + rgba(255, 255, 255, 0.08) 50%, + transparent 100% + ); } -.codeStepLabel { - display: flex; - align-items: center; - gap: 0.75rem; - font-size: 1.1rem; - font-weight: 600; - margin-bottom: 0.75rem; - color: var(--ifm-color-emphasis-800); +[data-theme="light"] .codeShowcase::before { + background: linear-gradient( + 90deg, + transparent 0%, + rgba(0, 0, 0, 0.08) 50%, + transparent 100% + ); } -.codeStepNumber { - display: inline-flex; - align-items: center; +.sectionTitle { + font-size: 2rem; + font-weight: 700; + letter-spacing: -0.02em; + text-align: center; + margin-bottom: 0.5rem; +} + +.sectionSubtext { + text-align: center; + color: rgba(255, 255, 255, 0.45); + max-width: 520px; + margin: 0 auto 2.5rem; + font-size: 0.95rem; + line-height: 1.6; +} + +[data-theme="light"] .sectionSubtext { + color: var(--ifm-color-emphasis-500); +} + +.tabBar { + display: flex; justify-content: center; - width: 1.75rem; - height: 1.75rem; - border-radius: 50%; + gap: 0.25rem; + margin-bottom: 1.5rem; + padding: 0.25rem; + background: rgba(255, 255, 255, 0.04); + border-radius: 12px; + width: fit-content; + margin-left: auto; + margin-right: auto; + border: 1px solid rgba(255, 255, 255, 0.06); +} + +[data-theme="light"] .tabBar { + background: rgba(0, 0, 0, 0.04); + border-color: rgba(0, 0, 0, 0.08); +} + +.tab { + padding: 0.5rem 1.25rem; + border-radius: 9px; + font-size: 0.875rem; + font-weight: 500; + cursor: pointer; + border: none; + background: transparent; + color: rgba(255, 255, 255, 0.45); + transition: all 0.2s ease; +} + +.tab:hover { + color: rgba(255, 255, 255, 0.7); +} + +[data-theme="light"] .tab { + color: var(--ifm-color-emphasis-500); +} + +[data-theme="light"] .tab:hover { + color: var(--ifm-color-emphasis-700); +} + +.tabActive { background: var(--ifm-color-primary); - color: #fff; + color: #fff !important; + box-shadow: 0 2px 8px rgba(99, 102, 241, 0.3); +} + +[data-theme="light"] .tabActive { + color: #fff !important; +} + +.codeWrapper { + max-width: 800px; + margin: 0 auto; + border-radius: 12px; + overflow: hidden; +} + +.codeWrapper pre { + border-radius: 12px !important; + border: 1px solid rgba(255, 255, 255, 0.06) !important; +} + +[data-theme="light"] .codeWrapper pre { + border-color: rgba(0, 0, 0, 0.08) !important; +} + +.codeCaption { + text-align: center; + margin-top: 1rem; font-size: 0.85rem; - font-weight: 700; - flex-shrink: 0; + color: rgba(255, 255, 255, 0.35); } +[data-theme="light"] .codeCaption { + color: var(--ifm-color-emphasis-400); +} + +/* ── CTA ── */ + .ctaSection { - padding: 4rem 0 5rem; - border-top: 1px solid var(--ifm-color-emphasis-200); + padding: 5rem 2rem; + text-align: center; + position: relative; +} + +.ctaSection::before { + content: ""; + position: absolute; + top: 0; + left: 50%; + transform: translateX(-50%); + width: min(100%, 800px); + height: 1px; + background: linear-gradient( + 90deg, + transparent 0%, + rgba(255, 255, 255, 0.08) 50%, + transparent 100% + ); +} + +[data-theme="light"] .ctaSection::before { + background: linear-gradient( + 90deg, + transparent 0%, + rgba(0, 0, 0, 0.08) 50%, + transparent 100% + ); +} + +.ctaTitle { + font-size: 2rem; + font-weight: 700; + letter-spacing: -0.02em; + margin-bottom: 0.75rem; +} + +.ctaSubtext { + color: rgba(255, 255, 255, 0.45); + max-width: 440px; + margin: 0 auto 2rem; + font-size: 0.95rem; + line-height: 1.6; +} + +[data-theme="light"] .ctaSubtext { + color: var(--ifm-color-emphasis-500); +} + +/* ── Responsive ── */ + +@media (max-width: 996px) { + .featureGrid { + grid-template-columns: repeat(2, 1fr); + } } @media (max-width: 768px) { + .heroBanner { + padding: 5rem 1.5rem 4rem; + } + .heroTitle { - font-size: 2.2rem; + font-size: 2rem; + letter-spacing: -0.03em; } .heroSubtitle { - font-size: 1.1rem; + font-size: 1rem; + margin-bottom: 2rem; + } + + .buttons { + flex-direction: column; + gap: 0.6rem; + } + + .primaryBtn, + .secondaryBtn { + width: 100%; + max-width: 280px; + } + + .features { + padding: 3rem 1.5rem; + } + + .featureGrid { + grid-template-columns: 1fr; + gap: 1rem; + } + + .featureCard { + padding: 1.5rem; + } + + .codeShowcase { + padding: 3rem 1rem 4rem; + } + + .sectionTitle { + font-size: 1.6rem; + } + + .tabBar { + width: 100%; + max-width: 360px; + } + + .tab { + padding: 0.45rem 0.9rem; + font-size: 0.8rem; + } + + .ctaSection { + padding: 3.5rem 1.5rem; + } + + .ctaTitle { + font-size: 1.6rem; + } +} + +@media (max-width: 480px) { + .heroBanner { + padding: 4rem 1.25rem 3rem; + } + + .heroTitle { + font-size: 1.7rem; + } + + .heroSubtitle { + font-size: 0.925rem; + } + + .featureCard { + padding: 1.25rem; + } + + .featureTitle { + font-size: 0.95rem; + } + + .featureDesc { + font-size: 0.85rem; + } + + .codeShowcase { + padding: 2.5rem 0.75rem 3rem; + } + + .tabBar { + gap: 0.15rem; + padding: 0.2rem; + } + + .tab { + padding: 0.4rem 0.7rem; + font-size: 0.75rem; } } diff --git a/apps/docs/src/pages/index.tsx b/apps/docs/src/pages/index.tsx index de78fb1b00..5979aace90 100644 --- a/apps/docs/src/pages/index.tsx +++ b/apps/docs/src/pages/index.tsx @@ -1,4 +1,4 @@ -import clsx from "clsx"; +import { useState } from "react"; import Link from "@docusaurus/Link"; import Layout from "@theme/Layout"; import Heading from "@theme/Heading"; @@ -6,48 +6,17 @@ import CodeBlock from "@theme/CodeBlock"; import styles from "./index.module.css"; -function HomepageHeader() { - return ( -
-
- - Stop wiring. Start building. - -

- flow-state.dev is a TypeScript framework that turns AI orchestration, - streaming, state, and error handling into composable primitives — - so you can focus on what your AI actually does. -

-
- - Get Started - - - Why flow-state.dev? - -
-
-
- ); -} +/* ── Code examples ── */ -const defineFlowExample = `import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; +const defineExample = `import { defineFlow, generator, sequencer } from "@flow-state-dev/core"; -// Any block or sequence of blocks can be used as a tool. -// This tool is a full multi-step pipeline. +// A tool that's a full multi-step pipeline — not a function wrapper const deepResearch = sequencer({ name: "deep-research" }) .then(searchIndex) .then(rankResults) .then(summarize); -// Resources give your AI a persistent workspace: text + structured state -// Think files with metadata, scoped to sessions, users, or projects. +// Resources: hybrid memory — text content + structured state const docResource = { stateSchema: z.object({ byId: z.record(z.object({ @@ -55,12 +24,10 @@ const docResource = { content: z.string(), // Rich text — the "file" part tags: z.array(z.string()), // Structured state — the "metadata" part })).default({}), - order: z.array(z.string()).default([]), }), writable: true, }; -// Pass any block as a tool — the framework compiles it for the LLM const agent = generator({ name: "agent", model: "gpt-5-mini", @@ -70,7 +37,6 @@ const agent = generator({ tools: [deepResearch, readDoc, writeDoc], }); -// Define the flow — this becomes a full API instantly export default defineFlow({ kind: "research-assistant", actions: { @@ -85,35 +51,30 @@ export default defineFlow({ }, })({ id: "default" });`; -const serverExample = `import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; +const serveExample = `import { createFlowRegistry, createFlowApiRouter } from "@flow-state-dev/server"; import researchFlow from "./flows/research-assistant"; import chatFlow from "./flows/chat"; const registry = createFlowRegistry(); registry.register(researchFlow); -registry.register(chatFlow); // Register as many flows as you need +registry.register(chatFlow); export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); -// Each flow is now a full API: actions, sessions, streaming, state snapshots. // POST /api/flows/research-assistant/actions/chat // GET /api/flows/research-assistant/requests/:id/stream // GET /api/flows/sessions/:id/state`; -const reactExample = `function ResearchApp() { +const renderExample = `function ResearchApp() { const flow = useFlow({ autoCreateSession: true }); const session = useSession(flow.activeSessionId); - - // Projections derive client-safe views from server-side resources const { session: proj } = useProjections(session, { session: ["docList"], }); return ( <> - {/* Items stream in real time as the AI works */} {session.items.map(item => )} - {/* Projection: derived from resource state, updated after each request */}
); } -function HomepageFeatures() { +function Features() { return (
-
-
- {FeatureList.map((props, idx) => ( - - ))} -
+
+ {features.map((f, i) => ( +
+
{f.title}
+

{f.description}

+
+ ))}
); } -type CodeTab = { - label: string; - code: string; - language: string; -}; - -const codeTabs: CodeTab[] = [ - { label: "Define", code: defineFlowExample, language: "ts" }, - { label: "Serve", code: serverExample, language: "ts" }, - { label: "Render", code: reactExample, language: "tsx" }, - { label: "Test", code: testExample, language: "ts" }, -]; +function CodeShowcase() { + const [active, setActive] = useState(0); + const tab = codeTabs[active]; -function HomepageCodeShowcase() { return (
-
-
-
- - From definition to UI in four steps - -

- Define your blocks and flows. Register with the server. Wire up React hooks. Write deterministic tests. Each layer is independent and composable. -

- {codeTabs.map((tab, idx) => ( -
-
- {idx + 1} - {tab.label} -
- {tab.code} -
- ))} -
-
+ + From definition to UI in four steps + +

+ Define blocks. Register flows. Wire up React. Write deterministic tests. Each layer is independent and composable. +

+ +
+ {codeTabs.map((t, i) => ( + + ))} +
+ +
+ {tab.code}
+

{tab.caption}

); } -function HomepageCTA() { +function CTA() { return (
-
- Ready to build? -

- Get a streaming chat app running in under 5 minutes. No boilerplate. No plumbing. -

-
- - Quick Start Guide - -
+ + Ready to explore? + +

+ Get a streaming AI app running in minutes. Then push it somewhere no framework has gone before. +

+
+ + Quick Start + + + Read the Manifesto +
); } +/* ── Page ── */ + export default function Home(): React.ReactElement { return ( - +
- - - + + +
); From 01be5822818955d9e650fa96b68356524c2d093d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 18:48:46 +0000 Subject: [PATCH 08/15] Show component item model in landing page examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Blocks don't send outputs to the client — they emit typed items. Updated Define example to show ctx.emitComponent() with a handler that emits a named "report-card" component. Updated Render example to show FlowProvider with registered component renderers and how ItemRenderer resolves component items from the stream. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh --- apps/docs/src/pages/index.tsx | 67 ++++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 24 deletions(-) diff --git a/apps/docs/src/pages/index.tsx b/apps/docs/src/pages/index.tsx index 5979aace90..d7fca85ad3 100644 --- a/apps/docs/src/pages/index.tsx +++ b/apps/docs/src/pages/index.tsx @@ -8,7 +8,7 @@ import styles from "./index.module.css"; /* ── Code examples ── */ -const defineExample = `import { defineFlow, generator, sequencer } from "@flow-state-dev/core"; +const defineExample = `import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core"; // A tool that's a full multi-step pipeline — not a function wrapper const deepResearch = sequencer({ name: "deep-research" }) @@ -16,17 +16,20 @@ const deepResearch = sequencer({ name: "deep-research" }) .then(rankResults) .then(summarize); -// Resources: hybrid memory — text content + structured state -const docResource = { - stateSchema: z.object({ - byId: z.record(z.object({ - title: z.string(), - content: z.string(), // Rich text — the "file" part - tags: z.array(z.string()), // Structured state — the "metadata" part - })).default({}), - }), - writable: true, -}; +// Blocks emit component items — structured data for the UI +const analyze = handler({ + name: "analyze", + execute: async (input, ctx) => { + const report = await buildReport(input); + const component = ctx.emitComponent("report-card", { + title: report.title, + findings: report.findings, + confidence: report.score, + }); + component.done(); + return report; + }, +}); const agent = generator({ name: "agent", @@ -34,7 +37,7 @@ const agent = generator({ prompt: "You are a research assistant.", history: (_input, ctx) => ctx.session.items.llm(), user: (input) => input.message, - tools: [deepResearch, readDoc, writeDoc], + tools: [deepResearch, analyze, readDoc, writeDoc], }); export default defineFlow({ @@ -64,22 +67,38 @@ export const { GET, POST, DELETE } = createFlowApiRouter({ registry }); // GET /api/flows/research-assistant/requests/:id/stream // GET /api/flows/sessions/:id/state`; -const renderExample = `function ResearchApp() { +const renderExample = `// Register component renderers — the UI counterpart to ctx.emitComponent() +function ReportCard({ item }: { item: ComponentItem }) { + const { title, findings, confidence } = item.data; + return ( +
+

{title}

+
    {findings.map(f =>
  • {f}
  • )}
+ +
+ ); +} + +function App() { + return ( + + + + ); +} + +function ResearchApp() { const flow = useFlow({ autoCreateSession: true }); const session = useSession(flow.activeSessionId); - const { session: proj } = useProjections(session, { - session: ["docList"], - }); return ( <> + {/* ItemRenderer resolves component items to registered renderers */} {session.items.map(item => )} - -