@flue/sdk
2.3.1 · 18 Nov 2026Apache-2.0309.1k / weekRepositoryHomepagenpmAtom feed
0.11.1 is the newest release of 0.9.x.
In short
7 breaking6 new9 fixed
- Breaking
Move application routing imports out of
@flue/runtime/app. Importflue,admin, andFetchablefrom@flue/runtime/routing. Import provider APIs andobservefrom@flue/runtime, and Workers AI binding types from@flue/runtime/cloudflare. Rename theProviderSettingstype toProviderConfiguration. - Breaking
Check your authored source directory. Flue now selects exactly one source directory in priority order:
.flue/,src/, then the project root. If your project already has asrc/directory, move root-level agents and workflows into the selected source directory so Flue continues to discover them. - Breaking
Cloudflare: Own Cloudflare Durable Object migrations in your project Wrangler config. Flue still generates classes and bindings, but no longer appends migrations automatically. Before upgrading an existing deployment, copy its complete ordered
flue-class-*migration history from the previously generated.flue-vite.wrangler.jsoncor builtwrangler.jsoninto the project-root Wrangler config. Keep deployed tags unchanged, and append a uniquely taggednew_sqlite_classesentry whenever you add an agent or workflow class. - Breaking
Workflows: Retry interrupted Cloudflare workflows explicitly. Flue no longer starts a replacement workflow run automatically after an interruption. The interrupted run is recorded as failed; invoke the workflow again when retrying is appropriate. Restart-link fields and their legacy OpenTelemetry attributes were removed.
- Breaking
Agents: Clear or migrate persisted beta session state before upgrading. Session and dispatch records from earlier beta releases are rejected rather than resumed with the new record shape. This does not apply to Flue workflows.
- Breaking
Providers: Use provider IDs consistently. Model values use
provider-id/model-id.registerProvider(providerId, ...)no longer accepts a separateprovideroverride,configureProvider(providerId, ...)uses the same ID, and binding-backedcloudflare/...models now report provider IDcloudflare. Prompt responses now exposemodel: { provider, id }. - Breaking
SDK: Configure SDK mount paths through
baseUrl. Its pathname is now used for public HTTP, SSE, and WebSocket routes. RemovewebsocketBasePath; keepadminBasePathonly for an independent admin mount.
Release note
Breaking Changes
- Breaking
Move application routing imports out of
@flue/runtime/app. Importflue,admin, andFetchablefrom@flue/runtime/routing. Import provider APIs andobservefrom@flue/runtime, and Workers AI binding types from@flue/runtime/cloudflare. Rename theProviderSettingstype toProviderConfiguration. - Breaking
Check your authored source directory. Flue now selects exactly one source directory in priority order:
.flue/,src/, then the project root. If your project already has asrc/directory, move root-level agents and workflows into the selected source directory so Flue continues to discover them. - Breaking
Cloudflare: Own Cloudflare Durable Object migrations in your project Wrangler config. Flue still generates classes and bindings, but no longer appends migrations automatically. Before upgrading an existing deployment, copy its complete ordered
flue-class-*migration history from the previously generated.flue-vite.wrangler.jsoncor builtwrangler.jsoninto the project-root Wrangler config. Keep deployed tags unchanged, and append a uniquely taggednew_sqlite_classesentry whenever you add an agent or workflow class. - Breaking
Workflows: Retry interrupted Cloudflare workflows explicitly. Flue no longer starts a replacement workflow run automatically after an interruption. The interrupted run is recorded as failed; invoke the workflow again when retrying is appropriate. Restart-link fields and their legacy OpenTelemetry attributes were removed.
- Breaking
Agents: Clear or migrate persisted beta session state before upgrading. Session and dispatch records from earlier beta releases are rejected rather than resumed with the new record shape. This does not apply to Flue workflows.
- Breaking
Providers: Use provider IDs consistently. Model values use
provider-id/model-id.registerProvider(providerId, ...)no longer accepts a separateprovideroverride,configureProvider(providerId, ...)uses the same ID, and binding-backedcloudflare/...models now report provider IDcloudflare. Prompt responses now exposemodel: { provider, id }. - Breaking
SDK: Configure SDK mount paths through
baseUrl. Its pathname is now used for public HTTP, SSE, and WebSocket routes. RemovewebsocketBasePath; keepadminBasePathonly for an independent admin mount.
New Features
Load local environment values before configuration. Flue application commands load project-root
.envvalues automatically. Use--env <path>to select one alternate file; shell values still take precedence.Restart
flue devafter configuration changes. Creating, editing, or deleting an auto-discoveredflue.config.*file restarts the development session with freshly resolved settings. Explicit--config <path>files are watched too.Forward authentication headers with
flue logs. Repeat--header 'Name: value'to send application-owned headers when inspecting workflow runs. Redirects are rejected so credentials stay on the selected server.Inspect admitted workflow runs from WebSocket clients.
WorkflowSocket.runIdresolves after admission, before the workflow result arrives.Catch SDK HTTP failures with
FlueApiError.@flue/sdknow exports the error type with the HTTP status and parsed response body when available.Forward Workers AI reasoning effort. Binding-backed
cloudflare/...models now pass reasoning effort toenv.AI.run(...)for models that support it.
Fixes & Other Changes
MCP connections now follow paginated tool listings so all server tools are available.
Workflow run streams now avoid duplicate events during replay-to-live handoff and validate reconnect event IDs more strictly.
Session lifecycle requests for the same name are serialized to avoid deletion races.
observe()subscribers now receive isolated event snapshots, and rejected async callbacks no longer interrupt runtime execution.Improved Cloudflare upgrade safety, local development diagnostics, and handling for unusual session names.
Fixed cwd scoping for created agents using Node
local()sandboxes.Pass at most one
--envfile.flue build,flue dev,flue run, andflue connectreject repeated--envflags. Combine values into one file or use shell environment overrides.session.delete()andharness.sessions.delete()now reject while the selected session has an active operation.Testing: Import
registerFauxProvider(...),fauxAssistantMessage(...),fauxText(...), andfauxToolCall(...)from@earendil-works/pi-aiinstead of@flue/runtime.
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.