Packages

@flue/runtime

2.3.1 · 18 Nov 2026Apache-2.0524.4k / weekRepositoryHomepagenpmAtom feed

Your version

2.0.0

major31 Jul 2026Where it was published

2.3.1 is the newest release of 2.x.

In short

33 breaking18 new43 fixed

  • Breaking

    Flue is now a Vite plugin — flue dev and flue build are removed. Adopt Flue by adding flue() from the new @flue/vite package to vite.config.ts; vite dev and vite build own the deployable application. The Node target emits dist/server.mjs (run it with node dist/server.mjs; vite preview for Node is deferred). The Cloudflare target is the official @cloudflare/vite-plugin as an explicit sibling — plugins: [flue(), cloudflare({ config: flueWorkerConfig() })] — with the target auto-detected from cloudflare()'s presence; wrangler.jsonc stays user-owned, and Flue's contributions (the generated Worker entry, served as the virtual:flue/worker module, and the per-agent Durable Object bindings) are applied in memory by the flueWorkerConfig() customizer — nothing is generated into the project tree. flue.config.ts survives as the host-independent project config: defineConfig moves to @flue/runtime/config (the @flue/cli/config export is removed), the accepted fields are target, app, db, cloudflare, agents (a glob narrowing the 'use agent' scan), providers, and tracing, and the root/output fields and named vite export are dropped. See the migration guide for the full before/after.

  • Breaking

    File-based routing is removed — app.ts is the route map. The src/agents/*, src/workflows/*, and src/channels/* directory conventions no longer create routes or registrations. An agent module joins the application through the 'use agent' directive (the module's first statement); the build scans source files for the directive and registers every capitalized exported function as an agent, deriving each agent's durable storage identity from the exported function's name — or an agentName static pinning it — never from the file (on Cloudflare, one generated Flue<PascalName>Agent Durable Object class per exported agent function; renaming an unpinned function is the storage-identity change, expressed with wrangler-native renamed_classes, and colliding identities are a build error — renaming the file changes nothing). Every HTTP route is mounted explicitly in app.ts: app.route('/agents/triage', createAgentRouter(Triage)) for agents (createAgentRouter from @flue/runtime/routing), app.route('/channels/slack', slack.route()) for channels (hand-rolled channels mount via createChannelRouter). The router factory is pure and side-effect-free — registration comes from the scan, so dispatch-only agents need no mount, and the same agent can be mounted at two URLs. The agent module's named exports route (middleware), attachments, and description are removed along with the convention that read them: protect a mount with ordinary middleware layered in app.ts before it, and the attachment byte route is part of every agent router rather than opt-in. createDefaultFlueApp() and the runtime flue() router are removed; a missing app.ts is a build error.

  • Breaking

    Workflows are removed. defineWorkflow, invoke, run stores and run event streams, the /runs/:runId and POST /workflows/:name routes (including ?wait=result), listRuns/getRun, the SDK client.workflows/client.runs namespaces, the React workflow hooks, and the dev-console run UI are all deleted, with no compatibility stubs. Conversations are the only durable unit: a workflow becomes a program that drives an agent — flue run in a shell or CI step, the start()/init() JS API from Node, the Agent SDK over HTTP, or an external durable-workflow engine (Cloudflare Workflows, Inngest, Temporal) that checkpoints the dispatch receipt in one step and reads the settled reply in another. A deterministic code-first entrypoint (the old no-model run() body) has no direct replacement. The migration guide covers the conversion.

  • Breaking

    Agent authoring is rewritten: an agent is a plain exported function configured with hooks, and defineAgent is removed. A beta agent was a defineAgent(initializer) default export whose initializer returned a config object (model, instructions, tools, actions, skills, subagents, sandbox, …); now the capitalized exported function in a 'use agent' module is the agent. It runs fresh before every model call (a render), its return string is the instruction document, and everything else is declared by calling hooks during the render: useModel(model, { thinkingLevel?, compaction? }) (required, exactly once — the old model/thinkingLevel/compaction config fields), useInstruction(text), useTool(tool), useSkill(skill), useSubagent(subagent), useMcpConnection(definition), useSandbox(factory, { cwd? }), usePersistentState(name, default?) (durable per-instance state with React-style functional updates), useInitialData() (instance-creation data), useDelivery() (the delivered message in front of the model), useDataWriter(name, { schema }) (named client-facing data parts), useDispatchMessage() (an instance-bound dispatcher), and the lifecycle and response-boundary hooks useAgentStart(run), useAgentFinish(run) (whose ctx.append can send the model back to work in the same response), useResponseStart(fn), and useResponseFinish(fn) (response metadata). Because the render re-runs each turn, declarations may be conditional: a tool, skill, subagent, MCP connection, or sandbox that appears or disappears between renders takes effect at the next turn boundary and is narrated to the model as a structured delta signal. Custom hooks are ordinary use* functions — composition needs no registration. The contract the platform reads without running the function lives in statics on the function itself: agentName (the durable-identity override), initialData (a Valibot schema for creation data), and durability ({ maxAttempts, timeoutMs }, previously a config field). Deleted with the old model: defineAgent, createAgent, defineAgentProfile and AgentProfile, and the whole Actions surface (defineAction, the actions: [...] list, and their error types) — a model-invoked job is a useTool tool now, with harness: true for one that needs to prompt the harness. Subagents are declared values too: useSubagent(defineSubagent({ name, description, agent, model?, thinkingLevel? })) renders a delegate for the always-present task tool, GeneralSubagent is the exported general-purpose delegate, and a task call can only name a declared subagent. See the migration guide.

  • Breaking

    The tool run() context and the harness are reshaped. ToolContext is now { toolCallId, log, signal? } plus data — the schema-parsed arguments, renamed from input — when the tool declares an input schema, harness when it declares harness: true, and step when it declares durable: true; every tool gets log for structured progress events. The harness handed to harness: true tools and to the useAgentStart/useAgentFinish contexts flattens to { name, prompt(), compact(), sandbox }: session(), sessions, shell(), and fs are removed, and harness.sandbox is the live SessionEnv (exec, readFile, writeFile, stat, readdir, mkdir, rm, …), present only when the agent declared a sandbox. The six built-in tools (bash, read, write, edit, grep, glob) are composable per-tool factories (createBashTool(env), createReadTool(env), …) that a SandboxFactory's optional tools() can reassemble, extend, or replace wholesale.

  • Breaking

    Sandboxes are opt-in: an agent that declares no useSandbox() has no execution environment. The beta gave every agent an implicit in-memory virtual sandbox with full network access; now the six built-in shell/filesystem tools are added only when the render declares a sandbox, harness.sandbox and workspace-skill reads throw a clear declare-a-sandbox error otherwise, and workspace discovery contributes nothing to the prompt. Framework tools — task, activate_skill, packaged-skill reads — are environment-independent, so skills and subagents work sandbox-less. useSandbox(factory, { cwd? }) is the only way to attach an environment: local() (@flue/runtime/node) runs commands on the host, cloudflareSandbox(stub) (@flue/runtime/cloudflare) runs them in a Cloudflare Sandbox container, and the beta default's equivalent is useSandbox(bash(() => new Bash({ fs: new InMemoryFs() }))) with just-bash added to your own dependencies — the same you-import-the-library pattern as model providers. The declaration is submission-scoped and may be conditional: presence is re-read at every turn boundary, and a flip attaches or detaches the environment before the next model call, announced to the model as one full environment signal (new cwd, complete tool roster, a warning that the previous environment's files may be inaccessible). Not constructing the default environment also slims deploys that never opted in: the cloudflare example's main chunk drops from 5,481 kB to 3,482 kB.

  • Breaking

    Skill and markdown imports drop their import attributes — the specifier decides. Importing a path that resolves to a SKILL.md packages that skill directory at build time and yields a SkillReference for useSkill(...) (static imports only; frontmatter validated against the Agent Skills spec); importing any other .md file yields the markdown text as a plain string, which defineSkill({ name, description, instructions }) turns into a skill. The with { type: 'skill' } and with { type: 'markdown' } attribute forms are removed. defineSkill now validates and freezes instead of packaging — instructions is required, packaging happens lazily, and the runtime writes the frontmatter — and useSkill(...) accepts a SkillReference or a SkillDefinition directly. Manual skill invocation is gone: skills mount into the agent's disclosure catalog (or join it via workspace discovery under a sandbox's .agents/skills/), and the model activates them through the framework's activate_skill tool.

  • Breaking

    MCP servers are declared as connection definitions; connectMcpServer is removed. One flat McpConnectionDefinition ({ name, url, transport?, auth?, headers?, tools?, optional?, timeoutMs?, … }) drives the whole surface: useMcpConnection(definition) declares a server from the agent render — its tools mount as mcp__<server>__<tool>, read once per submission and cached per agent instance — defineMcpConnection(definition) is the validating, freezing typing helper for the exportable unit (spread it for per-mount overrides), and createMcpConnection(definition) is the imperative factory replacing the beta's connectMcpServer(name, options) for module-scope use on the Node target (McpServerConnection is renamed McpConnection). New in the definition: auth — a static bearer token or a function resolved freshly on every request, the seam for per-user and rotating credentials (a 401 retries once after the credential resolver is consulted); tools — an allowlist by the server's own tool names, where a name the server doesn't expose is a hard error; and optional: true — a server that fails to resolve mounts zero tools for that submission instead of failing it, announced to the model once as a resources signal naming each unavailable server and surfaced to observers as a warning event (failures are never cached, so the next submission retries). Underneath, the adapter runs on the v2 MCP SDK (@modelcontextprotocol/client, a direct dependency of @flue/runtime): structured tool output is validated by the client itself with a workerd-compatible validator, and existing v1 servers interoperate unchanged.

Release note

Breaking Changes

  • Breaking

    Flue is now a Vite plugin — flue dev and flue build are removed. Adopt Flue by adding flue() from the new @flue/vite package to vite.config.ts; vite dev and vite build own the deployable application. The Node target emits dist/server.mjs (run it with node dist/server.mjs; vite preview for Node is deferred). The Cloudflare target is the official @cloudflare/vite-plugin as an explicit sibling — plugins: [flue(), cloudflare({ config: flueWorkerConfig() })] — with the target auto-detected from cloudflare()'s presence; wrangler.jsonc stays user-owned, and Flue's contributions (the generated Worker entry, served as the virtual:flue/worker module, and the per-agent Durable Object bindings) are applied in memory by the flueWorkerConfig() customizer — nothing is generated into the project tree. flue.config.ts survives as the host-independent project config: defineConfig moves to @flue/runtime/config (the @flue/cli/config export is removed), the accepted fields are target, app, db, cloudflare, agents (a glob narrowing the 'use agent' scan), providers, and tracing, and the root/output fields and named vite export are dropped. See the migration guide for the full before/after.

  • Breaking

    File-based routing is removed — app.ts is the route map. The src/agents/*, src/workflows/*, and src/channels/* directory conventions no longer create routes or registrations. An agent module joins the application through the 'use agent' directive (the module's first statement); the build scans source files for the directive and registers every capitalized exported function as an agent, deriving each agent's durable storage identity from the exported function's name — or an agentName static pinning it — never from the file (on Cloudflare, one generated Flue<PascalName>Agent Durable Object class per exported agent function; renaming an unpinned function is the storage-identity change, expressed with wrangler-native renamed_classes, and colliding identities are a build error — renaming the file changes nothing). Every HTTP route is mounted explicitly in app.ts: app.route('/agents/triage', createAgentRouter(Triage)) for agents (createAgentRouter from @flue/runtime/routing), app.route('/channels/slack', slack.route()) for channels (hand-rolled channels mount via createChannelRouter). The router factory is pure and side-effect-free — registration comes from the scan, so dispatch-only agents need no mount, and the same agent can be mounted at two URLs. The agent module's named exports route (middleware), attachments, and description are removed along with the convention that read them: protect a mount with ordinary middleware layered in app.ts before it, and the attachment byte route is part of every agent router rather than opt-in. createDefaultFlueApp() and the runtime flue() router are removed; a missing app.ts is a build error.

  • Breaking

    Workflows are removed. defineWorkflow, invoke, run stores and run event streams, the /runs/:runId and POST /workflows/:name routes (including ?wait=result), listRuns/getRun, the SDK client.workflows/client.runs namespaces, the React workflow hooks, and the dev-console run UI are all deleted, with no compatibility stubs. Conversations are the only durable unit: a workflow becomes a program that drives an agent — flue run in a shell or CI step, the start()/init() JS API from Node, the Agent SDK over HTTP, or an external durable-workflow engine (Cloudflare Workflows, Inngest, Temporal) that checkpoints the dispatch receipt in one step and reads the settled reply in another. A deterministic code-first entrypoint (the old no-model run() body) has no direct replacement. The migration guide covers the conversion.

  • Breaking

    Agent authoring is rewritten: an agent is a plain exported function configured with hooks, and defineAgent is removed. A beta agent was a defineAgent(initializer) default export whose initializer returned a config object (model, instructions, tools, actions, skills, subagents, sandbox, …); now the capitalized exported function in a 'use agent' module is the agent. It runs fresh before every model call (a render), its return string is the instruction document, and everything else is declared by calling hooks during the render: useModel(model, { thinkingLevel?, compaction? }) (required, exactly once — the old model/thinkingLevel/compaction config fields), useInstruction(text), useTool(tool), useSkill(skill), useSubagent(subagent), useMcpConnection(definition), useSandbox(factory, { cwd? }), usePersistentState(name, default?) (durable per-instance state with React-style functional updates), useInitialData() (instance-creation data), useDelivery() (the delivered message in front of the model), useDataWriter(name, { schema }) (named client-facing data parts), useDispatchMessage() (an instance-bound dispatcher), and the lifecycle and response-boundary hooks useAgentStart(run), useAgentFinish(run) (whose ctx.append can send the model back to work in the same response), useResponseStart(fn), and useResponseFinish(fn) (response metadata). Because the render re-runs each turn, declarations may be conditional: a tool, skill, subagent, MCP connection, or sandbox that appears or disappears between renders takes effect at the next turn boundary and is narrated to the model as a structured delta signal. Custom hooks are ordinary use* functions — composition needs no registration. The contract the platform reads without running the function lives in statics on the function itself: agentName (the durable-identity override), initialData (a Valibot schema for creation data), and durability ({ maxAttempts, timeoutMs }, previously a config field). Deleted with the old model: defineAgent, createAgent, defineAgentProfile and AgentProfile, and the whole Actions surface (defineAction, the actions: [...] list, and their error types) — a model-invoked job is a useTool tool now, with harness: true for one that needs to prompt the harness. Subagents are declared values too: useSubagent(defineSubagent({ name, description, agent, model?, thinkingLevel? })) renders a delegate for the always-present task tool, GeneralSubagent is the exported general-purpose delegate, and a task call can only name a declared subagent. See the migration guide.

  • Breaking

    The tool run() context and the harness are reshaped. ToolContext is now { toolCallId, log, signal? } plus data — the schema-parsed arguments, renamed from input — when the tool declares an input schema, harness when it declares harness: true, and step when it declares durable: true; every tool gets log for structured progress events. The harness handed to harness: true tools and to the useAgentStart/useAgentFinish contexts flattens to { name, prompt(), compact(), sandbox }: session(), sessions, shell(), and fs are removed, and harness.sandbox is the live SessionEnv (exec, readFile, writeFile, stat, readdir, mkdir, rm, …), present only when the agent declared a sandbox. The six built-in tools (bash, read, write, edit, grep, glob) are composable per-tool factories (createBashTool(env), createReadTool(env), …) that a SandboxFactory's optional tools() can reassemble, extend, or replace wholesale.

  • Breaking

    Sandboxes are opt-in: an agent that declares no useSandbox() has no execution environment. The beta gave every agent an implicit in-memory virtual sandbox with full network access; now the six built-in shell/filesystem tools are added only when the render declares a sandbox, harness.sandbox and workspace-skill reads throw a clear declare-a-sandbox error otherwise, and workspace discovery contributes nothing to the prompt. Framework tools — task, activate_skill, packaged-skill reads — are environment-independent, so skills and subagents work sandbox-less. useSandbox(factory, { cwd? }) is the only way to attach an environment: local() (@flue/runtime/node) runs commands on the host, cloudflareSandbox(stub) (@flue/runtime/cloudflare) runs them in a Cloudflare Sandbox container, and the beta default's equivalent is useSandbox(bash(() => new Bash({ fs: new InMemoryFs() }))) with just-bash added to your own dependencies — the same you-import-the-library pattern as model providers. The declaration is submission-scoped and may be conditional: presence is re-read at every turn boundary, and a flip attaches or detaches the environment before the next model call, announced to the model as one full environment signal (new cwd, complete tool roster, a warning that the previous environment's files may be inaccessible). Not constructing the default environment also slims deploys that never opted in: the cloudflare example's main chunk drops from 5,481 kB to 3,482 kB.

  • Breaking

    Skill and markdown imports drop their import attributes — the specifier decides. Importing a path that resolves to a SKILL.md packages that skill directory at build time and yields a SkillReference for useSkill(...) (static imports only; frontmatter validated against the Agent Skills spec); importing any other .md file yields the markdown text as a plain string, which defineSkill({ name, description, instructions }) turns into a skill. The with { type: 'skill' } and with { type: 'markdown' } attribute forms are removed. defineSkill now validates and freezes instead of packaging — instructions is required, packaging happens lazily, and the runtime writes the frontmatter — and useSkill(...) accepts a SkillReference or a SkillDefinition directly. Manual skill invocation is gone: skills mount into the agent's disclosure catalog (or join it via workspace discovery under a sandbox's .agents/skills/), and the model activates them through the framework's activate_skill tool.

  • Breaking

    MCP servers are declared as connection definitions; connectMcpServer is removed. One flat McpConnectionDefinition ({ name, url, transport?, auth?, headers?, tools?, optional?, timeoutMs?, … }) drives the whole surface: useMcpConnection(definition) declares a server from the agent render — its tools mount as mcp__<server>__<tool>, read once per submission and cached per agent instance — defineMcpConnection(definition) is the validating, freezing typing helper for the exportable unit (spread it for per-mount overrides), and createMcpConnection(definition) is the imperative factory replacing the beta's connectMcpServer(name, options) for module-scope use on the Node target (McpServerConnection is renamed McpConnection). New in the definition: auth — a static bearer token or a function resolved freshly on every request, the seam for per-user and rotating credentials (a 401 retries once after the credential resolver is consulted); tools — an allowlist by the server's own tool names, where a name the server doesn't expose is a hard error; and optional: true — a server that fails to resolve mounts zero tools for that submission instead of failing it, announced to the model once as a resources signal naming each unavailable server and surfaced to observers as a warning event (failures are never cached, so the next submission retries). Underneath, the adapter runs on the v2 MCP SDK (@modelcontextprotocol/client, a direct dependency of @flue/runtime): structured tool output is validated by the client itself with a workerd-compatible validator, and existing v1 servers interoperate unchanged.

  • Breaking

    Model providers are Pi-native: registerProvider and registerApiProvider are removed, and the providers list is exhaustive. A custom or customized provider is a pi-ai Provider object registered with setProvider(provider) — built with createProvider(...) and the built-in factories from @earendil-works/pi-ai, which you depend on directly — replacing the beta's option-bag registerProvider(id, { ... }), registerApiProvider, and the deprecated pi-ai/compat layer under them (model capabilities such as reasoning, input, contextWindow, and cost are plain fields on the Model objects a provider declares). Model specifiers keep the 'provider-id/model-id' format. The new providers?: string config (in flue.config.ts or inline on the flue() plugin) selects which built-in providers exist: omitted, every pi built-in registers as before; set, only the listed providers — catalogs and protocol implementations included — are bundled and resolvable, and the narrowing is real bundle weight: examples/cloudflare with providers: ['anthropic'] deploys 5.8 MB instead of 9.6 MB (#359). 'cloudflare' in the list selects the Workers AI binding provider — cloudflareBindingProvider({ binding, gateway? }) from @flue/runtime/cloudflare/workers-ai, auto-registered on Cloudflare builds when the list is omitted, with its wire-protocol implementations now loaded lazily so Durable Object cold starts stop paying for them — and naming it on the Node target is a config error pointing at the HTTP alternatives (cloudflare-workers-ai / cloudflare-ai-gateway). Programmatic runs get the same selection as start({ providers }), taking Provider objects.

  • Breaking

    Channel helper APIs are renamed instanceId/parseInstanceId. The value these helpers produce was always the agent instance id, so every channel package renames conversationKey → instanceId and parseConversationKey → parseInstanceId (zendesk's ticketKey/parseTicketKey included), with the Invalid*ConversationKeyError classes following as Invalid*InstanceIdError — a clean break, no aliases. parseInstanceId is also demoted from showcase to escape hatch: agents receive structured facts as creation data (useInitialData()) rather than parsing them back out of the id.

  • Breaking

    The SDK and React hooks address one conversation by URL. The framework no longer knows where agents live — app.ts is the map — so the client collapses to the resource it talks to: createFlueClient({ url: 'https://host/agents/triage/123456' }) (the agent's mount URL plus a caller-chosen conversation id) with send(), wait(), history(), observe(), abort(), and attachmentUrl(). The baseUrl + agent-name/id addressing, the client.agents namespace, and listAgents() are removed; a new conversation is the caller appending a fresh id to the mount URL. @flue/react's useFlueAgent({ url }) replaces useFlueAgent({ name, id }).

  • Breaking

    Assistant output projects as one conversation message per response. An assistant response spanning multiple model steps (text, tool calls, tool results, more text) previously projected one message per step; history snapshots and live updates now fold every assistant step of a submission into one message — parts accumulate in record order, usage sums across steps, identity fields stay the first step's — matching how the AI SDK ecosystem assembles one UIMessage per response. Clients that keyed logic on per-step assistant messages see fewer, larger messages; the chunk wire vocabulary is unchanged.

  • Breaking

    The @flue/dev-console TUI package is removed. The terminal chat console is not a direction Flue is investing in; local manual testing lives in the in-browser demo chat app (demo/ in the repository), which is the basis for a future flue dev experience.

  • Breaking

    flue run is rewritten as transport-free local execution, and the CLI slims to run/init/add/update/docs. flue run <path-to-agent-module> --message "..." compiles and runs one agent module under Node with no HTTP listener or Cloudflare emulation: product events stream to stderr, the final reply (or a --json envelope) prints to stdout, and the conversation id is printed so --id can continue the same conversation across invocations. Persistence honors the project's db.ts when configured, else a project-local cache database. Removed flags: --server, --header, --target, --root, --output, --config, and --input (superseded by --message); flue run <name> (a bare agent name) is replaced by the module path form. flue dev and flue build error with pointers to the Vite commands.

  • Breaking

    dispatch() takes a structured message, not an opaque input. AgentDispatchRequest.input: unknown is replaced by message: DeliveredMessage, the same unified shape a direct HTTP prompt uses internally: { kind: 'user', body: string, attachments?: DeliveredAttachment } for a real chat turn, or { kind: 'signal', type: string, body: string, attributes?: Record<string, string>, tagName?: string } for a structured event/webhook payload. body is always a string — JSON-stringify structured payloads yourself. dispatch() can now deliver a kind: 'user' message with image attachments, the same way a direct HTTP prompt does (attachments on kind: 'signal' are not supported). message is validated the same way as a direct prompt's body (a malformed message throws InvalidRequestError) instead of being forwarded unchecked. On the adapter surface, the submission input types collapse into one AgentSubmissionInput interface ({ kind: 'dispatch' | 'direct', submissionId, agent, id, message, acceptedAt }) — DispatchAgentSubmissionInput and DirectAgentSubmissionInput are removed, a dispatched submission's persisted input carries only submissionId (no separate dispatch-scoped id), and the persisted-attachment helpers exported from @flue/runtime/adapter are renamed: prepareDirectSubmission → prepareSubmissionAttachments, hydratePersistedDirectSubmission → hydratePersistedSubmissionAttachments, matchesPersistedDirectSubmission → matchesPersistedSubmissionAttachments. Every first-party channel example and blueprint is updated to the new shape, following one convention: body carries the message itself and structured metadata (sender identity, ids, titles) goes in attributes as flat strings.

  • Breaking

    dispatch() targets an agent definition, not a name string. The single signature is dispatch(agent, { id, message }), where agent is the default export of a 'use agent' module. The dispatch({ agent: '<name>', id, message }) named-string form is removed — a non-definition first argument throws InvalidRequestError — and the NamedAgentDispatchRequest type is no longer exported from @flue/runtime.

  • Breaking

    The direct agent HTTP wire body is a DeliveredMessage. POST /agents/:name/:id now accepts the same validated DeliveredMessage shape dispatch() admits — { "kind": "user", "body": "...", "attachments"?: [...] } for a chat turn (or a kind: 'signal' event) — replacing the { message, images? } wire body and the internal mapping layer behind it. @flue/sdk's AgentPromptOptions.message is now a DeliveredMessage (was string; the images option folds into attachments), and AgentPromptImage is renamed DeliveredAttachment in @flue/sdk and @flue/react. The DirectAgentPayload type is removed from @flue/runtime. flue run delivers its --message text as a kind: 'user' message.

  • Breaking

    Signal tagName must be a valid XML tag name. The optional tagName on a kind: 'signal' message is rendered as the signal's XML envelope in model context, so it is now validated (letters, digits, _, -, .; must not start with a digit, -, or ., and must be non-empty) and a malformed value throws InvalidRequestError at admission instead of injecting markup past the body/attribute escaping.

  • Breaking

    Direct agent prompts are fire-and-forget only. The ?wait=result synchronous mode on agent HTTP POSTs is removed; agent prompts always return a 202 admission. The in-process observer registry (createAgentSubmissionObserverRegistry, AgentSubmissionObserver, AgentSubmissionObserverRegistry), the DirectAttachedOptions/invokeDirectAttached/runDirectSyncMode admission path, and the result field on SubmissionSettledRecord, AgentConversationSettlement, AgentSubmissionSettledEvent, and the submission_settled FlueEvent variant are all removed. Callers that need the actual assistant reply should read it from the conversation transcript via the conversation client's history() or the live conversation stream.

  • Breaking

    The SDK's prompt() is removed. Use the conversation client's send() (fire-and-forget) plus wait() (completion-await, now Promise<void>) plus history() (to read the reply). AgentPromptResult and AgentPromptResponse types are removed from @flue/sdk.

  • Breaking

    The SDK's wait() no longer resolves with a result. It resolves void on completion and throws FlueExecutionError on failure or abort. A remote abort is now distinguishable from a real failure: FlueExecutionError.failure is 'aborted' for an aborted settlement (previously both classified as 'failed').

  • Breaking

    AttachedAgentEventCallback type removed from @flue/runtime. The onEvent callback parameter on admission no longer exists.

  • Breaking

    reconcileInterruptedSubmission return type simplified. Returns AgentSubmission | undefined (the replacement submission, or undefined) instead of the 5-variant ReconciliationResult discriminated union. Custom coordinator implementations that inspected .disposition should branch on truthiness instead.

  • Breaking

    The init() handle's dispatch() is enqueue-only; awaiting the reply is the new read(). handle.dispatch(request) now resolves at admission with the durable DispatchReceipt — the same contract as the top-level dispatch(), so the verb means one thing everywhere — instead of awaiting the settled reply, and it no longer takes an options argument. The settled reply moves to handle.read(receipt | submissionId, { onEvent?, signal? }), which resolves with the AgentReply (rejecting with AgentRunError on a failed or aborted settlement) and re-attaches from any process at any later time: settlement and reply are durable conversation records, so a receipt persisted across a crash — for example as a workflow step's durable result — is all a retry needs, and a submission that settled long ago resolves immediately. read()'s signal stops only the read (a local cancel; previously the dispatch signal requested a durable abort of the run) — the durable abort intent is the new explicit handle.abort(), which covers the running head and every queued submission. A read addressed to an instance that does not exist rejects with AgentInstanceNotFoundError on every target rather than waiting for work that can never settle. The AgentDispatchOptions type is renamed AgentReadOptions and belongs to read().

  • Breaking

    One id vocabulary end to end: dispatchId is renamed submissionId. DispatchReceipt.dispatchId (the field dispatch(), handle.dispatch(), and useDispatchMessage() resolve with) is now DispatchReceipt.submissionId; handle.read(receipt) and handle.read(submissionId) are unaffected, and a bare-string read target is still the receipt's id, just spelled submissionId. New dispatch submission ids are sub_-prefixed (previously dispatch_); ids remain opaque and old dispatch_-prefixed ids stay valid.

  • Breaking

    FlueEvent no longer has a dispatchId correlation field. submissionId alone identifies a submission's activity — dispatched and direct alike — on every event and on FlueExecutionContext; code that branched on dispatchId should read submissionId instead. See the Events Reference.

  • Breaking

    The flue.dispatch.id telemetry attribute is removed. @flue/opentelemetry and the native Cloudflare tracing adapter (createCloudflareTracing()) no longer emit it; flue.submission.id, already emitted alongside it, is the replacement.

  • Breaking

    Trace content is captured by default, and @flue/opentelemetry's content surface collapses to content?: false | { transform }. Both trace adapters — createOpenTelemetryInstrumentation() and the native Cloudflare createCloudflareTracing() — now emit conversation content (gen_ai.input/output.messages, system instructions, tool definitions/arguments/results) unless you pass content: false; installing an instrumentation with instrument(...) is the consent (on Cloudflare, enabling Workers Traces), and a transform is the policy hook. On @flue/opentelemetry this removes GenAIContentPolicy as a public type along with enabled, inline, externalContent (a side-effecting transform is the replacement — GenAIContentScope now carries traceId/spanId for correlation), limits (slice in the transform, or use the exported truncateContent(content, { maxBytes })), and the diagnostic callback. Exception message and stack now ship by default through the same gate (strip them with a transform on exception_message/exception_stacktrace, or disable content); the Cloudflare adapter continues to exclude them unconditionally. The flue.telemetry.content.*.truncated/.omitted marker attributes are gone: truncation is structural and in-band — payloads stay valid JSON under a 56 KiB per-span content budget (every content attribute a span carries shares one pool, with a reserve so response content always has room beside large prompts), with oldest messages dropped behind a role: "flue" sentinel message and oversized strings cut with a [flue:truncated, …] suffix (FLUE_TELEMETRY_EXTENSION_REVISION is now 4). @flue/opentelemetry requires a @flue/runtime version shipping the ./telemetry subpath.

  • Breaking

    GEN_AI_SCHEMA_URL is removed, and @flue/opentelemetry's tracer/meter no longer declare a schemaUrl. The URL was fabricated — the OpenTelemetry GenAI semantic-conventions repository has not published a schema URL — so exporting it and stamping it on the wire handed schema-aware tooling a dead link with defined semantics. The pinned upstream revision the gen_ai.* keys were read from remains exported as GEN_AI_SEMCONV_REVISION.

  • Breaking

    Persisted stores are stamped format_version 1, and stores written by 1.0.0-beta.x are rejected. Every persisted Flue store durably records the format version it was created with — a format_version key in the SQL backends' flue_meta table, the equivalent on the non-SQL adapters — and refuses to open anything else, throwing PersistedFormatVersionError (type: 'persisted_format_version_unsupported'). The persisted shapes changed incompatibly across the 2.0 line (one unified message input for both transports, the submission_id column naming, chunked attachment storage), so a beta-era store must be cleared; there is no migration. For adapter authors, the stamp contract is exported from @flue/runtime/adapter as FLUE_FORMAT_VERSION and assertSupportedFlueFormatVersion() (replacing FLUE_SCHEMA_VERSION and PersistedSchemaVersionError), and defineStoreContractTests exercises the stamping rules on every backend.

  • Breaking

    A tool's run() returns a result envelope — { output?, terminate? } — and bare non-string values are rejected. output is the tool's result value, validated against the declared output schema and serialized for the model exactly as before; terminate: true ends the agent's turn once the current tool batch settles — the same loop-ending contract the built-in finish/give_up tools use, so a custom tool can conclude a response without another model round-trip (the turn ends only when every result in the batch terminates, and a throwing tool never terminates). Returning a bare string remains shorthand for { output: <string> }, and returning nothing is still allowed for tools without an output schema; any other bare value (number, boolean, array, null) or an object with keys beyond output/terminate now throws an error telling you to wrap it — return { output: <value> } — which is what makes plain-object returns unambiguous. Termination is durable: the flag is recorded on the tool's canonical outcome (additive — no storage schema bump), so a crash between a terminal tool batch's commit and settlement now recovers to the live outcome — the submission settles without an extra model turn — closing the same recovery gap for turns ended by finish/give_up.

  • Breaking

    SessionEnv.exec now rejects promptly on abort — an un-cancellable sandbox command becomes a documented orphan. When options.signal aborts mid-command, the returned promise rejects with AbortError immediately instead of waiting for the remote command to settle. Previously, aborting agent work during a command on a signal-blind provider SDK (E2B, Daytona, Modal, and most others expose no mid-flight cancellation) blocked the entire abort path — the error tool result, the batch commit, the submission_aborted advisory, and the next queued prompt — until the command finished on its own. The guarantee is implemented once, in the runtime's wrappers (createSandboxSessionEnv and the bash() factory adapter), so SandboxApi itself is structurally unchanged and every adapter built on the wrappers gets the behavior for free; the first-party Cloudflare adapter's own local abort race is removed in favor of the shared one (its container death detector now handles liveness only). The still-running remote command is an explicit, named state — an orphaned command: its eventual settlement is consumed, never recorded (no conversation records, no tool events; a late SandboxDiedError from an orphan is swallowed into the settlement), and is observable through the new optional createSandboxSessionEnv(api, cwd, { onOrphanSettled }) callback with the exported OrphanedExecSettlement type. The abort-time error message — which reaches the model as the error tool result — now carries the suffix "The sandbox command could not be confirmed cancelled and may still be running.", and a subsequent command may run in the same sandbox while an orphan is still executing (whether the provider serializes or interleaves is provider-defined; this was already the reality on Cloudflare). Deliberately breaking in two ways: callers that relied on an abort rejection implying the remote command had finished lose that (it was already false on Cloudflare), and hand-rolled SessionEnv implementations built without the wrappers are now out of contract if they late-reject. The sandbox reference's "do not simulate mid-flight cancellation with Promise.race" guidance is withdrawn and inverted: the wrapper owns the abort race, and adapters must not add their own. No persisted-schema or record-shape changes — the abort path emits the same records, just without the wait.

  • Breaking

    AgentSubmissionStore gains a required method: settleQueuedSubmission(submissionId, outcome, error). Terminal settlement for a queued submission that can never be claimed — atomic and queued-gated (the first terminal state wins against a racing claim), no attempt is created, and no canonical settlement record exists for it (the same already-tolerated class as the SQL stores' malformed-row termination: the row's outcome is authoritative when no stream record exists). Custom AgentSubmissionStore implementations must add it; every first-party backend (the built-in SQLite stores plus @flue/libsql, @flue/postgres, @flue/mysql, @flue/mongodb, and @flue/redis) ships it in lockstep, and defineStoreContractTests now exercises it unconditionally.

New Features

  • Idempotent delivery: name a send with idempotencyKey and retries converge instead of duplicating turns. Every real inbound channel is at-least-once — Slack redelivers events, webhook providers retry, a browser resends after a lost response — and until now each redelivery admitted a brand-new submission. Both transports now accept an optional caller-chosen key (≤256 chars): dispatch(agent, { id, message, idempotencyKey }) (and the init() handle's dispatch), a reserved idempotencyKey body sibling beside initialData/uid on the direct POST /agents/:name/:id, and send({ message, idempotencyKey }) in @flue/sdk. Two admissions to the same agent instance with the same key are the same submission — delivered and answered at most once, every admission returning the same receipt, with replays marked deduplicated: true and echoing the original acceptedAt (direct replays re-attach from the stream origin offset). The key names the delivery, not the outcome: a submission that settled failed stays failed — retry with a fresh key to ask again. Reusing a key with a different payload rejects with the new structured 409, SubmissionConflictError (type: 'submission_conflict', the existing submission's id in meta.submissionId), identical on both targets — the Cloudflare internal dispatch conflict body is now structured JSON rehydrated Worker-side instead of bare text. No storage schema change and nothing new asked of persistence adapters: the key deterministically derives the submission id (sub_ik_ + SHA-256 over agent/instance/key, a frozen wire format), so the existing idempotent admission machinery does the rest, and custom stores get the feature for free. Channel packages stay stateless — pass the provider's redelivery-stable id through (idempotencyKey: payload.event_id for Slack); the channel READMEs and guide show the mapping.

  • New @flue/runtime/telemetry subpath: the backend-neutral GenAI content machinery shared by the native Cloudflare tracing adapter and @flue/opentelemetry — the role/parts message projection (inputMessages, outputMessages, systemInstructions, toolDefinitions, …), the content pipeline, the truncateContent(content, { maxBytes }) helper (same structural in-band truncation and [flue] sentinels as the built-in safety net, for tighter policy budgets inside a transform), the CONTENT_ATTR vocabulary, and the semconv revision constants. Dependency-free and Node-evaluable; the runtime stays free of @opentelemetry/api.

  • createCloudflareTracing() now captures conversation content into Workers Traces by default — input/output messages, system instructions, and tool definitions/arguments/results on the same gen_ai.* attributes the OTel adapter emits, so Flue conversations read directly in the Traces dashboard. content: false restores content-free spans; content: { transform } redacts or drops in code. Raw error messages and stacks never ship on this backend, caller-origin bash is traced as the same flue-owned flue.operation shell span @flue/opentelemetry emits — no gen_ai.* claims and no content, since a user's shell operation is not a model tool call — and all content projection runs only on sampled invocations.

  • Agents deployed to Cloudflare are traced with no wiring: enable Workers Traces and each response's trace carries the invoke_agent/chat/execute_tool spans, no instrument(...) line needed. Installing createCloudflareTracing(...) yourself customizes as before; tracing: false in flue.config.ts opts out.

  • Public conversation messages now expose typed purpose (user, assistant, dispatch, or advisory) and display (visible, hidden, or diagnostic), plus optional turnId grouping and a signal descriptor, so clients can distinguish public chat from internal, control, and advisory activity without parsing message text, timestamps, or ordering. The classification is applied identically across conversation history() snapshots and live updates, and @flue/sdk / @flue/react shapes are updated in lockstep (#404).

  • vite preview now works on the Node target. vite build emits two entries — the self-starting dist/server.mjs and the non-listening dist/app.mjs application chunk it imports — and preview serves the built app.mjs natively (no Vite transformation), so what preview serves is exactly what node dist/server.mjs would serve, including production persistence defaults and the real process environment. Running preview without an artifact fails with "Run vite build first."

  • vite dev on the Node target now loads the project's .env file set (.env, .env.local, .env.<mode>, .env.<mode>.local) into the application's environment, with shell-exported values taking precedence — matching flue run, so model-provider keys work without a shell export. The built server still reads only the real environment, and Cloudflare .dev.vars/.env handling stays with the Cloudflare plugin.

  • The Node dev server's 503 "runtime unavailable" envelope now carries the underlying application load failure in its dev-only field, so a request tells you WHY the app failed to load without tailing the terminal, and load-failure stacks are remapped to authored sources (ssrFixStacktrace).

  • flue init is now interactive and scaffolds the full project skeleton for the new surface instead of only flue.config.ts: missing choices are prompted, with --target and --deploy answering them for scripted runs, and when the HTTP server setup is included it also writes a vite.config.ts with the flue() plugin (plus cloudflare() on the Cloudflare target), a starter src/app.ts route map, and — on the Cloudflare target — a wrangler.jsonc with nodejs_compat, observability.traces enabled, and commented migration guidance. --force still applies only to flue.config.*; the other files are created only when absent and never overwritten.

  • @flue/react's useFlueAgent() now exposes refresh(), so apps observing an agent conversation that may be created out-of-band (a server-side wakeup, queue worker, or webhook) can re-check on their own schedule instead of faking an empty history snapshot. Retry policy stays in userland (#403).

  • Internally-logged error responses now carry a correlation ref. When the runtime renders a 500-class internal error (a non-FlueError, or a non-HTTP FlueError that escaped to a route), it mints an err_-prefixed ULID and stamps it in three places: the envelope's new error.ref field, a new flue-error-ref response header (which survives body-less HEAD responses and body-swallowing intermediaries), and the matching server-side log line's [flue] [err_…] prefix — so a caller reporting a production 500 can point operators at the exact log entry, and the ULID alone brackets the time window. Caller-mistake 4xx envelopes stay unlogged and ref-free ("ref iff logged"). When the failing request carried a W3C traceparent, it is logged beside the ref (never echoed on the response). @flue/sdk's FlueApiError exposes the ref as ref (envelope body first, header fallback) and includes it in the composed message — Flue API error 500 [internal_error] (ref err_…): … — so the ref lands in calling services' own logs with no extra code. The failed-submission settlement text now also directs callers to quote the submissionId, the async-path counterpart of the ref.

  • Queue activity and recovery failures are first-class runtime events. Three additions complete the observe() submission vocabulary (queued → running → settled): submission_queued is emitted immediately after durable admission on both targets (at-least-once — idempotent replays re-emit); submission_running is emitted from the attempt's own context on every attempt, carrying attemptCount/maxAttempts, so a recovery replacement re-announces itself with the incremented count; and submission_recovery surfaces every contained coordinator recovery failure — admission-side materialization, settlement finalization, interrupted-attempt reconciliation, attempt start/processing, and pass-wide failures — with operation/outcome discriminators, the same stackless error shape as submission_settled (the live observation adds the classified errorInfo with throw-site stack), and re-emission on every failed wake while the condition persists, closing the alerting hole where a submission stuck in a retry loop was visible only in stderr (each site's structured console.error remains). Deriving per-instance busy/idle by keying queued/running against settled on submissionId is now a documented stable pattern that converges across process restarts and Durable Object eviction; a delivery that joins a busy conversation emits queued + settled but never running. All three are live-only events like the rest of the stream — no conversation records, no schema change — and existing observers that branch on specific event.types are unaffected (exhaustive switch statements need a default arm). See the Events Reference.

  • start() and init(): the programmatic agent client. start({ agents, db?, env?, providers? }) (from @flue/runtime/node) assembles a transport-free Flue runtime in any Node process — agents passed as the functions themselves, an optional PersistenceAdapter (default: in-memory), and stop()/await using for drain-and-dispose — so scripts, cron jobs, and tests drive agents without an HTTP server. init(agent, { id?, uid? }) (from @flue/runtime, on both targets) returns the durable handle for one agent instance — an address, not a resource: it creates nothing and does no I/O, so it is safe at module scope — with dispatch() (enqueue-only, resolving at admission with the durable DispatchReceipt; a bare string is shorthand for a user message, { message, initialData?, idempotencyKey? } the full payload), read() (await the settled AgentReply, re-attachable from any process at any later time), and abort(). On Cloudflare the handle works inside cron callbacks, queue consumers, and Cloudflare Workflow steps — checkpoint the receipt as one step's durable result and read the reply in the next — the recommended shape for durable multi-step orchestration now that workflows live outside the framework.

  • durable: true tools get checkpointed steps. A tool declared durable: true receives ctx.step, and step.do(name, fn) runs fn once per name per tool call, durably recording the result before resolving. An interrupted durable: true call is re-executed on recovery with completed steps replaying their recorded values — the code between steps re-runs, memoized steps do not — instead of being settled with an unknown-outcome interrupted error like an ordinary tool. The guarantee is exactly-once-recorded, at-least-once-executed (a crash in the window between fn completing and the record landing re-runs that one step), so steps around external effects should be individually idempotent; step values must be JSON-serializable and small, names deterministic and unique within a call. A thrown error is not an interruption — a durable tool that throws settles as an ordinary tool error the model sees, with no retry-budget burn — and the flags compose: durable: true, harness: true receives both step and harness, with harness.prompt(...) wrapped in a step so recovery doesn't re-prompt.

  • Instance creation data and incarnation-conditional sends. An agent instance can be born with typed data: declare a Valibot schema as the agent's initialData static, read the parsed value with useInitialData(), and seed it from any sender — dispatch(agent, { id, message, initialData }), the init() handle's dispatch({ message, initialData }), a reserved initialData body sibling on the direct HTTP POST, send({ message, initialData }) in @flue/sdk, and flue run --data '<json>'. Validation runs synchronously at admission, before anything durable is admitted — a mismatched creating send rejects instead of queuing an unrunnable submission — and data sent to an already-existing instance is ignored. Every instance also gets a uid minted at its birth (inst_…, carried on every DispatchReceipt and SDK send result), and sends can be made conditional on it ETag-style with the uid option: a string continues only that incarnation (a missing instance or mismatched uid rejects at admission with AgentInstanceNotFoundError / 404, nothing durable), null creates only (an existing instance rejects with AgentInstanceExistsError / 409 carrying the existing uid in meta.uid), and omitted stays unconditional. The CLI speaks the same contract (flue run --uid <uid> / --new), and getAgentInstance(agent, id) looks up an instance's uid when no receipt is at hand.

  • A message that arrives while its conversation is busy can join the live response. Dispatches and direct HTTP prompts delivered mid-response no longer always wait in queue: at the next turn boundary the delivery joins the running response — the agent re-renders with the new input in front of the model, and the joined submission is answered by the response it joined (settlements expose the linkage as answeredBySubmissionId) — while a delivery that misses the live response runs as its own submission afterward, so nothing is lost either way.

  • In-process observe() now receives streaming tool-call argument deltas: the new toolcall_delta event carries { toolCallId, toolName, argumentTextDelta } while a model streams a tool call's JSON arguments, so a UI can preview an in-flight, schema-enforced tool call as it is written. Live-preview only — never persisted or replayed; the complete arguments still arrive with the canonical tool-call record (#450).

  • The SDK client gains read(admission | submissionId, options?) — the HTTP counterpart of the handle's read(). It awaits the submission's settlement and resolves with its reply ({ text, data, metadata?, submissionId, uid? }), throwing FlueExecutionError on a failed or aborted settlement; the bare-id form follows the conversation from the stream origin, so a process that persisted just the admission re-attaches at any later time and an already-settled submission resolves immediately. wait() remains the cheaper outcome-only primitive. @flue/sdk also exports readSubmissionReply(conversation, submissionId), the pure projection read() uses internally — extract a reply from a history() snapshot or an observe() state with no extra fetch, including the coalesced reply when the send joined a busy response (replacing hand-picked messages.at(-1) reads that silently grab the wrong message on a busy conversation). The same projection backs the runtime's init().read(), so a reply read over HTTP and one read in-process agree.

Fixes & Other Changes

  • Updated @earendil-works/pi-ai and @earendil-works/pi-agent-core to 0.83.0.

  • Conversation reads and cold starts no longer replay an instance's whole record log, and resident conversation state no longer grows with lifetime streaming volume. Every read (history, updates, SSE connects, attachment resolution, in-process observers) is served from one shared per-instance fold advanced incrementally and shared with the writer — a dispatch after a read pays no second replay, and vice versa. The fold releases what it provably never reads again: per-chunk streaming-record bookkeeping at message completion (and at the settle barrier for interrupted streams), and a settled submission's attempt bookkeeping bodies, so the idempotency index scales with non-streaming records instead of delta volume. Cold loads seed from a durable fold checkpoint the writer cuts every 64 appends and fold only the suffix appended since — checkpoints are a discardable cache over the log, self-invalidated by format version, incarnation, and the stream head, never authoritative. Adapter surface: ConversationStreamStore gains optional putFoldCheckpoint/getFoldCheckpoint (the first optional store methods; implemented by every first-party adapter, additive tables/keys with no format-version event) — custom adapters without them stay fully functional and degrade to full replay with one warning per path. The idempotency contract relaxes exactly where the bookkeeping releases: replaying a streaming record after its message resolved now fails loudly instead of deduplicating silently; no legitimate path re-appends one (store-level producer sequencing dedupes batch retries).

  • @flue/opentelemetry now reserves the Stable exception.type attribute for the exception class name (RateLimitError, TypeError, …), per the OpenTelemetry exception conventions — previously it duplicated Flue's error taxonomy, which stays on error.type only. Applies to span exception events, span status, and gen_ai.client.operation.exception log records alike; when a failure carries neither a throw-site class name nor a (content-gated) message, no exception record is emitted and the span's error.type is the whole failure record.

  • Both trace backends now stamp gen_ai.agent.name on execute_tool spans (conditionally required by the GenAI semantic conventions when the owning agent is known), and the native Cloudflare adapter's chat spans gain server.address/server.port, gen_ai.conversation.compacted, and openai.api.type, closing the attribute gap with @flue/opentelemetry.

  • Terminalizing a durable agent submission (retry exhaustion, timeout, post-input interruption, or abort) now settles its conversation to a deterministic rest state instead of leaving dangling tool calls behind. Every tool call without a confirmed outcome gets an explicit interrupted-error tool_outcome and the batch is committed — recorded outcomes are preserved and nothing is re-executed or resumed — so a task tool call can no longer rest as "still running" forever in history projections, and the settled turn stays visible to future model context instead of being silently dropped. For a task call the marker includes the retained child conversation id; the child transcript itself is untouched. An interrupted in-progress assistant stream is likewise completed as aborted at terminalization. The terminal advisory now carries the interrupted-call list as structured attributes.interruptedTools (also on SubmissionRetryExhaustedError/SubmissionInterruptedError meta), so apps can settle their own run state without parsing text. Conversations already left dangling by earlier versions self-heal on their next prompt: a new submission settles abandoned trailing state before appending its input (#419).

  • The local CORS defaults now apply to Cloudflare-target vite dev and to vite preview on both targets, not just Node vite dev, and are tightened to localhost: credentialed requests are allowed from localhost-family origins (Vite's own default origin set) instead of any reflected Origin, with the durable-stream coordination headers exposed — so separate-origin local clients (like the repository's demo chat app) can stream conversations from any local server shape, while an arbitrary website can no longer drive the local agent API through ambient credentials (#483). Non-localhost clients need an explicit server.cors / preview.cors override — user-set values still win — and production servers keep CORS as an application concern.

  • Wrong-environment import failures now print the import chain. When a cloudflare:* module reaches a Node graph — under vite dev, vite build, or flue run — the diagnostic names the route to the problem (src/app.ts imports src/lib/platform.ts imports cloudflare:workers), not just the failing specifier, and adds the type-only escape hatch (import type is erased at build time). In vite dev the chain also lands in the 503 envelope's dev field.

  • Watcher event bursts (branch switch, format-on-save across files) now coalesce: the agent re-scan and Cloudflare input-regeneration queues run at most one in-flight pass plus one queued pass instead of one full pass per event, which also keeps dev-server shutdown from waiting behind a long queue.

  • @flue/vite hardening from a comparative review against SvelteKit's and TanStack Start's Vite plugins: resolve.dedupe for @flue/runtime/hono on every target, an explicit warning when user Vite config conflicts with values flue() enforces, a warning when multiple flue.config.* files coexist, stackless errors for expected user mistakes (the message is the diagnostic, without a framework stack burying it), hook-level transform filters (the import-attribute transform no longer parses every TS module in the graph), self-contained transform sourcemaps (sourcesContent), a file:line:column pointer on the missing-default-export diagnostic, and the Chrome DevTools well-known probe is answered with a 404 before it can reach a catch-all application route.

  • MCP tool connections no longer crash on Cloudflare Workers when a connected server advertises a tool outputSchema. JSON Schema validation now uses a codegen-free strategy compatible with the workerd runtime instead of runtime code generation (#400).

  • Completed assistant messages now preserve their submissionId in conversation history() snapshots, so clients that group a user turn with its assistant answer by submission id keep that grouping after reload (#402).

  • Tool-call duration is now durably recorded and surfaced as durationMs on the resolved dynamic-tool part in both history snapshots and live updates, instead of being available only on the ephemeral live event (#407).

  • The Cloudflare extension's base and wrap callbacks are now typed against the concrete generated Durable Object constructor (GeneratedDurableObjectClass<TBase, TEnv>, a constructor producing TBase & DurableObject<TEnv>), replacing the unreleased generic type-preserving wrap signature. Every class Flue passes in really is a branded Durable Object, so brand-checked platform instrumentation such as @sentry/cloudflare's instrumentDurableObjectWithSentry now accepts the class straight through — no generics, unsafe casts, or runtime constructability assertions, and no need for your own base type to extend DurableObject. extend() gains an optional second TEnv type parameter for typing the environment your instrumentation reads. The @flue/runtime/cloudflare types now reference cloudflare:workers type-only (its runtime import graph is unchanged); projects without Cloudflare workers types configured degrade to any under skipLibCheck (#410).

  • Documented the supported pattern for reaching a private Flue agent over a Cloudflare service binding: point the @flue/sdk client's fetch option at the binding, since the baseUrl host is never dialed and only the pathname and query drive routing (#408).

  • Documented the kind: 'user' vs kind: 'signal' convention: user is a direct user talking to the assistant (a 1:1 chat surface); signal models everything beyond that — including most channels, where a Slack thread or GitHub issue is a multi-user conversation the agent participates in as one member, with sender identity carried in attributes.

  • Channel examples no longer drop sender identity and event metadata during dispatch: GitHub (sender, issue ref, title, installationId — restoring the self-reply-loop guard), Teams, Google Chat, Linear, Telegram, Twilio, and Messenger regain the fields the DeliveredMessage migration lost, as flat attributes. Telegram media-only updates now dispatch a '[photo message]'-style placeholder body instead of an empty string.

  • A joined submission's reply is now resolved through its settlement's derived linkage instead of by recency. Conversation settlements (settlements in history snapshots, the submission-settled chunk, and the SDK types in lockstep) expose answeredBySubmissionId — the submission whose response answered this one, derived at projection time from the attempt shared by the settlement record and the response's assistant records, so nothing new is stamped at settle time and existing conversations resolve retroactively. Previously a delivery that joined a busy response read "the conversation's last assistant message" as its reply, which silently returned a later submission's answer once the conversation moved on; that recency fallback now applies only to legacy settlements that predate attempt stamping.

  • The SDK client's read() rejects an admission that belongs to a different conversation (compared by pathname, so service-binding setups that never dial the URL's host are unaffected) instead of waiting on one conversation's stream and reading a reply out of another.

  • The SDK's wait() (and the new read()) now recognize a settlement folded into a conversation-reset snapshot — previously a settlement subsumed by a reset chunk recorded in the same durable batch (for example alongside a compaction) was missed, leaving the wait hanging until the stream produced another event.

  • Removed dead per-submission result computation left behind by the result-await removal (each settled submission no longer builds a response text and full-conversation usage aggregate that nothing reads), the never-populated interruptedTools field on SubmissionInterruptedError meta and the terminal-advisory renderer, and the unused AttachedAgentEventCallback-era boolean returns on internal settlement helpers.

  • A bare "Provider finish_reason: error" — how pi-ai's OpenAI-compatible layer reports an aggregator (e.g. OpenRouter) upstream provider dying mid-generation — is now retried with the same backoff as a 5xx instead of terminalizing the submission. Qualified reasons (error_quota, error-content-filter, content_filter, …) stay terminal.

  • Failed and aborted turns are now structurally detectable in the conversation timeline: the terminal advisory message the runtime appends when a submission settles short of a reply carries a settlement: { outcome: 'failed' | 'aborted' } marker (the message's submissionId names the settled submission), identically in history() snapshots and live updates, with the @flue/sdk and @flue/react message shapes updated in lockstep — so clients render a stopped or failed turn from the structured field instead of sniffing advisory record ids and parsing prose (which is what the repository's demo chat did for aborts; it now uses the marker and renders failed turns too). Completed submissions get no timeline marker (the assistant reply is the marker), recovery and narration advisories carry none, and the snapshot's settlements stays the programmatic outcome index — now also exposed on @flue/react's useFlueAgent() snapshot as settlements (with FlueConversationSettlement re-exported), purely additive to the existing status/error semantics. Internally, the canonical submission_settled record now requires its submissionId — every writer already stamps it — with the reducer fold rejecting a record missing it, which retires the projection layer's tolerate-missing-id branches; no storage schema bump.

  • A live conversation stream can no longer stall silently forever. Nothing in the read path owned a deadline: a half-open TCP connection (NAT timeout, laptop sleep), a proxy blackhole, or the durable-stream client's internal retry loop — which retries 5xx responses forever without ever surfacing — left the SDK's observe() in phase 'live' indefinitely while the UI showed a spinner on a conversation that had long since moved on. The observation loop now runs a liveness watchdog: the runtime already produces transport activity at least every ~30s on both live modes (empty long-poll responses, idle SSE control events), so 90 seconds of total silence — no chunk and no activity — cancels the stream (aborting the underlying connection) and recovers through the ordinary retry backoff and a fresh history re-hydrate; a stall is not an auth failure and never consumes the bounded auth-retry budget. Relatedly, resuming at an offset the stream no longer has (a dev-server restart on the in-memory store leaves clients holding offsets beyond the regrown stream's head) now fails loud with a structured 416 stream_offset_gone error — validated before the response commits on the plain, long-poll, and SSE paths, with the requested offset and current head in error.meta — instead of surfacing as a generic 500 that the durable-stream client retried invisibly forever; 416 sits outside that client's retry set and outside the SDK's fatal set, so existing clients recover automatically through the same retry → re-hydrate path.

  • A conversation stream that is reset and regrown under a live observer (a dev-server restart on the in-memory store, a wiped store) is now detected and recovered automatically instead of silently serving a different conversation at the same offsets. The stream's durable generation identity now crosses the wire: history snapshots carry it as FlueConversationSnapshot.incarnation, and the updates view emits a minimal stream-checkpoint chunk — once per SSE connection (the first data frame, so transport-internal reconnects re-learn it) and on every JSON updates response. It rides an ordinary data frame deliberately: the durable-stream client strips response headers and unknown control-frame fields, so an in-band chunk is the only channel that reaches SDK code. observe() records the incarnation at hydrate time and, on a mismatched checkpoint, cancels the stream and re-hydrates immediately — the phase dips to 'connecting' with no error, no backoff, and no cost to the bounded auth-retry budget — closing the nastiest corner of a regrown stream: replayed positions at overlapping offsets that position dedup would otherwise silently eat. The checkpoint carries no position (it can never disturb dedup), counts as watchdog liveness, and is skipped by every other chunk consumer (wait(), the CLI presenter, the handle's read()). Relatedly, the continuity invariant the whole read path leans on — a resume offset never advances past content not yet handed to the consumer, so a connection dying at any point either replays the in-flight batch (dedup absorbs it) or resumes behind content the client already holds, and a truncated payload fails loudly into a full re-hydrate — is now documented in the SDK's stream wrapper and pinned by a dedicated suite that runs against the real @durable-streams/client, so a dependency upgrade or refactor that breaks it turns tests red instead of shipping as silent stream divergence.

  • The SDK's observe() no longer treats every 401/403 as permanently fatal. Previously any single auth failure — even a transient token-expiry race — published phase 'error' and stopped the observation until a manual refresh(), which could leave a live UI frozen on a conversation that had long since completed. Auth failures now retry through the normal reconnect backoff, and because the client's header factory re-resolves per request, each attempt carries freshly minted credentials — a token-expiry race heals on the next attempt in about a second. The retries are bounded at three consecutive failures with no intervening progress (a successful history read or an applied update chunk), after which the observation settles to phase 'error' with the last error as before, so a genuinely revoked credential still surfaces within seconds instead of retrying forever. A 400 stays immediately fatal.

  • The settlement followers — the SDK client's wait() and read() — now carry the same stall, auth, and stream-reset resilience as observe(). Previously they ran a bare loop over the conversation updates stream: a half-open connection meant waiting forever with no deadline anywhere, a single 401 from a token-expiry race rejected the wait outright, and a stream reset and regrown under the follow could serve different content at the same offsets undetected. Now 90 seconds of total transport silence cancels the dead stream, a 401/403 retries with freshly re-resolved headers (bounded at three consecutive failures with no intervening delivered chunk, after which the last auth error rejects as before; 400 and other statuses stay immediately fatal), and a mismatched stream-checkpoint incarnation or a 416 stale-offset error recreates the stream — from the admission offset, or from the origin once the admission offset is gone — instead of hanging or rejecting. Settlement scanning is pure and replay-safe, so recovery needs no history snapshot: the follow just re-reads and re-scans, with replayed chunks position-deduped so onEvent never observes a chunk twice. FlueExecutionError semantics are unchanged — failed and aborted settlements reject exactly as before. This matters most for read(), which is documented as durable re-attach from any process at any later time, where "any later time" now includes streams that stalled, credentials that flapped, and stores that were reset in between.

  • Server-side error logs are now cause-chain faithful: the renderer's log lines print every cause level (and AggregateError members) with stacks instead of one amputated level, a Cloudflare Durable Object whose SQLite stores fail to initialize logs the full chain and stacks DO-side before the constructor throw crosses the workerd tunnel message-only (the flattened message it tunnels now carries every cause message, and conversation-store init failures get the same framing instead of escaping unwrapped), and a Worker→DO forward that rejects is wrapped to name the agent, instance, and verb in the rendered log.

  • A settlement recovered from the crash window between reserve and finalize now publishes the live submission_settled event when a later reconcile pass finalizes it. Previously the submission settled durably but silently on the runtime event stream — the documented "emitted on every terminal path" contract had a hole exactly where a process died mid-settlement.

  • A joined delivery's live submission_settled event now carries the joined submission's own submissionId; the host context's decoration previously overwrote it with the host's id, so an observer keying on submissionId never saw the joined delivery settle (the durable settlement record was always correct).

  • The dev-mode lifecycle logger is now an observe() subscriber over submission_running/submission_recovery (recovery failures now show up in dev output), retiring the bespoke onInteractionStart callback that was threaded through both coordinators and both generated entries to deliver one log line.

  • The local() sandbox now resolves a command killed by its timeoutMs deadline with exit code 124 — the timeout(1) convention the sandbox contract documents and the other first-party adapters follow — instead of 1, so a model-requested timeout is distinguishable from an ordinary command failure.

  • A queued submission that can never be claimed — canonical materialization permanently failing (an agent renamed or removed after rows were admitted, an initialData schema tightened between admission and recovery, a persistently failing conversation writer) — is no longer un-terminable. Such a row had no budget, no timeout, and no settlement (the durability budget only starts at claim), and abort() couldn't save it either: abort settlement only ran through attempt-based paths, so an aborted, un-materializable submission kept waking the coordinator every 30 seconds forever. Both coordinators' unready passes now terminalize the class: a durable abort settles the row as aborted immediately (abort is the guaranteed escape hatch for every stuck class), and materialization failing past acceptedAt plus the agent's durability.timeoutMs static (store default one hour) auto-fails it with the persistent error, emitting the live submission_settled plus a submission_recovery with outcome: 'terminated'. Settlement goes through the store's first-terminal-wins queued CAS, so coordinators racing the same row converge on one settlement — and the Cloudflare Durable Object goes idle instead of re-arming its backstop indefinitely. These settlements carry no canonical stream record, so a stream-following waiter (wait()/read()) does not observe them durably; for the never-materialized classes the instance itself does not exist and a late read fails fast with AgentInstanceNotFoundError, and the settled row remains the durable outcome authority.

  • Coordinator recovery failures now reach both tracing adapters and the Sentry blueprint: @flue/opentelemetry emits submission_recovery as a stackless log record, the Cloudflare native tracing adapter records it as a span event on the ambient platform span, and the Sentry blueprint (bumped to version 4) reports it as a breadcrumb rather than an issue.

  • On Cloudflare, the whole agent response now runs inside the Durable Object's own alarm invocation instead of detaching behind the 202: admission answers first and the response begins on the next zero-delay alarm tick (typically tens of milliseconds), so invocation-scoped platform tooling — Workers observability spans, log and outcome attribution, Sentry's Durable Object wrapping — sees every model turn and tool call as one platform-visible unit instead of force-closed spans attributed to no invocation.

  • Sandbox operations can no longer hang forever when the sandbox dies mid-call. The cloudflareSandbox() adapter runs every RPC through a death detector — while a call is pending it polls the container state every 5 seconds (a Durable Object storage read, no container round trip) and rejects with the new SandboxDiedError once the container reports stopped, with an unanswered probe presuming the Durable Object itself dead — so a hung tool, attempt, or abort settles instead of waiting on an answer that will never come; there is deliberately no deadline, so a legitimately slow command on a healthy container is never interrupted (#497). SandboxDiedError is provider-neutral so ecosystem adapters can throw it for consistent shell classification, and the SandboxApi contract now states the liveness expectation for adapter authors: in-flight operations settle when the sandbox dies, by whatever mechanism the provider SDK supports, with adapters lacking one carrying a documented limitation.

  • Conversation batches larger than Cloudflare Durable Object SQLite's ~2 MB per-value cap no longer fail the append with a raw SQLITE_TOOBIG: serialized batches past 1 MB spill into 512 KB chunk rows inside the same transaction and are reassembled with validation on read, and a 12 MB pre-append ceiling turns a pathological batch into an actionable error naming the largest record's type, id, and approximate size (#289).

  • Admission owns instance identity, so a submission no longer runs full root-harness initialization twice before its first model turn — materialization previously opened a whole session (full stream reduce, agent render, a sandbox session that was then dropped undisposed, workspace discovery) just to obtain the conversation identity, and processing opened it all again (#495).

  • Conversation loads fold in place instead of cloning the reduced state once per stored batch, and resident conversation state shrinks to an index over the log: on a 30 MB delta-heavy log stored as ~3,000 batches, a from-scratch load drops from ~2.6 s to ~0.8 s, with streaming-heavy conversations gaining the most (#499).

  • A model-invoked task call naming an agent outside the declared roster now returns a plain tool result stating the miss and the current roster — the same pattern as an unknown activate_skill name — instead of throwing a typed error into an error outcome; programmatic resolution keeps SubagentNotDeclaredError (#522).

  • A Workers AI stream that ends with no error frame and no finish_reason — a response truncated in transit, Cloudflare-acknowledged transient behavior under load — is now classified retryable at the throw site and enters the bounded in-loop retry instead of hard-failing the submission.

  • AI Gateway models work fully through the Workers AI binding provider (#525): pi's cloudflare-ai-gateway catalog is hydrated into the cloudflare provider's model list (vendor-prefixed, e.g. cloudflare/openai/…), so gateway models resolve with real cost, context-window, reasoning, and image-input metadata instead of the zero-metadata fallback that silently replaced image attachments with text placeholders; openai/ gateway models are spoken in the OpenAI Responses wire format the /openai gateway route requires, where previously every non-anthropic/ id was sent a chat-completions payload and failed with a gateway 400 before any tokens streamed; and a gateway id missing from the catalog still streams (its wire format inferred from the vendor prefix) with a once-per-isolate warning naming the metadata gap.

  • @flue/redis reads HGETALL and CONFIG GET replies in both RESP2 and RESP3 shapes, fixing stream reads that saw an empty hash under node-redis v6's RESP3 default — creates read back missing and every append failed with "Stream does not exist.".

  • Webhook ingress hardening across the channel packages: signature verification awaits subtle.verify so a bad signature reports as a verification failure instead of a 500, HMAC verification keys are imported once with a guarded verify (Slack, WhatsApp, Notion, Linear, GitHub), Discord rejects signed timestamps outside a five-minute freshness window, Twilio signs every occurrence of repeated form values so distinct bodies never share a signature, Teams' signing-key cache gains a 60-second TTL floor and a cooldown on failed refresh, Notion keeps answering verification deliveries when verificationToken is configured, Telegram length-guards its constant-time secret-token compare, Google Chat answers 400 rather than 413 for a mid-stream body read failure, webhook-handler exceptions are no longer swallowed, and request body streams are cancelled without unhandled rejections.

A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.