@flue/sdk
2.3.1 · 18 Nov 2026Apache-2.0309.1k / weekRepositoryHomepagenpmAtom feed
52 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.
- 2.x · latest line
2.3.1
18 Nov 2026Updated
@earendil-works/pi-aiand@earendil-works/pi-agent-coreto 1.5.2, fixing builds that picked up pi-ai 1.5.@flue/runtime2.3.0 imported TypeBox through@earendil-works/pi-ai, which stopped re-exporting it in 1.5.0, so a fresh install failedvite build. Flue now depends ontypeboxdirectly and requires pi^1.5.0; remove any overrides that held pi at 1.4. If your own code importsTypeorStaticfrom@earendil-works/pi-ai, import them fromtypeboxinstead. Pi now validates tool arguments with its own JSON Schema validator, which coerces a little more (for example"3"for a number) and words its validation errors differently. OpenAI-compatible requests with no tools no longer send"tools":; setcompat.requiresToolsWithToolHistory: trueon models behind proxies that require it, such as older LiteLLM versions in front of Anthropic.Workers AI binding models on the Responses API declare tools the way pi's own OpenAI provider does. Since pi 1.4, the binding passed a boolean where pi expected a tool-support mode, so a model without deferred tool loading could leave tools added mid-conversation out of its request. Models that support mid-conversation tool additions now declare every tool through
additional_toolsinput items.
2.3.0
12 Oct 2026Updated
@earendil-works/pi-aiand@earendil-works/pi-agent-coreto 1.1.0. New models resolve with no configuration, including Claude Sonnet 5.5 (anthropic/claude-sonnet-5-5), Claude Haiku 5.5 (anthropic/claude-haiku-5-5), and GPT-6.1 Sol (openai/gpt-6.1-sol). Azure users must update: Pi renamed the Azure provider fromazure-openai-responsestoazure, so changeazure-openai-responses/...model specifiers andprovidersconfig entries toazure. TheAZURE_OPENAI_*environment variables are unchanged. Tool and turndurationMsvalues now come from Pi's monotonic timing, so a tool's duration covers only its execution, not Flue's hooks or result storage.useAgentFinishcallbacks once again see state written during the response. Since 2.2.0, finish hooks ran against the agent render from before the response's final turn, so a durable guard set by a finish callback — the documentedusePersistentStatepattern for appending a reminder once — was never observed: the callback re-appended on every cycle until the response failed at the runaway-loop ceiling. The agent now re-renders before each finish-hook cycle (#818).read_skill_resourceaccepts a packaged skill path without its leading/. Models often echo the advertised/.flue/packaged-skills/...path without the slash, and the read failed as not found (#781).
New Features
Updated
@earendil-works/pi-aiand@earendil-works/pi-agent-coreto 1.1.0. New models resolve with no configuration, including Claude Sonnet 5.5 (anthropic/claude-sonnet-5-5), Claude Haiku 5.5 (anthropic/claude-haiku-5-5), and GPT-6.1 Sol (openai/gpt-6.1-sol). Azure users must update: Pi renamed the Azure provider fromazure-openai-responsestoazure, so changeazure-openai-responses/...model specifiers andprovidersconfig entries toazure. TheAZURE_OPENAI_*environment variables are unchanged. Tool and turndurationMsvalues now come from Pi's monotonic timing, so a tool's duration covers only its execution, not Flue's hooks or result storage.
Fixes & Other Changes
useAgentFinishcallbacks once again see state written during the response. Since 2.2.0, finish hooks ran against the agent render from before the response's final turn, so a durable guard set by a finish callback — the documentedusePersistentStatepattern for appending a reminder once — was never observed: the callback re-appended on every cycle until the response failed at the runaway-loop ceiling. The agent now re-renders before each finish-hook cycle (#818).read_skill_resourceaccepts a packaged skill path without its leading/. Models often echo the advertised/.flue/packaged-skills/...path without the slash, and the read failed as not found (#781).The local sandbox SIGKILLs a command's whole process group after the grace period, even when the shell exits first. On an
exec()timeout or abort, the pending SIGKILL was cancelled once the shell's pipes closed, so a process that ignored SIGTERM and held none of the shell's output kept running afterexec()returned (#809).Execution interceptors see
agentNameon model, tool, and shell steps, not only on the outeragentoperation. The root harness's execution context carried only the instance id, so an interceptor that branches per agent took its default branch on every step (#785).flue init --target cloudflarescaffolds the Workers AI binding that keylesscloudflare/...models need, commented out inwrangler.jsonc. The generated agent suggested switching to a keyless Cloudflare model but nothing declaredenv.AI; it now points at the binding to uncomment. The binding stays off by default because it reaches your Cloudflare account even in local dev (#739).The E2B sandbox blueprint returns a non-zero exit from
exec()instead of throwing. E2B'scommands.run()throwsCommandExitErroron a non-zero exit, so a failing command rejected with no command or stderr instead of resolving with itsexitCode. The blueprint is bumped to version 2; runflue update sandbox e2bto update an existing integration (#805).
2.2.2
28 Sep 2026No changes in this release.
2.2.1
28 Sep 2026No changes in this release.
2.2.0
28 Sep 2026Add bounded conversation history reads so long-running chats no longer transfer the whole transcript on every page load or reconnect.
Unbounded reads are unchanged.
@flue/reactstill observes the whole conversation.Support document attachments (PDFs) on user messages.
DeliveredAttachmentis now a union of image and document attachments —{ type: 'document', data, mimeType: 'application/pdf', filename? }— accepted ondispatch(), theinit()handle, and direct HTTP prompts.session.prompt(),skill(), andtask()gain adocumentsoption alongsideimages, and@flue/react'ssendMessage()gains adocumentsoption. Documents are forwarded to the model as native document content: Anthropicdocumentblocks, OpenAI (and Azure OpenAI) Responsesinput_fileparts, and GoogleinlineData. On other model APIs the document is replaced in model context with a text placeholder saying it was omitted. Documents are stored like images — as canonical attachments projected asfileparts withmediaType: 'application/pdf'— so existing conversations and persistence adapters need no migration. The SDK also exportsDeliveredImageAttachmentandDeliveredDocumentAttachment.Conversation messages now carry a server-authored
timestamp(ISO 8601 capture time of the underlying durable record) inhistory(),observe(), anduseFlueAgent. It works for every role and for existing conversations.metadataremains entirely agent-authored. Conversation settlements carry the sametimestampfor when the submission settled.
2.1.1
23 Sep 2026Clarify that a skill's
allowed-toolsfield is guidance. Flue accepts it for Agent Skills spec compatibility and does not enforce it; enforce authorization in your own tools and approval gates.Record tool arguments and results of every payload shape on the standard
gen_ai.tool.call.arguments/gen_ai.tool.call.resultattributes, so OTel backends can display them. The shape-based diversion to the vendorflue.tool.call.*fallback keys is removed — those keys are no longer emitted, and their constants are retained for source compatibility. Payloads record exactly as before: objects/arrays as JSON strings, strings byte-for-byte within the content budget, other scalars as their JSON form.
2.1.0
18 Sep 2026The OpenTelemetry ecosystem page and Cloudflare target guide now document
contentBudgetBytesoncreateOpenTelemetryInstrumentation()/createCloudflareTracing(): an override for the default 56 KiB per-span content pool. Raising it ships fuller content only on backends not bound by workerd's span cap (the OpenTelemetry adapter); on the Cloudflare target it is a tightening control only, since workerd's 64 KiB span-attribute cap is a platform limit no setting raises.The MCP guide and Agent API reference now document preserved MCP tool annotations, including how trusted applications can inspect them and why server-supplied hints are not a security boundary.
The Tools guide and agent API reference now document
timeoutMson tool definitions: a per-call execution bound that aborts the tool'scontext.signaland settles the call with aToolTimeoutErrorinstead of letting one hung call consume the submission's durability budget.
2.0.8
16 Sep 2026The Cloudflare Sandbox documentation page now presents
flue add sandbox cloudflareas a copyable prompt for your coding agent, with an explainer of what the blueprint-driven agent may do — installing@cloudflare/sandbox, wiring the Durable Object binding, migration, and containerDockerfile, and updating the agent to use the sandbox.
2.0.7
15 Sep 2026Installed packages once again include the bundled Flue documentation, so commands such as
flue docs read guide/sandboxeswork out of the box.Fix delayed reconnects in
observe(): after a stream has been healthy for a full stream lifetime, the reconnect backoff resets, so a subsequent disconnect reconnects promptly instead of applying a stale delay.
2.0.6
14 Sep 2026Published packages once again include the bundled Flue documentation. The 2.0.4 and 2.0.5 releases omitted the generated
docs/directories from@flue/cli,@flue/runtime, and@flue/sdk, causing commands such asflue docs read guide/sandboxesto fail.
2.0.5
11 Sep 2026Published packages once again resolve internal Flue dependencies to the release version. The 2.0.4 release accidentally shipped raw pnpm
workspace:dependency specifiers, making affected packages impossible to install outside the workspace. The complete lockstep package set is republished as 2.0.5 through pnpm so every internal dependency resolves to 2.0.5 (#657).
2.0.4
9 Sep 2026"Connection error."is now classified as a retryable model error. The retryable-error matcher recognizedconnection reset/connection refused/connection lostbut not a bareconnection error— a transient "Connection error." (with its trailing period) fell through the pattern and terminated the submission as a hard failure. The matcher now also acceptsconnection errorand the run retries it under the transient-error budget (#629).
2.0.3
5 Aug 2026The Cloudflare Agents SDK (
agents) is now a dependency of@flue/vite— projects no longer declare it. The generated Worker entry is the only code that imports the SDK, so the package that generates it ships it, and every project runs the SDK version Flue was tested against instead of whatever a scaffolded range resolves to on install day;flue init --target cloudflarestops writing the dependency, and existing projects can delete theirs. A project that declares its ownagentsdependency still wins — the plugin only falls back to its bundled copy when the project'snode_moduleschain has none. This also unbreaks fresh installs, which failed on anaipeer conflict internal toagents@0.14.5, the newest version the scaffolded^0.14.2range had come to resolve (reported by Ben Buzbee). The scaffoldedwranglerrange moves to^4.113.0.
2.0.2
4 Aug 2026Conditional tool additions are now cache-safe on models with deferred tool loading. A tool mounted by the rerender that follows a settled tool batch is anchored to that batch's final tool result, so current first-party Anthropic models (Claude 4.5 and later, excluding Haiku) keep the added definition out of the cached prompt prefix instead of invalidating it; other providers ignore the anchor and their requests are unchanged. The anchor persists with the run and is restored on rehydration, so a rehydrated context matches the live loop exactly (the internal reduced-state format counter bumps to 2). The Tools guide now states the actual cache contract: tool-set changes rewrite the native tools array and invalidate the provider prompt cache, except additions unlocked by a completed tool call on the models above (#545).
The
cloudflare-shellblueprint is replaced bycloudflare-computer, built on@cloudflare/computer— the successor to@cloudflare/shellthat hosts a durable SQLite-backed workspace in the agent's own Durable Object with ajust-bashshell backend, and can escalate to a container backend where a JavaScript shell isn't enough. The adapter provides a realexec()and keeps the framework's standard tool set instead of substituting a code tool.flue add cloudflare-shelland the old docs URLs redirect to the successor.Cloudflare trace spans whose terminal event never arrives (their operation orphaned by deadline force-settlement or recovery) are force-closed when the submission settles, so the run's
invoke_agentroot span no longer vanishes from the trace. Forced closes carry aflue.span.forced_closeattribute, and span-close failures are reported instead of swallowed.
Fixes & Other Changes
Conditional tool additions are now cache-safe on models with deferred tool loading. A tool mounted by the rerender that follows a settled tool batch is anchored to that batch's final tool result, so current first-party Anthropic models (Claude 4.5 and later, excluding Haiku) keep the added definition out of the cached prompt prefix instead of invalidating it; other providers ignore the anchor and their requests are unchanged. The anchor persists with the run and is restored on rehydration, so a rehydrated context matches the live loop exactly (the internal reduced-state format counter bumps to 2). The Tools guide now states the actual cache contract: tool-set changes rewrite the native tools array and invalidate the provider prompt cache, except additions unlocked by a completed tool call on the models above (#545).
The
cloudflare-shellblueprint is replaced bycloudflare-computer, built on@cloudflare/computer— the successor to@cloudflare/shellthat hosts a durable SQLite-backed workspace in the agent's own Durable Object with ajust-bashshell backend, and can escalate to a container backend where a JavaScript shell isn't enough. The adapter provides a realexec()and keeps the framework's standard tool set instead of substituting a code tool.flue add cloudflare-shelland the old docs URLs redirect to the successor.Cloudflare trace spans whose terminal event never arrives (their operation orphaned by deadline force-settlement or recovery) are force-closed when the submission settles, so the run's
invoke_agentroot span no longer vanishes from the trace. Forced closes carry aflue.span.forced_closeattribute, and span-close failures are reported instead of swallowed.The sandbox types are renamed to match their roles; the old names remain as deprecated aliases.
SessionEnv→Sandbox(the live environment handle behindharness.sandboxand the standard tools),SandboxApi→SandboxDriver(the per-provider interface a sandbox adapter implements),createSandboxSessionEnv()→sandboxFromDriver(),SessionToolFactory/SessionToolFactoryOptions→SandboxToolFactory/SandboxToolFactoryOptions, andSandboxFactory.createSessionEnv()→createSandbox(). No action is required: the old type names andcreateSandboxSessionEnvare exported as deprecated aliases, and a factory implementing only the legacycreateSessionEnv()method still initializes (with a one-time deprecation warning). Blueprints, examples, and docs emit the new names.New docs reference page: Agent Behavior — the out-of-the-box runtime contract in one place: the built-in tools' parameters and truncation limits, environment defaults, message admission and turn-boundary joining, context composition and compaction, and the enforced limits.
2.0.1
1 Aug 2026Reasoning effort sent through the Workers AI binding's Responses wire format is now clamped to the
/runendpoint'snone|low|medium|highceiling. A gateway model whose catalog maps thexhigh/maxthinking levels verbatim (for exampleopenai/gpt-5.6-luna) previously hard-400ed after admission for a thinking level Flue itself accepts — those catalog mappings are written for the model's own API, which does accept them over the HTTP gateway path; the ceiling is the binding transport's, and the chat-completions path already applied it. The emitted effort now always comes from the catalog's ownlow/medium/highmappings (#544).A durable submission can no longer sit unsettled forever behind a hung await. On Cloudflare the wake handler previously both executed and supervised — it awaited every attempt, so one stalled model stream or sandbox RPC wedged the only loop that evaluates durability timeouts, and a backstop alarm firing mid-drain was silently consumed without re-arming. The coordinator now separates the roles: supervisor passes run bounded and storage-only (arming their successor heartbeat before any failable work, so no pass failure breaks the wake chain), and attempt fibers run detached, settling their own submissions. Deadline enforcement is structural on both targets: each pass fires the attempt's abort controller at
timeoutAt(or on an unhonored durable abort) so signal-aware awaits unwind through the normal settle paths, and once the first signal outlives a 60-second grace the pass force-settles the submission over the hung fiber, orphaning it — the Node coordinator gets the same sweep from its lease scan, whose expired-lease branch was previously unreachable while a live process renewed a hung attempt's lease forever. A newFlueEventoperation,enforce_deadline, marks the signaled grace window and the force; the per-drain attempt cap is retired as vestigial (#538).The awaits that could stall an attempt now bound themselves, so a stall recovers in seconds-to-minutes instead of failing at the durability deadline. Model streams on the Workers AI binding provider get an idle deadline: a chunk gap past the cap fails the read as a retryable interruption — the exact reported shape, a 200 that never speaks again, becomes a retried turn under the transient-error budget. The default is 5 minutes (long-thinking models can be legitimately silent), configurable per provider via
streamIdleTimeoutMs, with0disabling it, and the timer only runs while a source read is outstanding so consumer backpressure never trips it.GatewayOptions.requestTimeoutMs— previously declared but never sent — is now emitted as thecf-aig-request-timeoutheader, a gateway-enforced bound on time to first response. Tools are abandoned on abort: every tool run races the attempt signal, so a signal-deaf tool (a sandbox file operation with no abort plumbing) rejects at abort instead of wedging the turn past every deadline, under the same orphaned-work contract as an orphaned exec (#538).
Fixes & Other Changes
Reasoning effort sent through the Workers AI binding's Responses wire format is now clamped to the
/runendpoint'snone|low|medium|highceiling. A gateway model whose catalog maps thexhigh/maxthinking levels verbatim (for exampleopenai/gpt-5.6-luna) previously hard-400ed after admission for a thinking level Flue itself accepts — those catalog mappings are written for the model's own API, which does accept them over the HTTP gateway path; the ceiling is the binding transport's, and the chat-completions path already applied it. The emitted effort now always comes from the catalog's ownlow/medium/highmappings (#544).A durable submission can no longer sit unsettled forever behind a hung await. On Cloudflare the wake handler previously both executed and supervised — it awaited every attempt, so one stalled model stream or sandbox RPC wedged the only loop that evaluates durability timeouts, and a backstop alarm firing mid-drain was silently consumed without re-arming. The coordinator now separates the roles: supervisor passes run bounded and storage-only (arming their successor heartbeat before any failable work, so no pass failure breaks the wake chain), and attempt fibers run detached, settling their own submissions. Deadline enforcement is structural on both targets: each pass fires the attempt's abort controller at
timeoutAt(or on an unhonored durable abort) so signal-aware awaits unwind through the normal settle paths, and once the first signal outlives a 60-second grace the pass force-settles the submission over the hung fiber, orphaning it — the Node coordinator gets the same sweep from its lease scan, whose expired-lease branch was previously unreachable while a live process renewed a hung attempt's lease forever. A newFlueEventoperation,enforce_deadline, marks the signaled grace window and the force; the per-drain attempt cap is retired as vestigial (#538).The awaits that could stall an attempt now bound themselves, so a stall recovers in seconds-to-minutes instead of failing at the durability deadline. Model streams on the Workers AI binding provider get an idle deadline: a chunk gap past the cap fails the read as a retryable interruption — the exact reported shape, a 200 that never speaks again, becomes a retried turn under the transient-error budget. The default is 5 minutes (long-thinking models can be legitimately silent), configurable per provider via
streamIdleTimeoutMs, with0disabling it, and the timer only runs while a source read is outstanding so consumer backpressure never trips it.GatewayOptions.requestTimeoutMs— previously declared but never sent — is now emitted as thecf-aig-request-timeoutheader, a gateway-enforced bound on time to first response. Tools are abandoned on abort: every tool run races the attempt signal, so a signal-deaf tool (a sandbox file operation with no abort plumbing) rejects at abort instead of wedging the turn past every deadline, under the same orphaned-work contract as an orphaned exec (#538).Settlement events no longer vanish in an invocation's final moments.
observe()subscriber deliveries were fire-and-forget on the emit path, so asubmission_settledemitted late in a Cloudflare alarm invocation could be torn down mid-POST before a host's bridge saw it; in-flight deliveries are now handed to the platform at every invocation boundary (emission still never awaits subscribers). And a settlement reservation refused while its row stays unsettled — the class that used to loop the heartbeat with completely empty logs — now writes a structured error log and publishes asubmission_recoveryevent on every occurrence, so the condition alerts at wake cadence instead of staying invisible (#538).
2.0.0
31 Jul 2026- Breaking
Flue is now a Vite plugin —
flue devandflue buildare removed. Adopt Flue by addingflue()from the new@flue/vitepackage tovite.config.ts;vite devandvite buildown the deployable application. The Node target emitsdist/server.mjs(run it withnode dist/server.mjs;vite previewfor Node is deferred). The Cloudflare target is the official@cloudflare/vite-pluginas an explicit sibling —plugins: [flue(), cloudflare({ config: flueWorkerConfig() })]— with the target auto-detected fromcloudflare()'s presence;wrangler.jsoncstays user-owned, and Flue's contributions (the generated Worker entry, served as thevirtual:flue/workermodule, and the per-agent Durable Object bindings) are applied in memory by theflueWorkerConfig()customizer — nothing is generated into the project tree.flue.config.tssurvives as the host-independent project config:defineConfigmoves to@flue/runtime/config(the@flue/cli/configexport is removed), the accepted fields aretarget,app,db,cloudflare,agents(a glob narrowing the'use agent'scan),providers, andtracing, and theroot/outputfields and namedviteexport are dropped. See the migration guide for the full before/after. - Breaking
File-based routing is removed —
app.tsis the route map. Thesrc/agents/*,src/workflows/*, andsrc/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 anagentNamestatic pinning it — never from the file (on Cloudflare, one generatedFlue<PascalName>AgentDurable Object class per exported agent function; renaming an unpinned function is the storage-identity change, expressed with wrangler-nativerenamed_classes, and colliding identities are a build error — renaming the file changes nothing). Every HTTP route is mounted explicitly inapp.ts:app.route('/agents/triage', createAgentRouter(Triage))for agents (createAgentRouterfrom@flue/runtime/routing),app.route('/channels/slack', slack.route())for channels (hand-rolled channels mount viacreateChannelRouter). 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 exportsroute(middleware),attachments, anddescriptionare removed along with the convention that read them: protect a mount with ordinary middleware layered inapp.tsbefore it, and the attachment byte route is part of every agent router rather than opt-in.createDefaultFlueApp()and the runtimeflue()router are removed; a missingapp.tsis a build error. - Breaking
Workflows are removed.
defineWorkflow,invoke, run stores and run event streams, the/runs/:runIdandPOST /workflows/:nameroutes (including?wait=result),listRuns/getRun, the SDKclient.workflows/client.runsnamespaces, 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 runin a shell or CI step, thestart()/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-modelrun()body) has no direct replacement. The migration guide covers the conversion.
Breaking Changes
- Breaking
Flue is now a Vite plugin —
flue devandflue buildare removed. Adopt Flue by addingflue()from the new@flue/vitepackage tovite.config.ts;vite devandvite buildown the deployable application. The Node target emitsdist/server.mjs(run it withnode dist/server.mjs;vite previewfor Node is deferred). The Cloudflare target is the official@cloudflare/vite-pluginas an explicit sibling —plugins: [flue(), cloudflare({ config: flueWorkerConfig() })]— with the target auto-detected fromcloudflare()'s presence;wrangler.jsoncstays user-owned, and Flue's contributions (the generated Worker entry, served as thevirtual:flue/workermodule, and the per-agent Durable Object bindings) are applied in memory by theflueWorkerConfig()customizer — nothing is generated into the project tree.flue.config.tssurvives as the host-independent project config:defineConfigmoves to@flue/runtime/config(the@flue/cli/configexport is removed), the accepted fields aretarget,app,db,cloudflare,agents(a glob narrowing the'use agent'scan),providers, andtracing, and theroot/outputfields and namedviteexport are dropped. See the migration guide for the full before/after. - Breaking
File-based routing is removed —
app.tsis the route map. Thesrc/agents/*,src/workflows/*, andsrc/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 anagentNamestatic pinning it — never from the file (on Cloudflare, one generatedFlue<PascalName>AgentDurable Object class per exported agent function; renaming an unpinned function is the storage-identity change, expressed with wrangler-nativerenamed_classes, and colliding identities are a build error — renaming the file changes nothing). Every HTTP route is mounted explicitly inapp.ts:app.route('/agents/triage', createAgentRouter(Triage))for agents (createAgentRouterfrom@flue/runtime/routing),app.route('/channels/slack', slack.route())for channels (hand-rolled channels mount viacreateChannelRouter). 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 exportsroute(middleware),attachments, anddescriptionare removed along with the convention that read them: protect a mount with ordinary middleware layered inapp.tsbefore it, and the attachment byte route is part of every agent router rather than opt-in.createDefaultFlueApp()and the runtimeflue()router are removed; a missingapp.tsis a build error. - Breaking
Workflows are removed.
defineWorkflow,invoke, run stores and run event streams, the/runs/:runIdandPOST /workflows/:nameroutes (including?wait=result),listRuns/getRun, the SDKclient.workflows/client.runsnamespaces, 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 runin a shell or CI step, thestart()/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-modelrun()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
defineAgentis removed. A beta agent was adefineAgent(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 oldmodel/thinkingLevel/compactionconfig 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 hooksuseAgentStart(run),useAgentFinish(run)(whosectx.appendcan send the model back to work in the same response),useResponseStart(fn), anduseResponseFinish(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 ordinaryuse*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), anddurability({ maxAttempts, timeoutMs }, previously a config field). Deleted with the old model:defineAgent,createAgent,defineAgentProfileandAgentProfile, and the whole Actions surface (defineAction, theactions: [...]list, and their error types) — a model-invoked job is auseTooltool now, withharness: truefor 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-presenttasktool,GeneralSubagentis the exported general-purpose delegate, and ataskcall can only name a declared subagent. See the migration guide. - Breaking
The tool
run()context and the harness are reshaped.ToolContextis now{ toolCallId, log, signal? }plusdata— the schema-parsed arguments, renamed frominput— when the tool declares aninputschema,harnesswhen it declaresharness: true, andstepwhen it declaresdurable: true; every tool getslogfor structured progress events. The harness handed toharness: truetools and to theuseAgentStart/useAgentFinishcontexts flattens to{ name, prompt(), compact(), sandbox }:session(),sessions,shell(), andfsare removed, andharness.sandboxis the liveSessionEnv(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 aSandboxFactory's optionaltools()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.sandboxand 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 isuseSandbox(bash(() => new Bash({ fs: new InMemoryFs() })))withjust-bashadded 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 fullenvironmentsignal (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.mdpackages that skill directory at build time and yields aSkillReferenceforuseSkill(...)(static imports only; frontmatter validated against the Agent Skills spec); importing any other.mdfile yields the markdown text as a plain string, whichdefineSkill({ name, description, instructions })turns into a skill. Thewith { type: 'skill' }andwith { type: 'markdown' }attribute forms are removed.defineSkillnow validates and freezes instead of packaging —instructionsis required, packaging happens lazily, and the runtime writes the frontmatter — anduseSkill(...)accepts aSkillReferenceor aSkillDefinitiondirectly. 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'sactivate_skilltool. - Breaking
MCP servers are declared as connection definitions;
connectMcpServeris removed. One flatMcpConnectionDefinition({ name, url, transport?, auth?, headers?, tools?, optional?, timeoutMs?, … }) drives the whole surface:useMcpConnection(definition)declares a server from the agent render — its tools mount asmcp__<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), andcreateMcpConnection(definition)is the imperative factory replacing the beta'sconnectMcpServer(name, options)for module-scope use on the Node target (McpServerConnectionis renamedMcpConnection). 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; andoptional: true— a server that fails to resolve mounts zero tools for that submission instead of failing it, announced to the model once as aresourcessignal 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:
registerProviderandregisterApiProviderare removed, and theproviderslist is exhaustive. A custom or customized provider is a pi-aiProviderobject registered withsetProvider(provider)— built withcreateProvider(...)and the built-in factories from@earendil-works/pi-ai, which you depend on directly — replacing the beta's option-bagregisterProvider(id, { ... }),registerApiProvider, and the deprecatedpi-ai/compatlayer under them (model capabilities such asreasoning,input,contextWindow, andcostare plain fields on theModelobjects a provider declares). Model specifiers keep the'provider-id/model-id'format. The newproviders?: stringconfig (influe.config.tsor inline on theflue()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/cloudflarewithproviders: ['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 asstart({ providers }), takingProviderobjects. - Breaking
Channel helper APIs are renamed
instanceId/parseInstanceId. The value these helpers produce was always the agent instance id, so every channel package renamesconversationKey→instanceIdandparseConversationKey→parseInstanceId(zendesk'sticketKey/parseTicketKeyincluded), with theInvalid*ConversationKeyErrorclasses following asInvalid*InstanceIdError— a clean break, no aliases.parseInstanceIdis 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.tsis 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) withsend(),wait(),history(),observe(),abort(), andattachmentUrl(). ThebaseUrl+ agent-name/id addressing, theclient.agentsnamespace, andlistAgents()are removed; a new conversation is the caller appending a fresh id to the mount URL.@flue/react'suseFlueAgent({ url })replacesuseFlueAgent({ 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
UIMessageper response. Clients that keyed logic on per-step assistant messages see fewer, larger messages; the chunk wire vocabulary is unchanged. - Breaking
The
@flue/dev-consoleTUI 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 futureflue devexperience. - Breaking
flue runis rewritten as transport-free local execution, and the CLI slims torun/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--jsonenvelope) prints to stdout, and the conversation id is printed so--idcan continue the same conversation across invocations. Persistence honors the project'sdb.tswhen 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 devandflue builderror with pointers to the Vite commands. - Breaking
dispatch()takes a structuredmessage, not an opaqueinput.AgentDispatchRequest.input: unknownis replaced bymessage: 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.bodyis always a string — JSON-stringify structured payloads yourself.dispatch()can now deliver akind: 'user'message with image attachments, the same way a direct HTTP prompt does (attachments onkind: 'signal'are not supported).messageis validated the same way as a direct prompt's body (a malformedmessagethrowsInvalidRequestError) instead of being forwarded unchecked. On the adapter surface, the submission input types collapse into oneAgentSubmissionInputinterface ({ kind: 'dispatch' | 'direct', submissionId, agent, id, message, acceptedAt }) —DispatchAgentSubmissionInputandDirectAgentSubmissionInputare removed, a dispatched submission's persisted input carries onlysubmissionId(no separate dispatch-scoped id), and the persisted-attachment helpers exported from@flue/runtime/adapterare renamed:prepareDirectSubmission→prepareSubmissionAttachments,hydratePersistedDirectSubmission→hydratePersistedSubmissionAttachments,matchesPersistedDirectSubmission→matchesPersistedSubmissionAttachments. Every first-party channel example and blueprint is updated to the new shape, following one convention:bodycarries the message itself and structured metadata (sender identity, ids, titles) goes inattributesas flat strings. - Breaking
dispatch()targets an agent definition, not a name string. The single signature isdispatch(agent, { id, message }), whereagentis the default export of a'use agent'module. Thedispatch({ agent: '<name>', id, message })named-string form is removed — a non-definition first argument throwsInvalidRequestError— and theNamedAgentDispatchRequesttype is no longer exported from@flue/runtime. - Breaking
The direct agent HTTP wire body is a
DeliveredMessage.POST /agents/:name/:idnow accepts the same validatedDeliveredMessageshapedispatch()admits —{ "kind": "user", "body": "...", "attachments"?: [...] }for a chat turn (or akind: 'signal'event) — replacing the{ message, images? }wire body and the internal mapping layer behind it.@flue/sdk'sAgentPromptOptions.messageis now aDeliveredMessage(wasstring; theimagesoption folds intoattachments), andAgentPromptImageis renamedDeliveredAttachmentin@flue/sdkand@flue/react. TheDirectAgentPayloadtype is removed from@flue/runtime.flue rundelivers its--messagetext as akind: 'user'message. - Breaking
Signal
tagNamemust be a valid XML tag name. The optionaltagNameon akind: '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 throwsInvalidRequestErrorat admission instead of injecting markup past the body/attribute escaping. - Breaking
Direct agent prompts are fire-and-forget only. The
?wait=resultsynchronous mode on agent HTTP POSTs is removed; agent prompts always return a 202 admission. The in-process observer registry (createAgentSubmissionObserverRegistry,AgentSubmissionObserver,AgentSubmissionObserverRegistry), theDirectAttachedOptions/invokeDirectAttached/runDirectSyncModeadmission path, and theresultfield onSubmissionSettledRecord,AgentConversationSettlement,AgentSubmissionSettledEvent, and thesubmission_settledFlueEvent variant are all removed. Callers that need the actual assistant reply should read it from the conversation transcript via the conversation client'shistory()or the live conversation stream. - Breaking
The SDK's
prompt()is removed. Use the conversation client'ssend()(fire-and-forget) pluswait()(completion-await, nowPromise<void>) plushistory()(to read the reply).AgentPromptResultandAgentPromptResponsetypes are removed from@flue/sdk. - Breaking
The SDK's
wait()no longer resolves with a result. It resolvesvoidon completion and throwsFlueExecutionErroron failure or abort. A remote abort is now distinguishable from a real failure:FlueExecutionError.failureis'aborted'for an aborted settlement (previously both classified as'failed'). - Breaking
AttachedAgentEventCallbacktype removed from@flue/runtime. TheonEventcallback parameter on admission no longer exists. - Breaking
reconcileInterruptedSubmissionreturn type simplified. ReturnsAgentSubmission | undefined(the replacement submission, orundefined) instead of the 5-variantReconciliationResultdiscriminated union. Custom coordinator implementations that inspected.dispositionshould branch on truthiness instead. - Breaking
The
init()handle'sdispatch()is enqueue-only; awaiting the reply is the newread().handle.dispatch(request)now resolves at admission with the durableDispatchReceipt— the same contract as the top-leveldispatch(), 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 tohandle.read(receipt | submissionId, { onEvent?, signal? }), which resolves with theAgentReply(rejecting withAgentRunErroron 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()'ssignalstops only the read (a local cancel; previously the dispatch signal requested a durable abort of the run) — the durable abort intent is the new explicithandle.abort(), which covers the running head and every queued submission. A read addressed to an instance that does not exist rejects withAgentInstanceNotFoundErroron every target rather than waiting for work that can never settle. TheAgentDispatchOptionstype is renamedAgentReadOptionsand belongs toread(). - Breaking
One id vocabulary end to end:
dispatchIdis renamedsubmissionId.DispatchReceipt.dispatchId(the fielddispatch(),handle.dispatch(), anduseDispatchMessage()resolve with) is nowDispatchReceipt.submissionId;handle.read(receipt)andhandle.read(submissionId)are unaffected, and a bare-string read target is still the receipt's id, just spelledsubmissionId. New dispatch submission ids aresub_-prefixed (previouslydispatch_); ids remain opaque and olddispatch_-prefixed ids stay valid. - Breaking
FlueEventno longer has adispatchIdcorrelation field.submissionIdalone identifies a submission's activity — dispatched and direct alike — on every event and onFlueExecutionContext; code that branched ondispatchIdshould readsubmissionIdinstead. See the Events Reference. - Breaking
The
flue.dispatch.idtelemetry attribute is removed.@flue/opentelemetryand 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 tocontent?: false | { transform }. Both trace adapters —createOpenTelemetryInstrumentation()and the native CloudflarecreateCloudflareTracing()— now emit conversation content (gen_ai.input/output.messages, system instructions, tool definitions/arguments/results) unless you passcontent: false; installing an instrumentation withinstrument(...)is the consent (on Cloudflare, enabling Workers Traces), and atransformis the policy hook. On@flue/opentelemetrythis removesGenAIContentPolicyas a public type along withenabled,inline,externalContent(a side-effecting transform is the replacement —GenAIContentScopenow carriestraceId/spanIdfor correlation),limits(slice in the transform, or use the exportedtruncateContent(content, { maxBytes })), and thediagnosticcallback. Exception message and stack now ship by default through the same gate (strip them with a transform onexception_message/exception_stacktrace, or disable content); the Cloudflare adapter continues to exclude them unconditionally. Theflue.telemetry.content.*.truncated/.omittedmarker 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 arole: "flue"sentinel message and oversized strings cut with a[flue:truncated, …]suffix (FLUE_TELEMETRY_EXTENSION_REVISIONis now4).@flue/opentelemetryrequires a@flue/runtimeversion shipping the./telemetrysubpath. - Breaking
GEN_AI_SCHEMA_URLis removed, and@flue/opentelemetry's tracer/meter no longer declare aschemaUrl. 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 thegen_ai.*keys were read from remains exported asGEN_AI_SEMCONV_REVISION. - Breaking
Persisted stores are stamped
format_version1, and stores written by 1.0.0-beta.x are rejected. Every persisted Flue store durably records the format version it was created with — aformat_versionkey in the SQL backends'flue_metatable, the equivalent on the non-SQL adapters — and refuses to open anything else, throwingPersistedFormatVersionError(type: 'persisted_format_version_unsupported'). The persisted shapes changed incompatibly across the 2.0 line (one unifiedmessageinput for both transports, thesubmission_idcolumn 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/adapterasFLUE_FORMAT_VERSIONandassertSupportedFlueFormatVersion()(replacingFLUE_SCHEMA_VERSIONandPersistedSchemaVersionError), anddefineStoreContractTestsexercises the stamping rules on every backend. - Breaking
A tool's
run()returns a result envelope —{ output?, terminate? }— and bare non-string values are rejected.outputis the tool's result value, validated against the declaredoutputschema and serialized for the model exactly as before;terminate: trueends the agent's turn once the current tool batch settles — the same loop-ending contract the built-infinish/give_uptools 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 barestringremains shorthand for{ output: <string> }, and returning nothing is still allowed for tools without anoutputschema; any other bare value (number, boolean, array, null) or an object with keys beyondoutput/terminatenow 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 byfinish/give_up. - Breaking
SessionEnv.execnow rejects promptly on abort — an un-cancellable sandbox command becomes a documented orphan. Whenoptions.signalaborts mid-command, the returned promise rejects withAbortErrorimmediately 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, thesubmission_abortedadvisory, and the next queued prompt — until the command finished on its own. The guarantee is implemented once, in the runtime's wrappers (createSandboxSessionEnvand thebash()factory adapter), soSandboxApiitself 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 lateSandboxDiedErrorfrom an orphan is swallowed into the settlement), and is observable through the new optionalcreateSandboxSessionEnv(api, cwd, { onOrphanSettled })callback with the exportedOrphanedExecSettlementtype. 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-rolledSessionEnvimplementations built without the wrappers are now out of contract if they late-reject. The sandbox reference's "do not simulate mid-flight cancellation withPromise.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
AgentSubmissionStoregains 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). CustomAgentSubmissionStoreimplementations 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, anddefineStoreContractTestsnow exercises it unconditionally.
New Features
Idempotent delivery: name a send with
idempotencyKeyand 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 theinit()handle's dispatch), a reservedidempotencyKeybody sibling besideinitialData/uidon the directPOST /agents/:name/:id, andsend({ 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 markeddeduplicated: trueand echoing the originalacceptedAt(direct replays re-attach from the stream origin offset). The key names the delivery, not the outcome: a submission that settledfailedstays 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 inmeta.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_idfor Slack); the channel READMEs and guide show the mapping.New
@flue/runtime/telemetrysubpath: 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, thetruncateContent(content, { maxBytes })helper (same structural in-band truncation and[flue]sentinels as the built-in safety net, for tighter policy budgets inside a transform), theCONTENT_ATTRvocabulary, 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 samegen_ai.*attributes the OTel adapter emits, so Flue conversations read directly in the Traces dashboard.content: falserestores content-free spans;content: { transform }redacts or drops in code. Raw error messages and stacks never ship on this backend, caller-originbashis traced as the same flue-ownedflue.operation shellspan@flue/opentelemetryemits — nogen_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_toolspans, noinstrument(...)line needed. InstallingcreateCloudflareTracing(...)yourself customizes as before;tracing: falseinflue.config.tsopts out.Public conversation messages now expose typed
purpose(user,assistant,dispatch, oradvisory) anddisplay(visible,hidden, ordiagnostic), plus optionalturnIdgrouping and asignaldescriptor, 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 conversationhistory()snapshots and live updates, and@flue/sdk/@flue/reactshapes are updated in lockstep (#404).vite previewnow works on the Node target.vite buildemits two entries — the self-startingdist/server.mjsand the non-listeningdist/app.mjsapplication chunk it imports — and preview serves the builtapp.mjsnatively (no Vite transformation), so what preview serves is exactly whatnode dist/server.mjswould serve, including production persistence defaults and the real process environment. Running preview without an artifact fails with "Runvite buildfirst."vite devon the Node target now loads the project's.envfile set (.env,.env.local,.env.<mode>,.env.<mode>.local) into the application's environment, with shell-exported values taking precedence — matchingflue run, so model-provider keys work without a shell export. The built server still reads only the real environment, and Cloudflare.dev.vars/.envhandling 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 initis now interactive and scaffolds the full project skeleton for the new surface instead of onlyflue.config.ts: missing choices are prompted, with--targetand--deployanswering them for scripted runs, and when the HTTP server setup is included it also writes avite.config.tswith theflue()plugin (pluscloudflare()on the Cloudflare target), a startersrc/app.tsroute map, and — on the Cloudflare target — awrangler.jsoncwithnodejs_compat,observability.tracesenabled, and commented migration guidance.--forcestill applies only toflue.config.*; the other files are created only when absent and never overwritten.@flue/react'suseFlueAgent()now exposesrefresh(), 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-HTTPFlueErrorthat escaped to a route), it mints anerr_-prefixed ULID and stamps it in three places: the envelope's newerror.reffield, a newflue-error-refresponse 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 W3Ctraceparent, it is logged beside the ref (never echoed on the response).@flue/sdk'sFlueApiErrorexposes the ref asref(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 thesubmissionId, 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_queuedis emitted immediately after durable admission on both targets (at-least-once — idempotent replays re-emit);submission_runningis emitted from the attempt's own context on every attempt, carryingattemptCount/maxAttempts, so a recovery replacement re-announces itself with the incremented count; andsubmission_recoverysurfaces every contained coordinator recovery failure — admission-side materialization, settlement finalization, interrupted-attempt reconciliation, attempt start/processing, and pass-wide failures — withoperation/outcomediscriminators, the same stackless error shape assubmission_settled(the live observation adds the classifiederrorInfowith 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 structuredconsole.errorremains). Deriving per-instance busy/idle by keyingqueued/runningagainstsettledonsubmissionIdis 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 specificevent.types are unaffected (exhaustiveswitchstatements need a default arm). See the Events Reference.start()andinit(): 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 optionalPersistenceAdapter(default: in-memory), andstop()/await usingfor 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 — withdispatch()(enqueue-only, resolving at admission with the durableDispatchReceipt; a bare string is shorthand for a user message,{ message, initialData?, idempotencyKey? }the full payload),read()(await the settledAgentReply, re-attachable from any process at any later time), andabort(). 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: truetools get checkpointed steps. A tool declareddurable: truereceivesctx.step, andstep.do(name, fn)runsfnonce per name per tool call, durably recording the result before resolving. An interrupteddurable: truecall 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 betweenfncompleting 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: truereceives bothstepandharness, withharness.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
initialDatastatic, read the parsed value withuseInitialData(), and seed it from any sender —dispatch(agent, { id, message, initialData }), theinit()handle'sdispatch({ message, initialData }), a reservedinitialDatabody sibling on the direct HTTPPOST,send({ message, initialData })in@flue/sdk, andflue 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 auidminted at its birth (inst_…, carried on everyDispatchReceiptand SDK send result), and sends can be made conditional on it ETag-style with theuidoption: a string continues only that incarnation (a missing instance or mismatched uid rejects at admission withAgentInstanceNotFoundError/ 404, nothing durable),nullcreates only (an existing instance rejects withAgentInstanceExistsError/ 409 carrying the existing uid inmeta.uid), and omitted stays unconditional. The CLI speaks the same contract (flue run --uid <uid>/--new), andgetAgentInstance(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 newtoolcall_deltaevent 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'sread(). It awaits the submission's settlement and resolves with its reply ({ text, data, metadata?, submissionId, uid? }), throwingFlueExecutionErroron 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/sdkalso exportsreadSubmissionReply(conversation, submissionId), the pure projectionread()uses internally — extract a reply from ahistory()snapshot or anobserve()state with no extra fetch, including the coalesced reply when the send joined a busy response (replacing hand-pickedmessages.at(-1)reads that silently grab the wrong message on a busy conversation). The same projection backs the runtime'sinit().read(), so a reply read over HTTP and one read in-process agree.
Fixes & Other Changes
Updated
@earendil-works/pi-aiand@earendil-works/pi-agent-coreto 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:
ConversationStreamStoregains optionalputFoldCheckpoint/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/opentelemetrynow reserves the Stableexception.typeattribute for the exception class name (RateLimitError,TypeError, …), per the OpenTelemetry exception conventions — previously it duplicated Flue's error taxonomy, which stays onerror.typeonly. Applies to span exception events, span status, andgen_ai.client.operation.exceptionlog 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'serror.typeis the whole failure record.Both trace backends now stamp
gen_ai.agent.nameonexecute_toolspans (conditionally required by the GenAI semantic conventions when the owning agent is known), and the native Cloudflare adapter's chat spans gainserver.address/server.port,gen_ai.conversation.compacted, andopenai.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_outcomeand the batch is committed — recorded outcomes are preserved and nothing is re-executed or resumed — so atasktool 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 ataskcall 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 structuredattributes.interruptedTools(also onSubmissionRetryExhaustedError/SubmissionInterruptedErrormeta), 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 devand tovite previewon both targets, not just Nodevite dev, and are tightened to localhost: credentialed requests are allowed from localhost-family origins (Vite's own default origin set) instead of any reflectedOrigin, 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 explicitserver.cors/preview.corsoverride — 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 — undervite dev,vite build, orflue 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 typeis erased at build time). Invite devthe 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/vitehardening from a comparative review against SvelteKit's and TanStack Start's Vite plugins:resolve.dedupefor@flue/runtime/honoon every target, an explicit warning when user Vite config conflicts with valuesflue()enforces, a warning when multipleflue.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
submissionIdin conversationhistory()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
durationMson the resolveddynamic-toolpart in both history snapshots and live updates, instead of being available only on the ephemeral live event (#407).The Cloudflare extension's
baseandwrapcallbacks are now typed against the concrete generated Durable Object constructor (GeneratedDurableObjectClass<TBase, TEnv>, a constructor producingTBase & DurableObject<TEnv>), replacing the unreleased generic type-preservingwrapsignature. Every class Flue passes in really is a branded Durable Object, so brand-checked platform instrumentation such as@sentry/cloudflare'sinstrumentDurableObjectWithSentrynow accepts the class straight through — no generics, unsafe casts, or runtime constructability assertions, and no need for your own base type to extendDurableObject.extend()gains an optional secondTEnvtype parameter for typing the environment your instrumentation reads. The@flue/runtime/cloudflaretypes now referencecloudflare:workerstype-only (its runtime import graph is unchanged); projects without Cloudflare workers types configured degrade toanyunderskipLibCheck(#410).Documented the supported pattern for reaching a private Flue agent over a Cloudflare service binding: point the
@flue/sdkclient'sfetchoption at the binding, since thebaseUrlhost is never dialed and only the pathname and query drive routing (#408).Documented the
kind: 'user'vskind: 'signal'convention:useris a direct user talking to the assistant (a 1:1 chat surface);signalmodels 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 inattributes.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 theDeliveredMessagemigration lost, as flatattributes. 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 (
settlementsin history snapshots, thesubmission-settledchunk, and the SDK types in lockstep) exposeansweredBySubmissionId— 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 newread()) now recognize a settlement folded into aconversation-resetsnapshot — 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
interruptedToolsfield onSubmissionInterruptedErrormeta and the terminal-advisory renderer, and the unusedAttachedAgentEventCallback-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'ssubmissionIdnames the settled submission), identically inhistory()snapshots and live updates, with the@flue/sdkand@flue/reactmessage 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'ssettlementsstays the programmatic outcome index — now also exposed on@flue/react'suseFlueAgent()snapshot assettlements(withFlueConversationSettlementre-exported), purely additive to the existingstatus/errorsemantics. Internally, the canonicalsubmission_settledrecord now requires itssubmissionId— 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 416stream_offset_goneerror — validated before the response commits on the plain, long-poll, and SSE paths, with the requested offset and current head inerror.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 theupdatesview emits a minimalstream-checkpointchunk — 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'sread()). 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 manualrefresh(), 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()andread()— now carry the same stall, auth, and stream-reset resilience asobserve(). Previously they ran a bare loop over the conversationupdatesstream: 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 mismatchedstream-checkpointincarnation 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 soonEventnever observes a chunk twice.FlueExecutionErrorsemantics are unchanged — failed and aborted settlements reject exactly as before. This matters most forread(), 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
causelevel (andAggregateErrormembers) 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_settledevent 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_settledevent now carries the joined submission's ownsubmissionId; the host context's decoration previously overwrote it with the host's id, so an observer keying onsubmissionIdnever saw the joined delivery settle (the durable settlement record was always correct).The dev-mode lifecycle logger is now an
observe()subscriber oversubmission_running/submission_recovery(recovery failures now show up in dev output), retiring the bespokeonInteractionStartcallback that was threaded through both coordinators and both generated entries to deliver one log line.The
local()sandbox now resolves a command killed by itstimeoutMsdeadline with exit code124— thetimeout(1)convention the sandbox contract documents and the other first-party adapters follow — instead of1, 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
initialDataschema 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), andabort()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 asabortedimmediately (abort is the guaranteed escape hatch for every stuck class), and materialization failing pastacceptedAtplus the agent'sdurability.timeoutMsstatic (store default one hour) auto-fails it with the persistent error, emitting the livesubmission_settledplus asubmission_recoverywithoutcome: '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 withAgentInstanceNotFoundError, and the settled row remains the durable outcome authority.Coordinator recovery failures now reach both tracing adapters and the Sentry blueprint:
@flue/opentelemetryemitssubmission_recoveryas 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 newSandboxDiedErroronce 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).SandboxDiedErroris provider-neutral so ecosystem adapters can throw it for consistent shell classification, and theSandboxApicontract 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
taskcall 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 unknownactivate_skillname — instead of throwing a typed error into an error outcome; programmatic resolution keepsSubagentNotDeclaredError(#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-gatewaycatalog is hydrated into thecloudflareprovider'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/openaigateway 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/redisreadsHGETALLandCONFIG GETreplies 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.verifyso 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 whenverificationTokenis 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.
- 0.11.x
0.11.1
11 Jun 2026Reading the note…
0.11.0
10 Jun 2026Reading the note…
- 0.10.x
0.10.2
10 Jun 2026Reading the note…
0.10.1
8 Jun 2026Reading the note…
0.10.0
8 Jun 2026Reading the note…
- 0.9.x
0.9.2
3 Jun 2026Reading the note…
0.9.1
2 Jun 2026Reading the note…
0.9.0
2 Jun 2026Reading the note…
- 0.8.x
0.8.1
28 May 2026Reading the note…
0.8.0
27 May 2026Reading the note…
- 0.7.x
0.7.1
26 May 2026Reading the note…
0.7.0
15 May 2026Reading the note…
- 0.6.x
0.6.2
14 May 2026Reading the note…
- 0.5.x
0.5.3
12 May 2026Reading the note…
0.5.2
11 May 2026Reading the note…
0.5.1
11 May 2026Reading the note…
0.5.0
11 May 2026Reading the note…
- 0.4.x
0.4.1
10 May 2026Reading the note…
0.4.0
10 May 2026Reading the note…
- 0.3.x
0.3.11
7 May 2026Reading the note…
0.3.10
3 May 2026Reading the note…
0.3.9
3 May 2026Reading the note…
0.3.8
3 May 2026Reading the note…
0.3.7
3 May 2026Reading the note…
0.3.6
2 May 2026Reading the note…
0.3.5
30 Apr 2026Reading the note…
0.3.4
30 Apr 2026Reading the note…
0.3.3
30 Apr 2026Reading the note…
0.3.2
30 Apr 2026Reading the note…
0.3.1
30 Apr 2026Reading the note…
0.3.0
30 Apr 2026Reading the note…
- 0.2.x
0.2.0
24 Apr 2026Reading the note…
- 0.1.x
0.1.3
21 Apr 2026Reading the note…
0.1.2
21 Apr 2026Reading the note…
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.