@falai/agent 1.2.7 → 2.0.0

package/docs/guides/persistence.md

@@ -0,0 +1,182 @@
+---
+title: "Persistence"
+description: "Swap the in-memory default for a durable adapter so sessions survive restarts and span processes."
+type: guide
+order: 5
+---
+
+# Persistence
+
+By default, `createAgent` runs against an in-process `MemoryAdapter`. That is the right choice while you are building — zero setup, instant resets between tests — but it forgets every conversation the moment the process exits. Production needs storage that outlives a deploy, scales to multiple replicas, and lets a session resume by id from any machine.
+
+This guide covers the swap. You will pick an adapter, wire it through `persistence`, resume sessions by `sessionId`, and run the v1 → v2 schema migration if you are upgrading an existing store.
+
+## The seven adapters
+
+`@falai/agent` ships seven adapters. Every one implements the same `PersistenceAdapter` interface, so the swap is one field on `createAgent`.
+
+| Adapter | When to reach for it |
+|---------|---------------------|
+| [`MemoryAdapter`](../reference/adapters.md#memoryadapter) | The implicit default. Tests, prototypes, single-process demos. |
+| [`PrismaAdapter`](../reference/adapters.md#prismaadapter) | You already use Prisma; want a typed schema. |
+| [`RedisAdapter`](../reference/adapters.md#redisadapter) | Fast, ephemeral, TTL-driven session storage. |
+| [`MongoAdapter`](../reference/adapters.md#mongoadapter) | Document-shape; flexible session payloads. |
+| [`PostgreSQLAdapter`](../reference/adapters.md#postgresqladapter) | Single SQL backend without an ORM. |
+| [`SQLiteAdapter`](../reference/adapters.md#sqliteadapter) | Local dev, single-node deploys, CLI tools. |
+| [`OpenSearchAdapter`](../reference/adapters.md#opensearchadapter) | Searchable session and message archive. |
+
+The full per-option contract for every adapter lives in [persistence adapters](../reference/adapters.md). This page sticks to the moves you make once.
+
+## Recipe 1: Swap memory for Prisma
+
+The fastest path to a real database. Add Prisma, declare the session model, point the adapter at the generated client.
+
+**1. Install Prisma.**
+
+```bash
+bun add @prisma/client
+bun add -d prisma
+bunx prisma init
+```
+
+**2. Declare the session model.** Two columns matter most: `pendingDirective` and `signals`. The agent serializes its [`Directive`](../reference/directive.md) and signals state into them at the end of every turn and reads them back at the start of the next. Both are required on every adapter's session schema in v2.
+
+```prisma
+model AgentSession {
+  id                String    @id
+  userId            String?
+  status            String    @default("active")
+  currentFlow       String?
+  currentStep       String?
+  collectedData     Json?
+  pendingDirective  Json?
+  signals           Json?
+  messageCount      Int       @default(0)
+  lastMessageAt     DateTime?
+  completedAt       DateTime?
+  createdAt         DateTime  @default(now())
+  updatedAt         DateTime  @updatedAt
+}
+```
+
+**3. Push and generate.**
+
+```bash
+bunx prisma db push
+bunx prisma generate
+```
+
+**4. Wire the adapter.** Only one field changes on `createAgent` — every flow, step, tool, and instruction stays the same.
+
+```typescript
+import { PrismaClient } from "@prisma/client";
+import { createAgent, GeminiProvider, PrismaAdapter } from "@falai/agent";
+
+const prisma = new PrismaClient();
+
+export const agent = createAgent({
+  name: "BookingBot",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema,
+  flows,
+  persistence: {
+    adapter: new PrismaAdapter({ prisma }),
+    userId: "user_123",
+  },
+});
+```
+
+That is the whole swap. Every `agent.respond` call now reads and writes through Prisma instead of an in-process map.
+
+## Recipe 2: Resume a conversation with `sessionId`
+
+`sessionId` is the contract between client and server. The same id on every request keeps the user pinned to the same conversation; the adapter loads the right `pendingDirective` and `signals`, the agent picks up exactly where the last turn ended.
+
+There are two equivalent patterns — pick whichever fits your call site.
+
+**Construct-time.** Pass `sessionId` to `createAgent` and the engine auto-loads it at the start of the first turn:
+
+```typescript
+const agent = createAgent({
+  /* ...same as above... */
+  persistence: { adapter: new PrismaAdapter({ prisma }) },
+  sessionId: "user_123:thread_abc",
+});
+
+await agent.respond({ history: [{ role: "user", content: "Hi again" }] });
+```
+
+**Per-request.** Hydrate explicitly when the session id is only known at request time (typical HTTP server shape):
+
+```typescript
+const session = await agent.session.getOrCreate("user_123:thread_abc");
+
+const response = await agent.respond({
+  history: [{ role: "user", content: "Hi again" }],
+  session,
+});
+```
+
+`getOrCreate` returns the stored `SessionState` (collected data, flow position, `pendingDirective`, signals state) — or creates a fresh session with that id if nothing exists yet. Unknown ids are not an error path; they are the start of a new conversation pinned to that id.
+
+A practical id shape: `<userId>:<threadId>`. Keep it stable across restarts and replicas. The adapter does the rest.
+
+## Recipe 3: Redis for fast, ephemeral sessions
+
+Redis is the right pick when you want fast reads, automatic expiry, and do not need long-term archives — chat widgets, ephemeral copilots, anything where a session can reasonably TTL out after a day. The adapter writes JSON-serialized strings under prefixed keys; `pendingDirective` and `signals` ride along inside the session value transparently, so there is no schema to migrate.
+
+```typescript
+import Redis from "ioredis";
+import { createAgent, GeminiProvider, RedisAdapter } from "@falai/agent";
+
+const redis = new Redis(process.env.REDIS_URL!);
+
+export const agent = createAgent({
+  name: "BookingBot",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema,
+  flows,
+  persistence: {
+    adapter: new RedisAdapter({
+      redis,
+      keyPrefix: "myapp:agent:",
+      sessionTTL: 60 * 60 * 24, // 1 day
+      messageTTL: 60 * 60 * 24 * 7, // 1 week
+    }),
+    userId: "user_123",
+  },
+});
+```
+
+A few things worth noting:
+
+- `keyPrefix` namespaces every key the adapter writes — pick something app-specific so it coexists cleanly with other Redis tenants.
+- `sessionTTL` and `messageTTL` are seconds. Pass a large number to effectively disable expiry; default is 7 days for sessions, 30 days for messages.
+- Connection pooling and reconnect strategy come from your Redis client (`ioredis` or `node-redis`) — the adapter does not own them.
+
+If you need an archive of every session and message (audit logs, search, analytics), pair Redis with a second adapter on a slower path, or pick a durable adapter from the table above directly.
+
+## Schema migration: v1 → v2
+
+If you are upgrading an existing v1 store, the session schema needs two new columns before v2 runs against it:
+
+- **`pendingDirective`** — the persisted [`Directive`](../reference/directive.md) consumed at the start of the next turn. Replaces the v1 column for the same slot.
+- **`signals`** (new in v2) — the [signals](../reference/signals.md) runtime state. Required even if you do not use signals; v2 reads and writes it.
+
+Without these columns, v2 throws a driver-specific column-not-found error on the first write, and any v1 value in the old slot is silently dropped on read.
+
+The full migration steps per adapter — SQL `ALTER TABLE` for Postgres and SQLite, Prisma model diff, MongoDB `updateMany`, Redis Lua transform, OpenSearch `_reindex` script — live in the [v1 → v2 migration guide](../migration/v1-to-v2.md). Run those once against your store before deploying v2.
+
+For brand-new v2 deploys there is nothing to migrate. The `PostgreSQLAdapter`, `SQLiteAdapter`, and `OpenSearchAdapter` create v2-shaped tables and indices when you call `await adapter.initialize()` once on boot. The `PrismaAdapter` and `MongoAdapter` follow your declared schema. The `MemoryAdapter` and `RedisAdapter` need no DDL at all.
+
+## Verification
+
+A quick checklist after the swap:
+
+1. **Restart the process between turns** and confirm the session resumes — same flow, same step, same collected data.
+2. **Inspect the row.** `pendingDirective` and `signals` should be present (possibly `null`); `collectedData` should hold whatever fields the user has supplied so far.
+3. **Run two requests with the same `sessionId` from different processes** (e.g., two `curl` calls against your endpoint). The second turn should land at the right step without re-asking for collected fields.
+
+If any of these fails, the issue is almost always the schema — re-check the column names against [persistence adapters](../reference/adapters.md) for your adapter and run the [v1 → v2 migration](../migration/v1-to-v2.md) if applicable.
+
+**Next:** [Streaming](./streaming.md)

package/docs/guides/streaming.md

@@ -0,0 +1,137 @@
+---
+title: "Streaming"
+description: "Stream the assistant's reply token by token, surface tool calls in flight, and cancel mid-turn with an `AbortSignal`."
+type: guide
+order: 6
+---
+
+# Streaming
+
+`agent.respond` returns a single `AgentResponse` after the LLM and any tool calls have finished. That works for batch work, but a chat UI feels dead until the first character lands. `agent.respondStream` returns an `AsyncGenerator<AgentResponseStreamChunk>`, yielding the assistant's reply incrementally and finishing with one terminal chunk that carries all the metadata.
+
+This guide is a recipe: take a non-streaming call site, swap to `respondStream`, render tokens as they arrive, expose a "thinking" indicator while tools run, read instruction and signal telemetry off the final chunk, and wire an `AbortSignal` so the user can stop mid-turn.
+
+## The shape
+
+`respondStream` takes the same `RespondParams` as `respond` — `history`, optional `session`, optional `contextOverride`, optional `signal` — and returns an async iterable of chunks.
+
+```typescript
+const stream = agent.respondStream({
+  history: [{ role: "user", content: "Book me a hotel in Lisbon." }],
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.delta);
+}
+```
+
+Every chunk has the same shape:
+
+```typescript
+interface AgentResponseStreamChunk<TData> {
+  delta: string;        // Text added since the previous chunk
+  accumulated: string;  // Full text so far
+  done: boolean;        // True only on the terminal chunk
+  // ...metadata fields, populated on the final chunk
+}
+```
+
+`delta` is the new token(s); concatenating every `delta` reproduces the final reply. `accumulated` is the running total — useful when your renderer needs the full string each tick (e.g., a Markdown view that re-parses on every update). `done` flips to `true` exactly once, on the terminal chunk.
+
+## Render incrementally
+
+The simplest renderer prints every `delta` as it arrives and clears the line on `done`:
+
+```typescript
+for await (const chunk of agent.respondStream({ history })) {
+  if (chunk.delta) {
+    process.stdout.write(chunk.delta);
+  }
+  if (chunk.done) {
+    process.stdout.write("\n");
+  }
+}
+```
+
+For a UI, push the latest `accumulated` into your component state. React, Solid, Svelte — they all re-render off whichever value you give them, and `accumulated` is the cheapest to consume because it never requires the renderer to track partial state.
+
+A common rendering rule of thumb:
+
+- Plain text view → append `delta`.
+- Markdown view that re-parses each frame → bind to `accumulated`.
+- Server-Sent Events transport → forward `{ delta, done }` per chunk; let the client reassemble.
+
+## Surface tool calls in flight
+
+Streaming works through tool calls transparently. When the LLM emits a tool call mid-reply, `respondStream` runs the tool, then resumes streaming the post-tool tokens — the consumer never sees the call boundary in the text. What you do get is a quiet gap while the tool executes, which is the right moment to show a "thinking" indicator.
+
+Detect the gap by watching for empty `delta` chunks after some text has already arrived, or — more robustly — toggle the indicator off as soon as the first non-empty `delta` lands:
+
+```typescript
+let thinking = true;
+let firstToken = true;
+
+for await (const chunk of agent.respondStream({ history })) {
+  if (chunk.delta) {
+    if (firstToken) {
+      thinking = false;
+      firstToken = false;
+      ui.hideSpinner();
+    }
+    ui.appendText(chunk.delta);
+  }
+}
+```
+
+If you need finer-grained tool telemetry — which tool fired, with what arguments — read `chunk.toolCalls` on the terminal chunk. It mirrors the same field on the non-streaming `AgentResponse`. For per-tool progress UI, attach observability to the [tool's `handler`](../reference/tool.md) directly; the streaming chunk shape stays clean.
+
+When a step uses [verbatim `reply`](../reference/step.md) or a [`halt` directive](../reference/pre-directive.md), the engine skips the LLM entirely and yields a single chunk with `done: true` and the full text in `accumulated`. The renderer above handles that case without a special branch — there is just no spinner gap.
+
+## The terminal chunk
+
+The chunk where `done: true` carries every observability field that lives on `AgentResponse`. Three matter for most call sites:
+
+```typescript
+for await (const chunk of agent.respondStream({ history })) {
+  // ...render delta...
+  if (chunk.done) {
+    console.log("flow complete:", chunk.isFlowComplete);
+    console.log("instructions rendered:", chunk.appliedInstructions);
+    console.log("signals fired:", chunk.triggeredSignals);
+  }
+}
+```
+
+- **`appliedInstructions`** — the [instructions](../reference/instruction.md) whose conditions passed and were rendered into this turn's prompt. Deterministic; derived from rendering, not from LLM self-report. Empty on intermediate chunks; populated only when `done: true`.
+- **`triggeredSignals`** — the [signals](../reference/signals.md) that fired during this turn (pre- and post-phase), in fire order. Same population rule.
+- **`isFlowComplete`** — `true` when this turn finished the flow. Use it to decide whether to clear the conversation, show a summary card, or transition the UI.
+
+The terminal chunk also carries `executedSteps`, `stoppedReason`, `metadata` (model, token usage), and the updated `session`. These are the same fields you would read off `AgentResponse` — swapping between APIs does not change observability.
+
+## Cancel mid-stream
+
+Pass an `AbortSignal` through `respondStream` and abort the controller to cancel. The generator stops yielding, the in-flight LLM call is cancelled at the provider boundary, and any tool execution unwinds cleanly.
+
+```typescript
+const controller = new AbortController();
+
+// User clicks Stop, or a 5s ceiling fires.
+const timer = setTimeout(() => controller.abort(), 5000);
+
+try {
+  for await (const chunk of agent.respondStream({
+    history,
+    signal: controller.signal,
+  })) {
+    process.stdout.write(chunk.delta);
+  }
+} finally {
+  clearTimeout(timer);
+}
+```
+
+When the signal aborts, the loop exits cleanly — no exception is thrown by the generator itself. If the LLM provider surfaces the cancellation as an error, it lands as a [`ResponseGenerationError`](../reference/errors.md) and you handle it the way you would any other turn-level error.
+
+For a Stop button, store the `controller` reference for the active stream on the UI side and call `controller.abort()` from the click handler. For server-side hard ceilings, wrap `respondStream` with an `AbortController` whose `setTimeout` fires at your SLO budget.
+
+**Next:** [Errors](./error-handling.md)

package/docs/migration/README.md

@@ -0,0 +1,15 @@
+# Migration
+
+Migration guides for upgrading `@falai/agent`.
+
+## v1 → v2
+
+Use this guide when upgrading from any `1.x` release to `2.0`. It covers every breaking change in v2, with rename tables and before/after code.
+
+[Read the v1 → v2 migration guide](./v1-to-v2.md)
+
+## Route → Flow rename
+
+Use this guide if you are landing the minor release that ships just before `2.0`, which renames the `Route` domain noun to `Flow` across symbols, config, and persistence.
+
+[Read the Route → Flow guide](./route-to-flow.md)