@flue/cli
2.3.1 · 18 Nov 2026Apache-2.0217.3k / weekRepositoryHomepagenpmAtom feed
0.11.1 is the newest release of 0.5.x.
In short
6 breaking6 new5 fixed
- Breaking
FlueAgentis nowFlueHarness. The value returned frominit()is a harness: a configured handle for model defaults, tools, sandbox, filesystem, and sessions. Rename imports/usages fromFlueAgenttoFlueHarness, and preferconst harness = await init(...)in agent files. - Breaking
Harnesses and sessions are named, not id'd.
init({ id })is nowinit({ name }), defaulting to"default". The returned harness exposes.nameinstead of.id.harness.session(id?),harness.sessions.get/create/delete(id?), andFlueSession.idare now name-based APIs (name?,.name). - Breaking
Session storage keys now include the agent instance id, harness name, and session name. Existing persisted sessions under the old two-part key shape are not migrated. Cloudflare Durable Object session history from earlier builds will not be read by this release.
- Breaking
Webhook responses return
runIdinstead ofrequestId. Every HTTP invocation now gets a generatedrun_<ulid>exposed to handlers asctx.runId. Webhook mode returns{ status: 'accepted', runId }. - Breaking
The event vocabulary changed for run observability.
tool_endis nowtool_call,operation_endis nowoperation, and session correlation fields useharness,session, andparentSessioninstead of the previous id-oriented names. Consumers of the rawFlueEventstream should update event-type checks and field names. - Breaking
SSE
event: resultwas removed. Terminal result/error state is now delivered by the widerun_endevent. Sync responses still return{ result, _meta: { runId } }.
Release note
Breaking Changes
- Breaking
FlueAgentis nowFlueHarness. The value returned frominit()is a harness: a configured handle for model defaults, tools, sandbox, filesystem, and sessions. Rename imports/usages fromFlueAgenttoFlueHarness, and preferconst harness = await init(...)in agent files. - Breaking
Harnesses and sessions are named, not id'd.
init({ id })is nowinit({ name }), defaulting to"default". The returned harness exposes.nameinstead of.id.harness.session(id?),harness.sessions.get/create/delete(id?), andFlueSession.idare now name-based APIs (name?,.name). - Breaking
Session storage keys now include the agent instance id, harness name, and session name. Existing persisted sessions under the old two-part key shape are not migrated. Cloudflare Durable Object session history from earlier builds will not be read by this release.
- Breaking
Webhook responses return
runIdinstead ofrequestId. Every HTTP invocation now gets a generatedrun_<ulid>exposed to handlers asctx.runId. Webhook mode returns{ status: 'accepted', runId }. - Breaking
The event vocabulary changed for run observability.
tool_endis nowtool_call,operation_endis nowoperation, and session correlation fields useharness,session, andparentSessioninstead of the previous id-oriented names. Consumers of the rawFlueEventstream should update event-type checks and field names. - Breaking
SSE
event: resultwas removed. Terminal result/error state is now delivered by the widerun_endevent. Sync responses still return{ result, _meta: { runId } }.
New Features
Run history and durable event logs. Every invocation is recorded as a run with
run_start/run_endlifecycle events and a monotoniceventIndex. Cloudflare persists run history in the Agent Durable Object SQLite storage; Node keeps an in-memory ring buffer of recent completed runs.Run-scoped HTTP endpoints. New read-only endpoints expose a known run:
GET /agents/<name>/<id>/runs/<runId>,GET /agents/<name>/<id>/runs/<runId>/events, andGET /agents/<name>/<id>/runs/<runId>/stream. There is intentionally no list-runs endpoint yet; broader run discovery remains admin-API territory.Reconnectable live run streams.
/runs/<runId>/streamreplays durable history and then tails active runs. It honors standardLast-Event-IDresume semantics and closes whenrun_endis observed.flue logscommand.flue logs <agent> <id> <runId>replays or tails a known run from a running Flue dev server. It supports--follow/--no-follow,--since,--types,--limit, and--format pretty|json|ndjson.Structured handler logs. Handlers can call
ctx.log.info(...),ctx.log.warn(...), andctx.log.error(...)to emit structuredlogevents into the run event stream and persisted history.flue runsurfaces run ids. One-shot runs now print the generated run id to stderr and include_meta.runIdin sync responses, making it easier to inspect the same run withflue logs.
Fixes & Other Changes
Run lifecycle ordering is durable-before-live. Terminal
run_endevents are appended before live subscribers are notified and before the run is marked terminal, avoiding missed terminal events for clients connecting near completion.Live event fan-out is ordered per run. Durable writes are serialized before publishing each non-terminal event to live subscribers.
SSE streams now use a shared 15s heartbeat. Both direct agent SSE responses and run-history streams emit heartbeats to avoid idle proxy/client timeouts.
Cloudflare run-route parsing is positional. An agent instance id of
"runs"no longer collides with the/runsroute marker.Generated docs and examples were updated for the harness terminology and new run observability APIs.
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.