> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Runtime

# Agent Runtime 🤖

WednesdayAI runs a single embedded agent runtime derived from **pi-mono**.

## Workspace (required)

WednesdayAI uses a single agent workspace directory (`agents.defaults.workspace`) as the agent’s **only** working directory (`cwd`) for tools and context.

Recommended: use `wednesdayai setup` to create `~/.openclaw/openclaw.json` if missing and initialize the workspace files.

Full workspace layout + backup guide: [Agent workspace](https://docs.wednesdayai.dev/next/developers/concepts/agent-workspace.md)

If `agents.defaults.sandbox` is enabled, non-main sessions can override this with
per-session workspaces under `agents.defaults.sandbox.workspaceRoot` (see
[Gateway configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md)).

## Bootstrap files (injected)

Inside `agents.defaults.workspace`, WednesdayAI expects these user-editable files:

* `AGENTS.md` — operating instructions + “memory”
* `SOUL.md` — persona, boundaries, tone
* `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions)
* `BOOTSTRAP.md` — one-time first-run ritual (deleted after completion)
* `IDENTITY.md` — agent name/vibe/emoji
* `USER.md` — user profile + preferred address

On the first turn of a new session, WednesdayAI injects the contents of these files directly into the agent context.

Blank files are skipped. Large files are trimmed and truncated with a marker so prompts stay lean (read the file for full content).

If a file is missing, WednesdayAI injects a single “missing file” marker line (and `wednesdayai setup` will create a safe default template). An absent `BOOTSTRAP.md` is the exception: it is omitted from the injected context with no marker, because it is supposed to be gone once onboarding completes.

`BOOTSTRAP.md` is only created for a **brand new workspace** (no other bootstrap files present). The agent finishes the ritual by deleting it with the built-in `delete` tool, and after that it is not recreated and no longer injected on later restarts.

To disable bootstrap file creation entirely (for pre-seeded workspaces), set:

```json5 theme={"dark"}
{ agent: { skipBootstrap: true } }
```

## Built-in tools

Core tools (read/exec/edit/write/delete and related system tools) are always available,
subject to tool policy. `delete` removes one file per call and is always confined to the agent workspace (or the lane workspace when lanes are on), even when `tools.fs.workspaceOnly` is `false`. `apply_patch` is optional and gated by
`tools.exec.applyPatch`. `TOOLS.md` does **not** control which tools exist; it's
guidance for how *you* want them used.

### Tool profiles

Tool profiles set a baseline tool set before allow/deny lists apply. Set globally with `tools.profile` or per-agent with `agents.list[].tools.profile`:

* `minimal` — read, write, edit, exec only
* `coding` — coding-oriented tools (read, write, edit, delete, exec, apply\_patch, browser)
* `messaging` — messaging-oriented tools (message, sessions tools). Note: this profile has no filesystem tools, so onboarding adds `tools.alsoAllow: ["group:fs"]` on new deployments to give the agent workspace-contained `read`/`write`/`edit`/`delete`
* `full` — all tools (default when no profile is set)

### Tool allow/deny

Fine-grained control via `tools.allow`, `tools.deny`, and per-agent `agents.list[].tools.allow/deny`. Use `tools.alsoAllow` for additive entries that merge into the existing allowlist without replacing it. Deny always wins.

The `gateway` tool also matches **action tokens** (`gateway.config_apply`, `gateway.config_patch`, and so on). For non-sandbox agents, whole-document `config.apply` is denied by default. Re-enable with `tools.allow` or `tools.alsoAllow` (including `agents.list[].tools.alsoAllow`). Bare `*` does not count. See [Config writes](https://docs.wednesdayai.dev/next/admin/gateway/config-writes.md).

Per-provider overrides: `tools.byProvider.<provider>.allow/deny` scopes tool policy to a specific model provider or `provider/model` pair.

### Session tool visibility

`tools.sessions.visibility` controls which sessions session tools (`sessions_list`, `sessions_history`, `sessions_send`, `agents_nudge`) can target:

* `self` — only the current session
* `tree` — current session + spawned subagent sessions (default)
* `agent` — any session belonging to the current agent id
* `all` — any session (cross-agent still requires `tools.agentToAgent`)

### Agent-to-agent messaging

`tools.agentToAgent` controls cross-agent session tools. Disabled by default:

```json5 theme={"dark"}
{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["home", "work"], // agent id allowlist
    },
  },
}
```

### Sub-agent tool policy

`tools.subagents.tools` sets the default tool policy for spawned sub-agents. See [Sub-agents](https://docs.wednesdayai.dev/next/users/tools/subagents.md) for full details.

### Filesystem restrictions

`tools.fs.workspaceOnly: true` restricts filesystem tools (read/write/edit/apply\_patch) to the agent workspace directory.

Unset (the default), `read`, `write` and `edit` can reach any path the gateway user can access;
the sandbox is also off by default. `apply_patch` stays workspace-only unless
`tools.exec.applyPatch.workspaceOnly` is also set to `false`. The `delete` tool is always workspace-contained regardless of this setting. Set `workspaceOnly: true` as a single guardrail against accidental
writes outside the workspace.

Known limitation: with `workspaceOnly: true`, `read` refuses bundled and managed `SKILL.md` paths outside the workspace, so skill instructions cannot be loaded. Workaround: set `tools.fs.workspaceOnly: false`.

### Exec configuration

`tools.exec` controls exec tool behavior: `host` (sandbox/gateway/node), `security` (deny/allowlist/full), `ask` (off/on-miss/always), `safeBins`, and more. Per-agent overrides via `agents.list[].tools.exec`.

### Loop detection

`tools.loopDetection` guards against repetitive tool-call patterns. See [Tool-loop detection](https://docs.wednesdayai.dev/next/users/tools/loop-detection.md).

## Skills

WednesdayAI loads skills from three locations (workspace wins on name conflict):

* Bundled (shipped with the install)
* Managed/local: `~/.openclaw/skills`
* Workspace: `<workspace>/skills`

Skills can be gated by config/env (see `skills` in [Gateway configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md)).

## pi-mono integration

WednesdayAI reuses pieces of the pi-mono codebase (models/tools), but **session management, discovery, and tool wiring are WednesdayAI-owned**.

* No pi-coding agent runtime.
* No `~/.pi/agent` or `<workspace>/.pi` settings are consulted.

## Sessions

Session transcripts are stored in the SQL session database:

* `~/.openclaw/sessions.db` (SQLite default; per-agent index identity at
  `~/.openclaw/agents/<agentId>/sessions/sessions.json`)

The session ID is stable and chosen by WednesdayAI.
Legacy Pi/Tau session folders are **not** read.

## Steering while streaming

When queue mode is `steer`, inbound messages are injected into the current run.
The queue is checked **after each tool call**; if a queued message is present,
remaining tool calls from the current assistant message are skipped (error tool
results with "Skipped due to queued user message."), then the queued user
message is injected before the next assistant response.

When queue mode is `followup` or `collect`, inbound messages are held until the
current turn ends, then a new agent turn starts with the queued payloads. See
[Queue](https://docs.wednesdayai.dev/next/developers/concepts/queue.md) for mode + debounce/cap behavior.

Block streaming sends completed assistant blocks as soon as they finish; it is
**off by default** (`agents.defaults.blockStreamingDefault: "off"`).
Tune the boundary via `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text\_end).
Control soft block chunking with `agents.defaults.blockStreamingChunk` (defaults to
800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
Coalesce streamed chunks with `agents.defaults.blockStreamingCoalesce` to reduce
single-line spam (idle-based merging before send). Non-Telegram channels require
explicit `*.blockStreaming: true` to enable block replies.
Verbose tool summaries are emitted at tool start (no debounce); Control UI
streams tool output via agent events when available.
More details: [Streaming + chunking](https://docs.wednesdayai.dev/next/developers/concepts/streaming.md).

## Model refs

Model refs in config (for example `agents.defaults.model` and `agents.defaults.models`) are parsed by splitting on the **first** `/`.

* Use `provider/model` when configuring models.
* If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
* If you omit the provider, WednesdayAI treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).

## Configuration (minimal)

At minimum, set:

* `agents.defaults.workspace`
* `channels.whatsapp.allowFrom` (strongly recommended)

***

*Next: [Group Chats](https://docs.wednesdayai.dev/next/admin/channels/group-messages.md)* 🦞


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.