npm / @flue/cli
@flue/cli
What changed in @flue/cli 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-15.
85 breaking1 security59 new APIs and options1 performance6 behavior and defaults5 tooling18 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@flue/cli 2175 changes
Breaking changes 85
Tool arguments are now recorded on the standard OTel attribute for every payload shape, so OTel backends can display them.
Tool results are now recorded on the standard OTel attribute for every payload shape, so OTel backends can display them.
AgentDispatchOptions is renamed AgentReadOptions and belongs to read().
AgentPromptImage is renamed to DeliveredAttachment in @flue/sdk and @flue/react.
The SDK message option is now a DeliveredMessage rather than a string; images fold into attachments.
Adapter submission input types collapse into one interface for dispatch and direct submissions.
Custom stores must implement atomic, queued-gated terminal settlement for submissions that can never be claimed; no attempt is created.
Routes must now be mounted explicitly in app.ts; a missing app.ts is a build error.
Assistant steps within one submission now fold into one conversation message, accumulating parts in record order and summing usage.
The callback type is removed, and admission no longer accepts an onEvent callback parameter.
The agent module's named attachments export is removed; the attachment byte route is part of every agent router.
The MCP connection API is replaced by connection definitions and createMcpConnection.
Channel helper APIs rename conversationKey to instanceId without aliases.
Cloudflare Durable Object SQLite batches above 1 MB now spill into 512 KB chunk rows; batches above 12 MB fail with an actionable error.
Mount an agent explicitly in app.ts with createAgentRouter from @flue/runtime/routing.
The built-in bash tool is now a composable per-tool factory that accepts an environment.
Conversation content is captured into Workers Traces by default. Set content to false for content-free spans or provide a transform to redact or drop content.
The default Flue app factory is removed.
The SDK client now addresses one conversation by its full mount URL rather than baseUrl and agent-name/id.
Create an imperative MCP connection for module-scope use on the Node target.
The Actions surface is removed; model-invoked jobs are tools declared with useTool.
The initializer-based agent API is removed; a capitalized exported function in a use agent module is the agent.
The agent profile helper and AgentProfile type are removed.
The configuration helper moves to @flue/runtime/config; the @flue/cli/config export is removed.
instructions is now required; defineSkill validates and freezes definitions rather than packaging them, which happens lazily.
The single signature is dispatch(agent, { id, message }); the named-string form is removed and rejects non-definition arguments.
Dispatch requests now carry a validated DeliveredMessage instead of opaque input; user messages can include image attachments.
Configure maxAttempts and timeoutMs as a static on the agent function rather than in the removed config object.
Now contains the exception class name, while Flue's error taxonomy remains on
error.type.The Flue build command is removed; use Vite commands instead.
The Flue development command is removed; use Vite commands instead.
The terminal chat console package is removed.
Adapter authors use FLUE_FORMAT_VERSION and assertSupportedFlueFormatVersion instead of the schema-version contract.
The command now compiles and runs one agent module locally under Node without an HTTP listener or Cloudflare emulation; it streams events to stderr and prints the reply and conversation id.
Supply the prompt using --message; it replaces --input.
Flue is now adopted as a Vite plugin; use vite dev and vite build, with the Cloudflare plugin as an explicit sibling when targeting Cloudflare.
The output field is no longer accepted in the host-independent project configuration.
The root field is no longer accepted in the host-independent project configuration.
The telemetry attribute is removed; flue.submission.id is its replacement.
The dispatchId correlation field is removed; submissionId identifies activity for dispatched and direct submissions.
Remote aborts are distinguishable from failures using the value 'aborted'.
Persisted stores are stamped with format version 1 and refuse unsupported formats; beta-era stores must be cleared because there is no migration.
The fabricated GenAI semantic-conventions schema URL export is removed.
The public content policy type is removed in favor of the content transform surface.
Dispatch now resolves at admission with a durable DispatchReceipt and no longer accepts options; use handle.read to await the reply.
Read a settled reply by receipt or submissionId, including after process restarts; it rejects with AgentRunError on failure or abort.
The harness interface flattens to name, prompt(), compact(), and sandbox; session, sessions, shell, and fs are removed.
Channel packages use instanceId for the agent instance identifier previously named conversationKey.
Commands killed by their timeout now resolve with exit code 124, matching the
timeout(1)convention.Channel helper APIs rename parseConversationKey to parseInstanceId without aliases.
parseInstanceId replaces parseConversationKey and is now an escape hatch; agents should receive structured facts as creation data.
The direct agent HTTP body now accepts the validated DeliveredMessage shape instead of { message, images? }.
The adapter helper is renamed from prepareDirectSubmission.
Local CORS defaults now cover
vite previewon both targets and are restricted to localhost-family origins; user overrides still win.The SDK prompt method is removed; use send, wait, and history.
The function now returns AgentSubmission or undefined rather than a ReconciliationResult union.
The API provider registration helper is removed.
The option-bag provider registration API is removed; custom providers are pi-ai Provider objects registered with setProvider.
The agent module's named route middleware export is removed; protect mounts with ordinary middleware layered in app.ts.
Agents no longer receive an implicit in-memory sandbox; execution environments and shell/filesystem tools are available only when an agent declares useSandbox.
The contract now requires in-flight operations to settle when the sandbox dies, by a mechanism supported by the provider SDK.
Hand-rolled implementations that late-reject without the runtime wrappers are out of contract; adapters must not add their own abort race.
When options.signal aborts mid-command, the promise now rejects immediately with AbortError. A still-running remote command is treated as an orphan and its eventual settlement is consumed, not recorded.
The directory convention no longer creates routes or registrations; agents are registered by scanning for the use agent directive.
The directory convention no longer creates routes or registrations.
Resuming beyond the available stream head now returns a structured 416 error with the requested offset and current head.
Replaying a streaming record after its message has resolved now fails loudly instead of silently deduplicating it.
Canonical records now require
submissionId, and joined deliveries' live events carry their own submission ID.Reusing an idempotency key with a different payload rejects with a structured 409 containing the existing submission id.
Signal tagName is validated as an XML tag name at admission; malformed values throw InvalidRequestError.
A model-invoked task naming an undeclared agent now returns a plain tool result describing the miss and roster; programmatic resolution still throws
SubagentNotDeclaredError.Terminalizing a durable submission now records an interrupted-error outcome for every tool call without a confirmed outcome and commits the batch.
Tool run functions return an { output?, terminate? } envelope; bare strings remain shorthand, undefined is allowed in specified cases, and other bare values are rejected.
Schema-parsed tool arguments are now exposed as data rather than input.
MCP definitions can allowlist server tool names; a name the server does not expose is a hard error.
An agent module is identified by this first-statement directive; the build scans for it and registers each capitalized exported function as an agent.
The React hook now accepts the conversation URL instead of name and id.
Declare the required model during each agent render, exactly once; thinkingLevel and compaction are options.
Attach an execution environment explicitly; sandbox declarations can change at turn boundaries.
Declare subagents as values during an agent render; task calls can only name a declared subagent.
SDK wait now resolves void on completion and throws FlueExecutionError on failure or abort; aborted settlements use failure 'aborted'.
Synchronous result mode on agent HTTP POSTs is removed; prompts always return a 202 admission.
Markdown import attributes are removed; the resolved specifier determines the import behavior.
Skill import attributes are removed; the resolved specifier determines whether an import is a skill.
Workflow definitions, invocation, run stores and event streams, workflow routes, SDK namespaces, React hooks, and run UI are deleted without compatibility stubs.
Security 1
Webhook verification and request handling are hardened across channel packages, including timestamp freshness checks, repeated-value signing, guarded key refresh, and safer body-stream cancellation.
New APIs and options 59
Pin an agent's durable storage identity independently of its exported function name.
Settlements expose which submission answered a delivery that joined a running response.
Conversation settlements expose the submission whose response answered the settled submission, derived from shared attempt linkage.
Terminal advisories now provide the interrupted-call list as structured attributes so apps can settle run state without parsing text.
MCP definitions can supply a static bearer token or a resolver called freshly on each request.
Use cloudflareSandbox(stub) to run commands in a Cloudflare Sandbox container.
Adds optional checkpoint methods for incremental conversation folds; custom adapters without them remain functional but fall back to full replay with one warning per path.
An optional callback observes settlement of orphaned commands; its settlement value uses the exported OrphanedExecSettlement type.
Tools declared durable: true receive checkpointed steps whose completed results replay during recovery; step values must be small and JSON-serializable.
Validate and freeze an exportable MCP connection definition.
A unified message shape represents either user chat turns or structured signal events.
A caller-chosen key makes repeated admissions to the same agent instance converge on one submission and receipt; replays are marked deduplicated.
Public conversation messages expose display classification values for visible, hidden, or diagnostic messages.
Logged internal 500-class errors include a correlation ref in the response envelope, enabling callers to identify the matching server log entry.
Gains an optional second type parameter for typing the environment read by instrumentation.
Logged internal errors include a correlation-ref response header, including on body-less HEAD responses.
The CLI can seed instance creation data with --data and condition sends on an incarnation with --uid or --new.
A dependency-free, Node-evaluable subpath exposes shared GenAI content projection, transforms, truncation, content attributes, and semantic-convention revision constants.
The SDK error exposes the correlation ref from the envelope or header and includes it in the composed error message.
History snapshots now carry the stream's durable generation identity so observers can detect reset and regrowth.
Explicitly request durable abort of the running head and every queued submission.
Creates a durable handle for an agent instance with dispatch(), read(), and abort(); creating the handle itself performs no I/O.
Declare a Valibot schema for agent creation data as a function static.
Agent instances can declare typed creation data, read with useInitialData(), and receive it from senders; admission validates it synchronously and ignores it for existing instances.
Use local() from @flue/runtime/node as a sandbox factory that runs commands on the host.
Set optional: true to let a failed MCP server resolve to zero tools for that submission instead of failing it.
The direct agent endpoint accepts idempotencyKey as a reserved request-body sibling beside initialData and uid.
The exhaustive provider list selects which built-in providers, catalogs, and protocol implementations are bundled and resolvable; it can also be supplied inline on the Vite plugin.
Public conversation messages expose typed purpose values so clients can distinguish chat from internal, control, and advisory activity.
The SDK can await a submission's settled reply by admission or submission id, reattach after settlement, and throw FlueExecutionError for failed or aborted outcomes.
A pure SDK projection extracts the reply from history or observe state, including a reply coalesced from a busy conversation.
SDK sends accept an optional idempotencyKey so retries converge instead of duplicating submissions.
Register custom or customized pi-ai Provider objects with setProvider.
useFlueAgent()snapshots now expose the settlements index, andFlueConversationSettlementis re-exported.The Node runtime can be assembled without an HTTP server so scripts, cron jobs, and tests can drive agents; stop() and await using drain and dispose it.
Programmatic runs can select providers using Provider objects.
Runs a named tool step with durable result recording before resolution; completed steps replay on recovery, while execution may repeat if a crash occurs before recording.
The updates view emits a checkpoint chunk so observers can detect stream incarnation changes and rehydrate.
observe() emits a live event immediately after durable admission; idempotent replays may emit it again.
observe() surfaces contained coordinator recovery failures as live events with operation and outcome discriminators.
observe() emits a live event from each attempt's context, including attemptCount and maxAttempts.
A tool can return terminate: true to end the agent turn after the current tool batch settles; the flag is durable across recovery.
In-process observe() streams tool-call argument text deltas for live previews; these events are not persisted or replayed.
Public conversation messages can include optional turn grouping and a signal descriptor, consistently across history snapshots and live updates.
Each instance receives a birth-time uid. Sends can require a matching incarnation, create only with null, or remain unconditional when omitted.
Register agent finish work; ctx.append can send the model back to work in the same response.
Register agent lifecycle work through a render hook.
Declare named client-facing data parts with a schema.
Read the delivered message in front of the model.
Obtain an instance-bound dispatcher from the agent render.
The hook exposes refresh() so applications can re-check conversations created out of band without faking an empty history snapshot.
Read the data supplied when an agent instance is created.
Declare instruction text through a hook during the agent render.
Declare an MCP server connection from the agent render; its tools mount under the mcp__server__tool naming scheme.
Add durable per-instance state with React-style functional updates.
Register a response-finish callback for response metadata.
Register a response-start callback during the agent render.
Declare a skill through a hook; it accepts a SkillReference or SkillDefinition directly.
Declare tools through a hook during the agent render.
Performance 1
Agent rescans and Cloudflare input regeneration now coalesce bursts into at most one in-flight pass and one queued pass.
Behavior and default changes 6
A delivery arriving mid-response can join the live response at the next turn boundary; a delivery that misses it runs afterward as its own submission.
Initialization is interactive and scaffolds the project skeleton; --target and --deploy answer prompts for scripted runs, while existing non-config files are not overwritten.
The native Cloudflare adapter's chat spans now include this attribute.
Adds a 90-second transport-silence watchdog, retries auth failures with fresh credentials up to three consecutive failures, and rehydrates on stream incarnation changes.
Terminal advisory messages for failed or aborted turns now carry a structured settlement outcome marker in snapshots and live updates.
On the Node target, the dev server loads the project's .env file set into the application environment, with shell-exported values taking precedence.
Tooling 5
Flue packages and newly scaffolded applications use compatible Hono dependencies, avoiding a newer root Hono alongside the runtime's older exact version and the resulting typecheck failure.
Its types now reference
cloudflare:workersas type-only, leaving the runtime import graph unchanged.The dev-only 503 runtime-unavailable envelope includes the underlying application load failure, and load-failure stacks are remapped to authored sources.
The Vite plugin now dedupes
@flue/runtimeandhono, warns about conflicting enforced config and multiple config files, and improves diagnostics and transform filtering.Node-target preview serves the built app.mjs natively and requires a prior build; vite build emits both server.mjs and app.mjs.
Fixes and other changes 18
Flue accepts the Agent Skills spec field as guidance but does not enforce it; authorization must be enforced in your own tools and approval gates.
Installed packages once again include the bundled Flue documentation, so this command works out of the box.
Channel examples now preserve sender identity and event metadata as flat attributes during dispatch; Telegram media-only updates receive a placeholder body.
Wrong-environment import diagnostics now print the import chain, and identify
import typeas an escape hatch.Workers AI binding models now include the hydrated AI Gateway catalog with metadata; OpenAI-prefixed gateway models use the Responses wire format, and uncatalogued gateway IDs still stream.
Resolved
dynamic-toolparts now expose durably recorded tool-call duration in history snapshots and live updates.Now reads
HGETALLandCONFIG GETreplies in both RESP2 and RESP3 shapes.The documented pattern for reaching a private Flue agent over a Cloudflare service binding is to point the client's
fetchoption at the binding.Both trace backends now stamp this attribute on
execute_toolspans when the owning agent is known.Completed assistant messages now preserve their
submissionIdin conversation history snapshots.The documented convention distinguishes direct user-to-assistant chats (
user) from broader channels and multi-user conversations (signal).MCP tool connections no longer crash on Cloudflare Workers when a connected server advertises an output schema.
Now recovers from stalled streams, transient auth failures, stream resets, and stale offsets while following a settlement.
A provider-neutral error is thrown when the Cloudflare sandbox container dies during an RPC, allowing the operation to settle.
The native Cloudflare adapter's chat spans now include this attribute.
Local CORS defaults now cover Cloudflare-target
vite dev; credentialed requests are allowed from localhost-family origins, and user overrides still win.Now recognizes a settlement folded into a
conversation-resetsnapshot instead of waiting for another stream event.Settlement followers now recover from stalls, transient auth failures, stream resets, and stale offsets rather than hanging or failing immediately.