@flue/sdk
2.3.1 · 18 Nov 2026Apache-2.0309.1k / weekRepositoryHomepagenpmAtom feed
0.11.1 is the newest release of 0.4.x.
In short
12 breaking21 new2 changed
- Breaking
There are some breaking changes to be aware of, when upgrading from
v0.3tov0.4. - Breaking
commandsanddefineCommandare removed. The original idea — register first-party CLI tools the agent could shell out to — only worked under just-bash and saw little real use. The same surface is better expressed today by passingenvto scope what a connector sees, or by choosing a sandbox connector that gives you the isolation you want. just-bash itself still supports custom commands — you just register them on your bash instance directly instead of through Flue's helper. Removed: thecommands?:option oninit()/prompt()/skill()/task()/shell(); theCommand,CommandDef,CommandOptions,CommandExecutor,CommandExecutorResulttypes; thedefineCommandexport from@flue/sdk/nodeand@flue/sdk/cloudflare; thecommand_start/command_endFlueEventvariants; and theBashLike.registerCommand/SessionEnv.scopeconnector hooks. - Breaking
Default
thinkingLevelchanged from'off'to'medium'. Reasoning-capable models (e.g. gpt-5, claude-opus-4-7) will now reason by default on everyprompt()/skill()/task()call. Non-reasoning models are unaffected (clamped to'off'per the model'sthinkingLevelMap). To restore the old behavior, setthinkingLevel: 'off'explicitly oninit(), your role frontmatter, or the call options. - Breaking
sandbox: 'local'now runs locally. Originally,'local'was a half-isolated layer — ajust-bashsubprocess with aReadWriteFs/MountableFsoverlay mountingprocess.cwd()at/workspace. That made sense when every Flue agent ran on a developer laptop, but increasingly people are deploying the agent itself inside a real sandbox (a container, a microVM, a Cloudflare Sandbox), where wrapping the host in a second virtual filesystem is pure overhead — and actively confusing, because paths get remapped twice.sandbox: 'local'now binds directly to the host:execruns through the user's shell with fullprocess.env, file methods hit the real filesystem, defaultcwdisprocess.cwd(), and there are no path remappings or command restrictions. Agents that hard-coded/workspacepaths must migrate to real host paths. If you want isolation on a developer laptop, reach for a real sandbox connector (Daytona, E2B, Mirage, etc.). - Breaking
init({ providers: { … } })has moved. Provider configuration moved to the newapp.tsruntime registration model (see below). Migrate by creating anapp.tsat your project root and callingconfigureProvider()(to patch a built-in catalog provider'sbaseUrl/apiKey/headers/storeResponses) orregisterProvider()(to register a brand-new URL-prefix provider). Both are exported from@flue/sdk/app. TheProvidersConfigtype andprovidersfield are removed fromAgentInitandAgentConfig. - Breaking
FlueAgent.destroy()andSessionEnv.cleanup()are removed. Flue no longer manages sandbox lifetime — sandboxes are user-owned. Connectors that previously took acleanupoption (Boxd, Daytona, E2B, Exedev, islo, Modal, Vercel) no longer accept it; some lose their options argument entirely (e.g.daytona(sandbox)instead ofdaytona(sandbox, { cleanup })). If you were relying on automatic teardown, destroy your sandbox explicitly when your handler is done. - Breaking
CLI
--workspaceflag renamed to--rootacrossflue dev/flue run/flue build. The corresponding programmatic options also moved:BuildOptions.workspaceDir→BuildOptions.root,BuildContext.workspaceDir→BuildContext.root. Theflue.config.tskey isroot, notworkspace. - Breaking
outputDirrenamed tooutputacrossBuildOptions,BuildContext, andDevOptions. Build plugin authors readingctx.outputDirmust update toctx.output. The CLI flag remains--output. The default is<root>/dist, and--outputis now the literal output directory (previously it was a parent directory into whichdist/was written).BuildOptions.outputis now optional.
Release note
Big release! We are working hard to stabilize our APIs and add any missing and essential features to Flue that you need. There are some breaking changes to be aware of, when upgrading from v0.3 to v0.4. Read through the list below to understand what's new and what's changed. Or, point your coding agent to this changelog URL for a more automated upgrade experience).
Breaking Changes
- Breaking
New return type for
prompt()/skill()/task()/shell(). Two changes folded into one new shape:They now return a
CallHandle<T>instead of aPromise<T>.awaitworks exactly as before. The handle is aPromiseLikewith.signal: AbortSignaland.abort(reason?)for synchronous cancellation, replacing the removedPromptOptions.timeout/SkillOptions.timeout/ShellOptions.timeoutfields. Code that uses these as plain Promises withoutawait(e.g. raw.then()/.catch()chains) may need adjustment.
// Cancel via an AbortSignal on the options bag const result = await session.prompt('…', { signal: AbortSignal.timeout(5000) }); // Or abort the handle directly const handle = session.prompt('…'); setTimeout(() => handle.abort('user cancelled'), 5000);The awaited value is now
{ text | data, usage, model }instead of a bare string or schema value. Schema-typed calls returnPromptResultResponse<T>; non-schema calls returnPromptResponsewith the newusageandmodelfields. To migrate, readresponse.textorresponse.data:
// Before const text = await session.prompt('…'); const user = await session.prompt('…', { result: UserSchema }); // After const { text } = await session.prompt('…'); const { data: user } = await session.prompt('…', { result: UserSchema });Structured results use the
resultoption and return validated data onresponse.data.Schema results are now extracted via injected
finish/give_upmodel-facing tools instead of---RESULT_START---/---RESULT_END---text markers. The unusedResultExtractionErrorclass is removed; a newResultUnavailableErroris thrown when the model invokesgive_up. - Breaking
commandsanddefineCommandare removed. The original idea — register first-party CLI tools the agent could shell out to — only worked under just-bash and saw little real use. The same surface is better expressed today by passingenvto scope what a connector sees, or by choosing a sandbox connector that gives you the isolation you want. just-bash itself still supports custom commands — you just register them on your bash instance directly instead of through Flue's helper. Removed: thecommands?:option oninit()/prompt()/skill()/task()/shell(); theCommand,CommandDef,CommandOptions,CommandExecutor,CommandExecutorResulttypes; thedefineCommandexport from@flue/sdk/nodeand@flue/sdk/cloudflare; thecommand_start/command_endFlueEventvariants; and theBashLike.registerCommand/SessionEnv.scopeconnector hooks. - Breaking
Default
thinkingLevelchanged from'off'to'medium'. Reasoning-capable models (e.g. gpt-5, claude-opus-4-7) will now reason by default on everyprompt()/skill()/task()call. Non-reasoning models are unaffected (clamped to'off'per the model'sthinkingLevelMap). To restore the old behavior, setthinkingLevel: 'off'explicitly oninit(), your role frontmatter, or the call options. - Breaking
sandbox: 'local'now runs locally. Originally,'local'was a half-isolated layer — ajust-bashsubprocess with aReadWriteFs/MountableFsoverlay mountingprocess.cwd()at/workspace. That made sense when every Flue agent ran on a developer laptop, but increasingly people are deploying the agent itself inside a real sandbox (a container, a microVM, a Cloudflare Sandbox), where wrapping the host in a second virtual filesystem is pure overhead — and actively confusing, because paths get remapped twice.sandbox: 'local'now binds directly to the host:execruns through the user's shell with fullprocess.env, file methods hit the real filesystem, defaultcwdisprocess.cwd(), and there are no path remappings or command restrictions. Agents that hard-coded/workspacepaths must migrate to real host paths. If you want isolation on a developer laptop, reach for a real sandbox connector (Daytona, E2B, Mirage, etc.). - Breaking
commands/defineCommandremoved. ThecommandsAPI let you register user CLIs (gh,npm, etc.) into a sandbox-scoped$PATH, isolating secrets from the model. In practice it only ever worked when the sandbox was aBashFactory(the default in-memory sandbox orgetVirtualSandboxon Cloudflare), and threw a runtime error on'local', every remote connector (Daytona, E2B, Mirage, etc.), and Cloudflare Containers — so the documented "CI agent withdefineCommand('gh', { env: { GH_TOKEN } })" pattern has been broken for most users since'local'was rebuilt. We're collapsing the API:With the new
'local'sandbox, the host shell is exposed directly. The agent'sbashtool can rungh issue view,npm test, etc. with whatever's on$PATHand whatever env you launched flue with. The runner / container / VM is the isolation boundary.For non-
'local'sandboxes, install the binaries inside the sandbox image, or wrap the operation as a custom tool withinit({ tools: [...] }). Tools have a structured parameter schema, are visible to the model directly, and recover the "secrets stay on the host" property — the tool readsprocess.env, the agent only sees the tool's params and result.
Removed:
Command,CommandDef,CommandOptions,CommandExecutor,CommandExecutorResulttypes;defineCommandfrom@flue/sdk/nodeand@flue/sdk/cloudflare;commands?:field oninit(),prompt(),skill(),task(),shell();BashLike.registerCommand?,SessionEnv.scope?; the deadcommand_start/command_endFlueEventvariants. - Breaking
init({ providers: { … } })has moved. Provider configuration moved to the newapp.tsruntime registration model (see below). Migrate by creating anapp.tsat your project root and callingconfigureProvider()(to patch a built-in catalog provider'sbaseUrl/apiKey/headers/storeResponses) orregisterProvider()(to register a brand-new URL-prefix provider). Both are exported from@flue/sdk/app. TheProvidersConfigtype andprovidersfield are removed fromAgentInitandAgentConfig. - Breaking
FlueAgent.destroy()andSessionEnv.cleanup()are removed. Flue no longer manages sandbox lifetime — sandboxes are user-owned. Connectors that previously took acleanupoption (Boxd, Daytona, E2B, Exedev, islo, Modal, Vercel) no longer accept it; some lose their options argument entirely (e.g.daytona(sandbox)instead ofdaytona(sandbox, { cleanup })). If you were relying on automatic teardown, destroy your sandbox explicitly when your handler is done. - Breaking
CLI
--workspaceflag renamed to--rootacrossflue dev/flue run/flue build. The corresponding programmatic options also moved:BuildOptions.workspaceDir→BuildOptions.root,BuildContext.workspaceDir→BuildContext.root. Theflue.config.tskey isroot, notworkspace. - Breaking
outputDirrenamed tooutputacrossBuildOptions,BuildContext, andDevOptions. Build plugin authors readingctx.outputDirmust update toctx.output. The CLI flag remains--output. The default is<root>/dist, and--outputis now the literal output directory (previously it was a parent directory into whichdist/was written).BuildOptions.outputis now optional. - Breaking
Built-in
/healthand/agentsHTTP endpoints removed. Projects that need them must author the routes inapp.ts.flue devandflue runno longer probe/health;flue runretries SSE POST onECONNREFUSEDfor ~5s instead. - Breaking
Skill.instructionsfield removed from the public type. Skill bodies are no longer cached in memory — at call time the model readsSKILL.mdfrom disk via its filesystem tools. This means relative references inside a skill resolve correctly, and edits are picked up mid-session without re-init. If you were readingskill.instructionsfrom the SDK types, read the file from disk yourself. - Breaking
Sandbox connector contract:
SandboxApi.execis now timeout-primary, signal-optional. Connectors are expected to forwardtimeoutto their provider's native timeout option (E2BtimeoutMs, Daytonatimeout, etc.); signal-aware SDKs may additionally forwardsignalfor true mid-flight cancellation.BashLike.execoptions gainedsignal?: AbortSignal. If you maintain a sandbox connector, see Sandbox Connector API for the dual contract. - Breaking
Long-running agents on Node no longer time out at ~300s. The generated Node server now sets
requestTimeout: 0on the underlyinghttp.Serverand emits a 25s SSE heartbeat, which keeps undici'sbodyTimeoutand reverse-proxy idle timers satisfied. Multi-minutebashcalls and other long handlers that emit no Flue-level events for >300s no longer abort with[flue] Agent error: terminated.
New Features
flue.config.tsproject config. Aflue.config.{ts,mts,mjs,js,cjs,cts}file at the project root is auto-discovered and can settarget('node' | 'cloudflare'),root, andoutput. CLI flags still win per-field. Authored in TypeScript via Node's native type-stripping (no bundling). New--config <path>flag onflue dev/flue run/flue build. New@flue/sdk/configsubpath export withdefineConfig,resolveConfig,resolveConfigPath,UserFlueConfig,FlueConfig,ResolveConfigOptions,ResolvedConfigResult.// flue.config.ts import { defineConfig } from '@flue/sdk/config'; export default defineConfig({ target: 'cloudflare', });flue initcommand scaffolds a starterflue.config.tsin the target directory. Flags:--target <node|cloudflare>(required),--root <path>,--force(overwrite existing).app.tsruntime entry point. A new optionalapp.ts(also.mts/.js/.mjs) at the source root lets you take over the request pipeline with custom Hono middleware, routes, auth, etc. Mount Flue's agent handler viaapp.route('/', flue()). New@flue/sdk/appsubpath export ships:flue()— Hono sub-app exposing/agents/:name/:id.Fetchable— type for the user app's default export.registerProvider(name, def)— register a new URL-prefix model provider at runtime, with platformenvin scope. Supports HTTP and Cloudflare AI binding registrations (HttpProviderRegistration,CloudflareAIBindingRegistration,CloudflareAIBinding).registerApiProvider— re-exported from pi-ai for entirely new wire protocols.configureProvider(slug, settings)— patchbaseUrl/apiKey/headers/storeResponseson an existing pi-ai catalog provider or previously registered prefix.
.flue/-as-source layout. When<root>/.flue/exists, source files (agents/,roles/, optionalapp.ts) are read from there; otherwise from<root>/directly..flue/wins unconditionally if present.AbortSignal cancellation across
prompt()/skill()/task()/shell(). Passsignal: AbortSignal(e.g.AbortSignal.timeout(5000)) on the options bag, or use the newCallHandle.abort(reason?)method on the returned handle. Aborts reject with a standardDOMExceptionnamedAbortErrorwhosecauseis the signal's reason. Aborting aprompt()also tears down in-flightbashtool commands, not just the model loop.SessionEnv.exec()also acceptssignal?alongsidetimeout?.Per-call reasoning effort. New
thinkingLevel?: ThinkingLevelonAgentInit,Role(also via role frontmatterthinkingLevel:),PromptOptions,SkillOptions,TaskOptions, andAgentConfig. Precedence: per-call > role > agent. Tasks inherit the parent's resolved level. Per-call'off'is rejected (init/role/agent-level only). Unknown values in role frontmatter throw at build time.ThinkingLevelre-exported from@flue/sdkand@flue/sdk/client. A single deployment can now serve a cheap classifier at'low'and a careful auditor at'high'from the same model entry.Images on
prompt()/skill()/task(). Newimages?: PromptImageoption on all three (and the initial turn oftask()).PromptImageis the shape{ type: 'image', data: base64, mimeType }, re-exported from pi-ai. Requires a vision-capable model. For schema-result calls, images are attached on the first attempt only; retries are text-only.Token + cost usage on every response.
PromptResponse(and the newPromptResultResponse<T>) now includeusage: PromptUsageandmodel: PromptModel.PromptUsageaggregates across every LLM call dispatched by a single invocation — assistant turns, schema-result retries, the 1–2 compaction summarization calls, and the post-compaction overflow retry. Fields:input,output,cacheRead,cacheWrite,totalTokens, plus acostbreakdown (input,output,cacheRead,cacheWrite,total).PromptModel.idreflects the model Flue selected via call > role > agent precedence.Thinking events on the SSE stream. Three new
FlueEventvariants:thinking_start,thinking_delta(withdelta: string), andthinking_end(withcontent: string).flue runrenders them as dimmed lines under athinking:startmarker.fssurface onFlueAgentandFlueSession. Out-of-band sandbox filesystem access that doesn't appear in the conversation transcript — useful for staging inputs and reading back outputs around aprompt()call. Methods:readFile,readFileBuffer,writeFile(string orUint8Array),stat,readdir,exists,mkdir({ recursive? }),rm({ recursive?, force? }). Paths resolve relative to the agent'scwd.ctx.req: Request | undefinedonFlueContext. Standard FetchRequestfor the current invocation — read headers (req.headers.get('authorization')), method, URL, and the raw body viareq.text()/req.json()/req.arrayBuffer()/req.formData(). Body is preserved for handlers (Flue's internal JSON parser consumes a clone), so HMAC signature verification over raw bytes works directly withoutreq.clone(). Undefined when an agent is invoked outside an HTTP context.Cloudflare Workers AI binding provider. Models prefixed
cloudflare/<model-id>route throughenv.AI.run()on the Cloudflare target with no API tokens — the only setup is"ai": { "binding": "AI" }inwrangler.jsonc. Works across role models, sub-tasks, and compaction. Hard error on--target nodepointing users at pi-ai's URL-based providers.ProviderConfiguration.storeResponses?: booleanopt-in. When enabled, setsstore: trueon outgoing requests foropenai-responsesandazure-openai-responses, enabling multi-turn against reasoning models whenthinkingLevel: 'off'is explicitly set. (Codex Responses intentionally excluded — it rejectsstore: true.)session.shell()is now a first-class transcript citizen. It emits the sametool_start/tool_endevents as an LLM-issuedbashcall (sharedtoolCallId,toolName: 'bash') and appends a user / assistant tool-use / toolResult triple to history. Per-callcwdandenvoverrides are preserved in the synthetic tool-callargumentsso they remain visible to the model on subsequent turns. Aborted commands now produce atoolResultwithisError: trueand the error message as text (previously dropped silently).Skills are now read from disk on demand.
session.skill()references the skill by name and the system prompt's "Available Skills" registry tells the model where to find it (.agents/skills/<name>/SKILL.md). Relative references inside a skill (sibling markdown files, scripts) now resolve from where they live, and edits toSKILL.mdare picked up mid-session without re-init. Path-based references produce a distinct prompt naming the file path explicitly.createLocalSessionEnv()helper exported from@flue/sdk/node. A pure-NodeSessionEnvbacked directly bynode:fs/promisesandnode:child_process. ConfigurablecwdviaLocalSessionEnvOptions.exechonorstimeout+signaland lifts the default output buffer cap to 64 MB. This is what powers the newsandbox: 'local'behavior.
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.