Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/withastro/flue/llms.txt

Use this file to discover all available pages before exploring further.

FlueHarness is returned by init() and represents a configured handle for model defaults, tools, sandbox, filesystem, and sessions within a single run. Most agent code interacts with a harness to open sessions and run shell commands outside the conversation context.

​
Properties

​
name
string
The harness name. Defaults to "default". Use init({ name }) to create multiple isolated harnesses per run.
​
fs
FlueFs
Out-of-band filesystem access to the harness sandbox. Operations do not appear in any conversation transcript. Use fs for plumbing (staging files, capturing artifacts, managing scratch space). If a write should feed into the model’s next turn, prompt the model to read the file itself.
​
sessions
FlueSessions
Explicit session management: get, create, or delete named sessions. Use harness.session() for the common get-or-create pattern; use harness.sessions when you need strict control over session existence.

​
Methods

​
session(name?, options?)

Get or create a named session. If the session already exists it is returned; otherwise a new one is created. 
const session = await harness.session();                     // default session
const review  = await harness.session('review-thread');      // named session
const scoped  = await harness.session('plan', { role: 'planner' }); // with role
​
name
string
Session name. Defaults to "default".
​
options.role
string
Session-wide default role. Per-call roles override this.
Returns Promise<FlueSession>.

​
shell(command, options?)

Run a shell command in the harness sandbox. Unlike session.shell(), this call is not recorded in any conversation transcript. Use it for setup, artifact extraction, or any shell work the model shouldn’t see. 
await harness.shell('npm install', { cwd: '/workspace/project' });
const { stdout } = await harness.shell('cat /workspace/result.json');
​
command
string
required
Shell command to execute.
​
options.cwd
string
Working directory for the command.
​
options.env
Record<string, string>
Additional environment variables.
​
options.signal
AbortSignal
Cancel the in-flight command.
Returns CallHandle<ShellResult>.

​
FlueSessions

Explicit session management. Access via harness.sessions.

​
sessions.get(name?, options?)

Load an existing session. Throws if the session does not exist. 
const session = await harness.sessions.get('review-thread');

​
sessions.create(name?, options?)

Create a new session. Throws if a session with that name already exists. 
const fresh = await harness.sessions.create('new-branch');

​
sessions.delete(name?)

Delete a session’s stored conversation state. No-op if the session does not exist. 
await harness.sessions.delete('old-thread');

​
FlueFs

The fs object on both FlueHarness and FlueSession exposes the sandbox filesystem for out-of-band reads and writes. 
// Stage a config file before prompting
await harness.fs.writeFile('/workspace/config.json', JSON.stringify({ rules: [] }));

// Read an artifact the agent produced
const result = await harness.fs.readFile('/workspace/output.md');
MethodSignatureDescription
readFile(path) → Promise<string>Read a UTF-8 file. Throws if missing.
readFileBuffer(path) → Promise<Uint8Array>Read raw bytes.
writeFile(path, content) → Promise<void>Write string or bytes. Creates if missing, replaces if present.
stat(path) → Promise<FileStat>File metadata: isFile, isDirectory, isSymbolicLink, size, mtime.
readdir(path) → Promise<string[]>List directory entry names (not full paths).
exists(path) → Promise<boolean>Returns true if path exists. Never throws.
mkdir(path, options?) → Promise<void>Create directory. Pass { recursive: true } for mkdir -p.
rm(path, options?) → Promise<void>Remove file or directory. Pass { recursive: true, force: true } as needed.

​
CallHandle

All methods that return CallHandle<T> are awaitable and cancellable. 
const handle = harness.shell('long-running-command');

// Abort after 5 seconds
setTimeout(() => handle.abort('timeout'), 5000);

const result = await handle; // resolves or rejects with AbortError
​
signal
AbortSignal
Fires when the call is aborted, whether via handle.abort() or an options.signal passed at call time.
​
abort
(reason?) => void
Cancel the in-flight call. The awaited promise rejects with an AbortError.

​
ShellResult

Returned by harness.shell() and session.shell().
​
stdout
string
Standard output of the command.
​
stderr
string
Standard error of the command.
​
exitCode
number
Exit code. 0 indicates success.

Build docs developers (and LLMs) love

Get started for freeTalk to us