---
title: Agent API
description: Reference for defining agents and running agent operations with @flue/runtime.
lastReviewedAt: 2026-06-21
---

The agent API is exported from `@flue/runtime`.

```ts
import {
  FlueError,
  ResultUnavailableError,
  ToolInputValidationError,
  ToolLegacyDefinitionError,
  ToolOutputSerializationError,
  ToolOutputValidationError,
  bash,
  connectMcpServer,
  defineAgent,
  defineAgentProfile,
  defineTool,
  dispatch,
  type AgentInitializerContext,
  type AgentDispatchRequest,
  type AgentProfile,
  type AgentRuntimeConfig,
  type BashFactory,
  type CallHandle,
  type CompactionConfig,
  type AgentDefinition,
  type DispatchReceipt,
  type FileStat,
  type FlueFs,
  type FlueHarness,
  type FlueLogger,
  type FlueSession,
  type FlueSessions,
  type McpServerConnection,
  type McpServerOptions,
  type NamedAgentDispatchRequest,
  type PromptImage,
  type PromptModel,
  type PromptOptions,
  type PromptResponse,
  type PromptResultResponse,
  type PromptUsage,
  type SandboxFactory,
  type ShellOptions,
  type ShellResult,
  type Skill,
  type SkillOptions,
  type SkillReference,
  type TaskOptions,
  type ThinkingLevel,
  type ToolContext,
  type ToolDefinition,
  type ToolInput,
  type ToolInputSchema,
  type ToolOutput,
  type ToolOutputSchema,
  type ToolValidationIssue,
} from '@flue/runtime';
```

## `defineAgentProfile(...)`

```ts
function defineAgentProfile(profile: AgentProfile): AgentProfile;
```

Validates and returns a reusable agent profile. Use profiles as the baseline for an agent definition or as named subagents available to `session.task()`.

Throws when the profile contains unknown fields, invalid capabilities, duplicate capability names, or circular subagents.

#### `AgentProfile`

| Field           | Type                        | Description                                                                                                                                                                 |
| --------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                    | Profile name. Required when selecting this profile with `session.task()`.                                                                                                   |
| `description`   | `string`                    | Human-readable profile description.                                                                                                                                         |
| `model`         | `string \| false`           | Default model specifier. Set to `false` to require call-level model selection.                                                                                              |
| `instructions`  | `string`                    | Instructions prepended to discovered workspace context.                                                                                                                     |
| `skills`        | `Skill[]`                   | Registered skills available to initialized sessions.                                                                                                                        |
| `tools`         | `ToolDefinition[]`          | Custom model-callable tools available to initialized sessions.                                                                                                              |
| `actions`       | `ActionDefinition[]`        | Reusable Actions exposed to the model as framework-managed tools.                                                                                                           |
| `subagents`     | `AgentProfile[]`            | Named profiles available for delegated `session.task()` operations.                                                                                                         |
| `thinkingLevel` | `ThinkingLevel`             | Default reasoning effort. Individual operations may override this value.                                                                                                    |
| `compaction`    | `false \| CompactionConfig` | Automatic conversation-compaction configuration. `false` disables threshold compaction; overflow recovery and explicit `session.compact()` calls still compact when needed. |
| `durability`    | `DurabilityConfig`          | Durability configuration for durable agent submissions. Controls recovery attempt limits and submission timeouts. Rejected on subagent profiles.                            |

When a profile is selected as a subagent with `session.task()`, it is self-contained: `instructions`, `tools`, `skills`, and `subagents` apply only as declared on the profile (omitted means none), while `model`, `thinkingLevel`, and `compaction` inherit from the parent as defaults. See [Subagents](/docs/guide/subagents/#configuration-inheritance).

#### `DurabilityConfig`

| Field         | Type     | Default   | Description                                                                                                                                                                                                                                                                                              |
| ------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxAttempts` | `number` | `10`      | Maximum total attempts before the submission is terminalized as failed. The initial run counts as the first attempt; each interruption that requires a new attempt consumes another.                                                                                                                     |
| `timeoutMs`   | `number` | `3600000` | Maximum wall-clock milliseconds for a single submission. Submissions exceeding this limit are aborted and settled as failed. Set higher for long-running agents (e.g. `21_600_000` for a 6-hour agent). The timeout is checked cooperatively at turn boundaries, not preemptively during provider calls. |

#### `CompactionConfig`

| Field              | Type     | Default                        | Description                                                                                                                     |
| ------------------ | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `reserveTokens`    | `number` | model-aware; capped at `20000` | Token headroom reserved before automatic compaction. Smaller model output limits and small context windows reduce this default. |
| `keepRecentTokens` | `number` | `8000`                         | Recent tokens preserved unsummarized after compaction.                                                                          |
| `model`            | `string` | session model                  | Model specifier override used for compaction summaries.                                                                         |

#### `Skill`

```ts
type Skill =
  | SkillReference
  | {
      name: string;
      description: string;
    };
```

Skill metadata registered with an agent, harness, or profile. Imported `SkillReference` values bundle application-owned skill content. Inline metadata adds only a named catalog entry; it does not package or inject an instruction body. Initialization rejects a registered skill whose name collides with a workspace-discovered skill. See [Skills](/docs/guide/skills/).

## `defineTool(...)`

```ts
function defineTool<
  TInput extends ToolInputSchema | undefined = undefined,
  TOutput extends ToolOutputSchema | undefined = undefined,
>(options: {
  name: string;
  description: string;
  input?: TInput;
  output?: TOutput;
  run: ToolDefinition<TInput, TOutput>['run'];
}): ToolDefinition<TInput, TOutput>;
```

Validates a custom model-callable tool and returns a frozen definition. Tool names are checked for collisions with other active tools when a session assembles its tool list.

`input` and `output` are optional Valibot schemas. `input` must be a top-level object schema. Model-supplied input is validated and parsed before `run` receives it; validation failures become tool errors so the model can retry. When present, `output` validates and parses the returned value. Structured output is snapshotted as JSON-compatible data and JSON-stringified for the model. Without an `output` schema, returning `undefined` sends `null` to the model. `emitData(name, data, { id? })` sends trusted structured activity to UI stream readers without exposing it to the model. It validates and snapshots JSON data synchronously. Payloads are persisted verbatim, so do not include raw image bytes, secrets, or unsanitized PII.

#### `ToolDefinition`

| Field         | Type                                      | Description                                                                                                 |
| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `name`        | `string`                                  | Tool name. Must be unique across active built-in and custom tools.                                          |
| `description` | `string`                                  | Tells the model when and how to use this tool.                                                              |
| `input`       | `ToolInputSchema`                         | Optional top-level Valibot object schema.                                                                   |
| `output`      | `ToolOutputSchema`                        | Optional Valibot schema for typed, validated output.                                                        |
| `run`         | `({ input, signal, emitData }) => value \| Promise` | Receives parsed input when declared, an optional `AbortSignal`, and a durable data emitter. Returns JSON-compatible structured data. |

```ts
import { defineTool } from '@flue/runtime';
import * as v from 'valibot';

const lookupPolicy = defineTool({
  name: 'lookup_policy',
  description: 'Read one approved policy by topic.',
  input: v.object({ topic: v.string() }),
  output: v.object({ title: v.string(), body: v.string() }),
  async run({ input, signal }) {
    return readPolicy(input.topic, { signal });
  },
});
```

### Breaking migration

The old `parameters` and `execute` markers now throw when a tool is defined. Rename `parameters` to `input`, rename `execute(args, signal)` to `run({ input, signal })`, and return structured JSON-compatible data directly instead of calling `JSON.stringify(...)`. Add `output` when the returned shape should be typed and validated.

## `connectMcpServer(...)`

```ts
function connectMcpServer(name: string, options: McpServerOptions): Promise<McpServerConnection>;
```

Connects to a remote MCP server and returns its listed tools as Flue tool definitions ready to pass directly in `tools` arrays.

Adapted tool names use `mcp__<server>__<tool>`. Unsupported characters are replaced with underscores, and duplicate adapted names are rejected. Do not wrap these tools with `defineTool()`. Close the returned connection when its tools are no longer needed.

#### `McpServerOptions`

| Field                    | Type                         | Default             | Description                                                                      |
| ------------------------ | ---------------------------- | ------------------- | -------------------------------------------------------------------------------- |
| `url`                    | `string \| URL`              | —                   | MCP server endpoint.                                                             |
| `transport`              | `'streamable-http' \| 'sse'` | `'streamable-http'` | Remote MCP transport. Use `'sse'` for legacy servers.                            |
| `headers`                | `HeadersInit`                | —                   | Headers merged into MCP transport requests.                                      |
| `requestInit`            | `RequestInit`                | —                   | Additional MCP transport request configuration.                                  |
| `fetch`                  | `typeof fetch`               | —                   | Custom fetch implementation used by the MCP transport.                           |
| `timeoutMs`              | `number`                     | `60000`             | Per-request timeout in milliseconds for MCP requests.                            |
| `resetTimeoutOnProgress` | `boolean`                    | `false`             | Reset the per-request timeout whenever the server sends a progress notification. |

#### `McpServerConnection`

```ts
interface McpServerConnection {
  name: string;
  tools: ToolDefinition[];
  close(): Promise<void>;
}
```

| Field     | Description                                            |
| --------- | ------------------------------------------------------ |
| `name`    | Server name supplied to `connectMcpServer()`.          |
| `tools`   | MCP tools ready to pass directly in `tools` arrays.     |
| `close()` | Close the underlying MCP client connection.            |

## `defineAgent(...)`

```ts
function defineAgent<TEnv = Record<string, any>>(
  initialize: (
    context: AgentInitializerContext<TEnv>,
  ) => AgentRuntimeConfig | Promise<AgentRuntimeConfig>,
): AgentDefinition<TEnv>;
```

Defines an agent initializer. Default-export the returned value from an `agents/<name>.ts` module to define an addressable agent, or bind it to a Workflow Definition.

The initializer runs whenever a runner initializes a root harness from the agent definition. Do not treat it as a one-time constructor for a persistent agent instance id. Return a runtime config object with `model: '<provider>/<model>'`, `model: false`, or a profile with its own model field.

#### `AgentInitializerContext`

| Field | Type     | Description                                            |
| ----- | -------- | ------------------------------------------------------ |
| `id`  | `string` | Agent instance ID or workflow run ID.                  |
| `env` | `TEnv`   | Platform environment bindings supplied by the runtime. |

#### `AgentRuntimeConfig`

| Field           | Type                        | Description                                                                                                                                                                                                                                                                               |
| --------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description`   | `string`                    | Optional organizational metadata describing what this agent does. Overrides the profile description when set. Per-initialization metadata only — for a static description that surfaces in the deployment manifest and `listAgents()`, use the module-level `description` export instead. |
| `profile`       | `AgentProfile`              | Reusable baseline profile. Agent-definition fields replace or extend profile values.                                                                                                                                                                                                         |
| `model`         | `string \| false`           | Default model specifier. Set to `false` to require call-level model selection.                                                                                                                                                                                                            |
| `instructions`  | `string`                    | Instructions prepended to discovered workspace context.                                                                                                                                                                                                                                   |
| `skills`        | `Skill[]`                   | Additional registered skills available to initialized sessions.                                                                                                                                                                                                                           |
| `tools`         | `ToolDefinition[]`          | Additional custom model-callable tools available to initialized sessions.                                                                                                                                                                                                                 |
| `actions`       | `ActionDefinition[]`        | Additional reusable Actions exposed as framework-managed model tools.                                                                                                                                                                                                                     |
| `subagents`     | `AgentProfile[]`            | Additional named profiles available for delegated `session.task()` operations.                                                                                                                                                                                                            |
| `thinkingLevel` | `ThinkingLevel`             | Default reasoning effort. Individual operations may override this value.                                                                                                                                                                                                                  |
| `compaction`    | `false \| CompactionConfig` | Automatic conversation-compaction configuration. `false` disables threshold compaction; overflow recovery and explicit `session.compact()` calls still compact when needed.                                                                                                               |
| `durability`    | `DurabilityConfig`          | Durability configuration for durable agent submissions. Controls recovery attempt limits and submission timeouts.                                                                                                                                                                         |
| `cwd`           | `string`                    | Working directory inside the initialized sandbox.                                                                                                                                                                                                                                         |
| `sandbox`       | `SandboxFactory`            | Sandbox factory used to construct the initialized environment. Omit for the default in-memory sandbox; use `bash(...)` to wrap a custom just-bash factory (`BashFactory`). See [Sandboxes](/docs/guide/sandboxes/).                                                                       |

#### `AgentDefinition`

`AgentDefinition` is the opaque initializer value returned by `defineAgent()`.

## `dispatch(...)`

```ts
function dispatch(agent: AgentDefinition, request: AgentDispatchRequest): Promise<DispatchReceipt>;

function dispatch(request: NamedAgentDispatchRequest): Promise<DispatchReceipt>;

interface AgentDispatchRequest {
  id: string;
  input: unknown;
}

interface NamedAgentDispatchRequest extends AgentDispatchRequest {
  agent: string;
}

interface DispatchReceipt {
  dispatchId: string;
  acceptedAt: string;
}
```

Accepts input for asynchronous delivery to a continuing agent instance. The agent-definition overload requires a value default-exported by one discovered `agents/<name>.ts` module. The named overload selects a discovered agent module by name.

| Field        | Description                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `agent`      | Discovered agent module name for the named overload.                                                  |
| `id`         | Target agent instance id.                                                                             |
| `input`      | Required JSON-like input. Use `null` for an intentional empty value. Flue snapshots it when accepted. |
| `dispatchId` | Generated delivery identifier returned in the receipt. This is not a workflow `runId`.                |
| `acceptedAt` | ISO timestamp assigned when dispatch admission begins.                                                |

`await dispatch(...)` resolves when the current runtime accepts and queues the input. It does not wait for model processing, tool calls, or an agent reply. Dispatched activity belongs to the continuing agent instance: it does not create workflow-run history and does not appear in SDK `client.runs` or raw `/runs` APIs.

Delivery durability depends on the generated target. Node uses a process-lifetime in-memory queue by default; with a durable `db.ts` adapter, dispatches survive restarts and are reconciled on the replacement process. Cloudflare durably admits delivery to the target agent Durable Object, orders it with direct prompts, and reconciles interruptions conservatively. Both targets retry only when replay safety is provable; external effects still require application-level idempotency. See [Durable Agents](/docs/concepts/durable-execution/) for recovery details, and [Deploy Agents on Node.js](/docs/ecosystem/deploy/node/) and [Deploy Agents on Cloudflare](/docs/ecosystem/deploy/cloudflare/) for target-specific setup.

## Agent

An agent definition is the opaque value returned by `defineAgent()`. Default-export it from `agents/<name>.ts` to make persistent instances addressable, or bind it to a workflow as execution policy. Workflow runners initialize their harness automatically.

## Harness

A harness is an initialized agent environment supplied by the active runner. Actions receive it as `context.harness`; application code does not name or initialize workflow harnesses.

#### `FlueHarness`

Initialized agent environment for sessions and workspace operations.

```ts
interface FlueHarness {
  readonly name: string;
  session(name?: string): Promise<FlueSession>;
  readonly sessions: FlueSessions;
  shell(command: string, options?: ShellOptions): CallHandle<ShellResult>;
  readonly fs: FlueFs;
}
```

### `harness.session(...)`

```ts
session(name?: string): Promise<FlueSession>;
```

Gets or creates a session in this harness. Defaults to the `'default'` session. Names beginning with `task:` are reserved for framework-owned detached task sessions.

### `harness.sessions.get(...)`

```ts
get(name?: string): Promise<FlueSession>;
```

Loads an existing session. Defaults to `'default'`. Rejects with `SessionNotFoundError` if it does not exist.

### `harness.sessions.create(...)`

```ts
create(name?: string): Promise<FlueSession>;
```

Creates a new session. Defaults to `'default'`. Rejects with `SessionAlreadyExistsError` if it already exists.

### `harness.sessions.delete(...)`

```ts
delete(name?: string): Promise<void>;
```

Deletes a session's stored conversation state. Defaults to `'default'`. No-op when missing. Rejects with `SessionBusyError` if the open session has an active operation. It also rejects while the session has accepted durable submissions queued or running. Session-management requests for one name are applied in request order.

### `harness.shell(...)`

```ts
shell(command: string, options?: ShellOptions): CallHandle<ShellResult>;
```

Runs a shell command in the harness sandbox without recording it in a conversation.

### `harness.fs`

- **Type:** `FlueFs`

Reads and writes files in the harness sandbox without recording them in a conversation.

## Session

A session is named conversation state inside a harness. A session runs one active `prompt`, `skill`, `task`, `shell`, or `compact` operation at a time. Use separate named sessions for parallel conversation branches.

#### `FlueSession`

Named conversation state inside a harness.

```ts
interface FlueSession {
  readonly name: string;
  prompt(text: string, options?: PromptOptions): CallHandle<PromptResponse>;
  skill(skill: SkillReference | string, options?: SkillOptions): CallHandle<PromptResponse>;
  task(text: string, options?: TaskOptions): CallHandle<PromptResponse>;
  shell(command: string, options?: ShellOptions): CallHandle<ShellResult>;
  readonly fs: FlueFs;
  compact(): Promise<void>;
  delete(): Promise<void>;
}
```

The `prompt()`, `skill()`, and `task()` signatures above omit structured-result overloads. Pass a Valibot schema as `options.result` to resolve with validated `response.data`.

### `session.prompt(...)`

```ts
prompt(text: string, options?: PromptOptions): CallHandle<PromptResponse>;
```

Runs a model operation with a text instruction.

#### `PromptOptions`

| Field           | Type               | Description                                                           |
| --------------- | ------------------ | --------------------------------------------------------------------- |
| `result`        | Valibot schema     | Require validated structured data and resolve with `response.data`.   |
| `tools`         | `ToolDefinition[]` | Additional custom model-callable tools for this operation.            |
| `model`         | `string`           | Model specifier override for this operation.                          |
| `thinkingLevel` | `ThinkingLevel`    | Reasoning-effort override for this operation.                         |
| `signal`        | `AbortSignal`      | Cancel this operation.                                                |
| `images`        | `PromptImage[]`    | Images attached to the user message. Requires a vision-capable model. |

#### `PromptImage`

```ts
type PromptImage = {
  type: 'image';
  data: string;
  mimeType: string;
};
```

The selected model must support image input.

#### `PromptResponse`

```ts
interface PromptResponse {
  text: string;
  usage: PromptUsage;
  model: PromptModel;
}
```

#### `PromptUsage`

Aggregated token and cost usage for model work performed by one operation. Tool use, result retries, and automatic compaction may cause one operation to include multiple model turns.

#### `PromptModel`

```ts
interface PromptModel {
  provider: string;
  id: string;
}
```

Model selected for the operation's primary turn.

#### `PromptResultResponse`

```ts
interface PromptResultResponse<T> {
  data: T;
  usage: PromptUsage;
  model: PromptModel;
}
```

A structured-result operation throws `ResultUnavailableError` when the agent cannot produce validated data.

### `session.skill(...)`

```ts
skill(skill: SkillReference | string, options?: SkillOptions): CallHandle<PromptResponse>;
```

Runs a registered skill. Pass `options.result` to require validated structured data instead of freeform text.

#### `SkillReference`

```ts
interface SkillReference {
  readonly __flueSkillReference: true;
  readonly id: string;
  readonly name: string;
  readonly description: string;
}
```

Opaque imported packaged-skill reference accepted by `session.skill()`. Import a `SKILL.md` value rather than constructing one manually.

#### `SkillOptions`

| Field           | Type                      | Description                                                                   |
| --------------- | ------------------------- | ----------------------------------------------------------------------------- |
| `args`          | `Record<string, unknown>` | Arguments included with the skill instruction.                                |
| `result`        | Valibot schema            | Require validated structured data and resolve with `response.data`.           |
| `tools`         | `ToolDefinition[]`        | Additional custom model-callable tools for this operation.                    |
| `model`         | `string`                  | Model specifier override for this operation.                                  |
| `thinkingLevel` | `ThinkingLevel`           | Reasoning-effort override for this operation.                                 |
| `signal`        | `AbortSignal`             | Cancel this operation.                                                        |
| `images`        | `PromptImage[]`           | Images attached to the skill's user message. Requires a vision-capable model. |

### `session.task(...)`

```ts
task(text: string, options?: TaskOptions): CallHandle<PromptResponse>;
```

Delegates work to a detached child session. Pass `options.agent` to select a named subagent profile and `options.result` to require validated data. Completed child history remains parent-owned until the parent session is deleted or application-owned retention removes it.

#### `TaskOptions`

| Field           | Type               | Description                                                                          |
| --------------- | ------------------ | ------------------------------------------------------------------------------------ |
| `agent`         | `string`           | Named subagent profile selected for this delegated task.                             |
| `result`        | Valibot schema     | Require validated structured data and resolve with `response.data`.                  |
| `tools`         | `ToolDefinition[]` | Additional custom model-callable tools for this operation.                           |
| `model`         | `string`           | Model specifier override for this operation.                                         |
| `thinkingLevel` | `ThinkingLevel`    | Reasoning-effort override for this operation.                                        |
| `cwd`           | `string`           | Working directory for the detached task session. Defaults to the parent session cwd. |
| `signal`        | `AbortSignal`      | Cancel this task.                                                                    |
| `images`        | `PromptImage[]`    | Images attached to the task's initial user message. Requires a vision-capable model. |

### `session.shell(...)`

```ts
shell(command: string, options?: ShellOptions): CallHandle<ShellResult>;
```

Runs a shell command and records its command exchange in conversation state.

#### `ShellOptions`

| Field       | Type                     | Description                                                                             |
| ----------- | ------------------------ | --------------------------------------------------------------------------------------- |
| `env`       | `Record<string, string>` | Environment variables supplied to the command.                                          |
| `cwd`       | `string`                 | Working directory supplied to the command.                                              |
| `timeoutMs` | `number`                 | Wall-clock deadline in milliseconds, forwarded to the sandbox adapter's native timeout. |
| `signal`    | `AbortSignal`            | Cancel this operation.                                                                  |

#### `ShellResult`

```ts
interface ShellResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}
```

### `session.fs`

- **Type:** `FlueFs`

Reads and writes files in the session sandbox without recording them in the conversation transcript.

### `session.compact()`

```ts
compact(): Promise<void>;
```

Triggers conversation compaction immediately. Resolves without work when there is nothing to compact. Rejects when summarization fails or is aborted. Rejects with `SessionBusyError` if another operation is active on the session.

### `session.delete()`

```ts
delete(): Promise<void>;
```

Deletes this session's stored conversation state. Rejects with `SessionBusyError` while an operation is active. It also rejects while accepted durable submissions are queued or running for the session. Once deletion starts, the session is unusable and concurrent calls share the same deletion work.

#### `CallHandle<T>`

```ts
interface CallHandle<T> extends Promise<T> {
  readonly signal: AbortSignal;
  abort(reason?: unknown): void;
}
```

`prompt()`, `skill()`, `task()`, and `shell()` return awaitable call handles. Retain the handle when application code needs to cancel in-flight work. Aborting rejects the awaited operation with an `AbortError` (`DOMException`). Pass `options.signal` to merge an external abort signal with the handle's signal.

Other session failures reject with typed `FlueError` subclasses such as `SessionBusyError`, `SkillNotRegisteredError`, and `ModelNotConfiguredError`, all importable from `@flue/runtime`. See the [Errors Reference](/docs/api/errors-reference/) for the full vocabulary.

#### `FlueFs`

```ts
interface FlueFs {
  readFile(path: string): Promise<string>;
  readFileBuffer(path: string): Promise<Uint8Array>;
  writeFile(path: string, content: string | Uint8Array): Promise<void>;
  stat(path: string): Promise<FileStat>;
  readdir(path: string): Promise<string[]>;
  exists(path: string): Promise<boolean>;
  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
}
```

Paths may be absolute or relative. Relative paths use the configured `cwd`, or the sandbox adapter's default when `cwd` is omitted; use absolute paths for portability across sandbox adapters. These operations are out-of-band and do not appear in conversation history.

`writeFile()` creates missing parent directories automatically, in every sandbox mode — no prior `mkdir()` is needed before writing to a nested path.

#### `FileStat`

```ts
interface FileStat {
  isFile: boolean;
  isDirectory: boolean;
  isSymbolicLink?: boolean;
  size?: number;
  mtime?: Date;
}
```

`isSymbolicLink`, `size`, and `mtime` are omitted when the sandbox adapter's provider does not expose them.