@flue/sdk
2.3.1 · 18 Nov 2026Apache-2.0309.1k / weekRepositoryHomepagenpmAtom feed
Upgrading @flue/sdk From 0.11.1 to 2.0.0
1 release in betweenevery note read
- 33
- changes to make
- 0
- advisories fixed
- 18
- new
- 43
- fixes
Start here
Before you upgrade
Tick each one off as you go- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
- Breaking2.0.0
Release by release
- 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
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.