Flue

Flue is an open-source TypeScript agent framework from the Astro team, published as @flue/runtime. An agent has no filesystem or shell until it calls useSandbox(); with a sandbox attached the model sees six dedicated tools, read, write, edit, bash, grep, and glob, all built in one file, packages/runtime/src/agent.ts, over a Sandbox interface that the adapter implements. The agent loop is Pi's @earendil-works/pi-agent-core, and each of the six descriptions is one sentence group of at most 136 characters. This page describes the local() Node adapter from @flue/runtime/node with process.cwd() as the working directory and the default environment allowlist, and names the just-bash virtual sandbox and the cloudflareSandbox container adapter where their behaviour differs.

Source

Tool inventory

createBuiltinToolGroups in session.ts builds the list. Without useSandbox() none of the six filesystem and shell tools exists and the framework tools stand alone. A SandboxFactory may carry a tools(sandbox, options) function; when present it replaces the six with whatever it returns, and task is appended after it. The runtime exports createReadTool, createWriteTool, createEditTool, createBashTool, createGrepTool, and createGlobTool so a factory can keep a subset. The three framework tools are listed here for completeness and are not covered under the Description sub-headings below. There is no list, stat, delete, or process tool for the model; the Sandbox interface has stat, readdir, exists, mkdir, and rm, and the runtime uses them for system-prompt discovery only.

Read

Signature

read({ path: string, offset?: number, limit?: number })

path is relative or absolute and is resolved by the adapter. offset is one-based; zero or a missing offset starts at line one. limit is a line count with no default of its own; the 2000-line and 50 KB caps apply when it is absent. The TypeBox schema types offset and limit as Number with no integer, minimum, or maximum constraint. read_skill_resource uses the same schema and the same formatReadContent function over the packaged skill catalog.

Description

read: 90 characters, 92 bytes, 1 line, approximately 25 tokens.

read (90 characters)

Read a file. Output is truncated to 2000 lines or 50KB — use offset/limit for large files.

Path handling

The tool passes params.path to env.readFile without change, so the adapter decides. On local(), resolvePath is path.isAbsolute(p) ? p : path.resolve(cwd, p): relative paths join cwd, absolute paths pass through, and .. can leave cwd. There is no ~, @, or file:// handling and no containment check. The bash() factory resolves relative paths through bash.fs.resolvePath(cwd, p) and passes absolute paths through. sandboxFromDriver, which cloudflareSandbox builds on, collapses ., .., and empty segments and clamps .. at /. A cwd option on useSandbox() or a task call wraps any adapter in createCwdSandbox, which uses that same POSIX normaliser before the adapter sees the path.

Near-miss recovery: None. The adapter error is thrown as-is. On local() a missing file gives the Node text:

ENOENT: no such file or directory, open '<path>'

The just-bash adapter throws its own ENOENT prefixed message; its exact text is Unverified at the ^3.0.1 range Flue declares. The cloudflareSandbox readFile error text is Not surveyed.

Symlinks: followed with no check on every adapter. read never calls stat, readFileBuffer, or exists.

Permissions

Binary and conversion

Limits

The byte budget is String.length, so 50 KB counts UTF-16 code units, and the newline before each line counts toward it. limit is honoured first, then truncateHead applies the line and byte caps to the slice; whichever is hit first wins.

Output

import { x } from "./x"
export const y = x

The example is Reconstructed from formatReadContent. The result details carry path and the total line count.

Notable

• No repeat-read guard, no content injection after the read, no redaction.
• An empty file returns an empty text part: ''.split('\n') gives one line, so the offset check passes and nothing is emitted.
• The abort signal is checked before the read only. The adapter read is not cancellable. The session wraps every tool in abandonToolOnAbort, so an abort during the read rejects one macrotask later with the message The operation was aborted. The tool execution could not be confirmed cancelled and may still be running., and the orphaned read is consumed silently.
• read does not take the mutation lock, so a parallel read and write on one path can race.
• Host knobs on this family: the sandbox factory (local(), bash(), cloudflareSandbox(), or sandboxFromDriver()), which owns path resolution, decoding, and every error text; local({ cwd }); the cwd option on useSandbox(); the factory's tools(sandbox, options) function, which replaces the whole tool list; and the exported createReadTool(env) for composing a subset.

Edit

Signature

write({ path: string, content: string })
edit({ path: string, oldText: string, newText: string, replaceAll?: boolean })

edit takes one pair per call. Pi's coding agent, whose field names Flue kept, takes an edits[] array; Flue dropped the batch. An empty oldText fails with oldText must be a non-empty string. before the lock is taken. There is no patch tool and no model-facing delete tool.

Description

write: 86 characters, 86 bytes, 1 line, approximately 18 tokens. edit: 136 characters, 136 bytes, 1 line, approximately 28 tokens.

write (86 characters)

Write content to a file. Creates the file and parent directories if they do not exist.

edit (136 characters)

Edit a file using exact text replacement. The oldText must match a unique region of the file. Use replaceAll to replace all occurrences.

Whole-file write

write takes the per-file mutation lock, then calls env.writeFile(path, content). Every adapter routes the write through writeFileCreatingParents: the write is tried first, and on any failure the parent is created with mkdir -p semantics and the write is retried once. Errors from the mkdir are ignored so the retry reproduces the original failure. On local() the write is fs.writeFile(resolved, content) with a UTF-8 string, in place, with no temporary file and rename, no backup, and no post-write verification. BOM and line endings: the content is written as supplied. Mode preservation: Not surveyed. The success text reports content.length, a JavaScript string length, so the number is not a UTF-8 byte count for non-ASCII text.

Matching

Exact only. countOccurrences walks the file with indexOf, advancing past each match so overlapping occurrences count once. Zero matches and more than one match are errors; the file is unchanged. With replaceAll the tool calls String.replaceAll and errors when the result equals the original. Both paths use a function replacer so $& and $$ patterns in the model's newText are literal. There is no fuzzy matching, no whitespace normalisation, no BOM stripping, and no CRLF handling. The model is never told about a fallback because there is none.

Multi-file patch

None. edit covers one file per call. There is no patch grammar and no multi-file tool.

Verification and mutation state

Output

No diff and no snippet is returned. details carry path and size for write, and path with replacements on the replaceAll path.

Notable

• No notebook editor, no undo tool, no checkpoint tool.
• write and edit reject with Operation aborted when the signal is already set at entry or after the lock wait.
• A conflict between two mutations of one file in the same parallel batch surfaces as a Could not find error on the second, because the second reads the first's result.
• Host knobs on this family: the sandbox factory, which owns writeFile, resolvePath (and so the lock key), and every error text; the factory's tools(sandbox, options) function; and the exported createWriteTool(env) and createEditTool(env).

Shell

Signature

bash({ command: string, timeout?: number })

timeout is in seconds and has no default. The tool converts it to milliseconds and passes it to env.exec as timeoutMs and as an AbortSignal.timeout merged with the host signal. There is no cwd, background, or permission parameter. The programmatic harness.shell() and session.shell() paths accept cwd, env, and timeoutMs and format their result with the same formatBashResult.

Description

bash: 102 characters, 102 bytes, 1 line, approximately 25 tokens.

bash (102 characters)

Execute a bash command. Returns stdout and stderr. Output is truncated to the last 2000 lines or 50KB.

Working directory and environment

On local() the working directory is path.resolve(options.cwd ?? process.cwd()), fixed at sandbox creation. The shell is probed once per process with bash -c 'command -v bash'; an absolute result is used, otherwise Node's platform default shell (/bin/sh, or cmd.exe on Windows). The environment is an allowlist snapshot taken once at construction: PATH, HOME, USER, LOGNAME, HOSTNAME, SHELL, LANG, LC_ALL, LC_CTYPE, TZ, TERM, TMPDIR, TMP, and TEMP. local({ env }) layers keys on top, and a key set to undefined drops a default; process.env is never read at exec time. Login shell: None.

The bash() factory takes cwd from bash.getCwd() and runs inside the emulated shell. cloudflareSandbox defaults cwd to /workspace inside the container.

Process lifecycle

Output limits

Sandbox

None on local(). No OS sandbox, container, seccomp, or Seatbelt policy; the network is unrestricted and the child runs as the Flue process account. The sandbox guide names this as the intended shape and says the host or a surrounding container provides isolation. The bash() factory over just-bash is an in-process emulated bash with InMemoryFs; no real process is spawned and network access is whatever the emulated curl allows. cloudflareSandbox runs commands in a @cloudflare/sandbox container.

Approval

None. The runtime ships no approval policy and no per-tool permission hook. A host that wants one supplies its own tools through the factory's tools(sandbox, options) function.

Notable

• A non-zero exit is a successful text result, not an error result. The model sees the output tail and the exit line.
• A model timeout is also a successful text result: [flue] Command timed out after <n> seconds., a blank line, then Command exited with code 124.
• A spawn failure on local() settles with exit code 1 and the spawn error message on stderr.
• No PTY, no streaming to the model, no interactive input.
• session.shell() and harness.shell() emit tool_start and tool events under the bash tool name, with an error result of exitCode: -1 on a thrown error.
• Host knobs on this family: the sandbox factory, which owns the shell, environment, cancellation, and exit-code semantics; local({ cwd, env }); onOrphanSettled on sandboxFromDriver; the factory's tools(sandbox, options) function; and the exported createBashTool(env).

Search and listing

Tools

Both tools run through env.exec. grep probes rg --version once per underlying exec function with a 10 second timeoutMs and a 15 second host-side race; a probe that answers nothing memoises grep. include becomes --glob on ripgrep and --include= on grep; literal becomes --fixed-strings or -F. Arguments are single-quoted. Exit code 1 with empty stdout gives No matches found.; a higher code throws grep failed: <stderr>. glob returns newline-joined paths as find prints them, or No files found matching pattern. when stdout is empty; because find errors go to /dev/null and the pipeline exit code is head's, a missing directory reads as no matches. Neither tool is available on a sandbox without exec.

Description

grep: 98 characters, 98 bytes, 1 line, approximately 18 tokens. glob: 93 characters, 93 bytes, 1 line, approximately 17 tokens.

grep (98 characters)

Search file contents for a regex pattern. Returns matching lines with file paths and line numbers.

glob (93 characters)

Find files by filename pattern using shell find -name semantics. Returns matching file paths.

Errors

The tools throw. Pi's agent loop catches the exception, places the message in one text part, and sets isError on the tool result. The model sees text, not a code; Node error text and absolute paths pass through on local(). Shell exit codes, timeouts, and output overflow are all delivered as ordinary results with the exit line, so the model can recover from them without an error turn.