Built-ins: the harness and capability catalog, with tools and parameters
---
# Built-ins Overview
> Built-in harness types and capabilities that ship with Everruns. Harnesses define reusable behavior; Agent Sandbox Template bindings select compute.
Source:
Everruns ships with built-in **harness types** and **capabilities** that provide the foundation for agent sessions. ## Harnesses A harness defines reusable session behavior: system prompt, default model, starter files, network policy, and bundled capabilities. Every session is assigned a harness. An Agent [Sandbox Template binding](https://everruns.com/docs/features/sandbox-templates/) independently selects the filesystem and compute target for new sessions. | Harness | Description | Capabilities | | -------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------- | | [Base](https://everruns.com/docs/built-ins/harnesses/base/) | System essentials every agent needs | Compaction, error disclosure, tool-call repair, loop detection, approval guidance | | [Conversation](https://everruns.com/docs/built-ins/harnesses/conversation/) | Default for dialogue, no workspace | Base + structured questions, message timestamps | | [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) | Worker without compute | Base + files, AGENTS.md, skills, long context, budgeting, subagents, tasks | | [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) | Worker with the Bashkit virtual shell | Worker + Bashkit shell, fixed Sandbox Template | | [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) | Worker with a full sandbox | Worker + the shell of a container or managed Sandbox Template | | [Worker Base (deprecated)](https://everruns.com/docs/built-ins/harnesses/worker-base/) | Deprecated legacy bundle | Files, bash, project instructions | | [Generic (deprecated)](https://everruns.com/docs/built-ins/harnesses/generic/) | Deprecated legacy bundle | 25 configured | | [Data Analyst](https://everruns.com/docs/built-ins/harnesses/data-analyst/) | SQL databases, charts, persistent memory | Bashkit Worker + data capabilities; available as a built-in example | [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) is a managed Agent bound to Bashkit Worker.  See the [Harnesses feature guide](https://everruns.com/docs/features/harnesses/) for harness selection, API management, and the prompt stack model. ## Harness Examples Harness examples are adoptable templates. Import them when you want a preconfigured starting point, then customize the resulting org-owned harness. | Example | Import Name | Description | | ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Coding (beta) | `coding` | Sandbox Worker + coding behavior for one or several GitHub repositories: [Repositories](https://everruns.com/docs/capabilities/repositories/), [code navigation](https://everruns.com/docs/capabilities/code-navigation/), [GitHub](https://everruns.com/docs/capabilities/github/) with pull requests, and GitHub Scout; the Agent Sandbox Template binding selects Daytona, a container, or another full sandbox | | Data Analyst | `data-analyst` | Bashkit Worker + SQL databases, charts, persistent memory, and curated data knowledge | ## Capabilities Capabilities are modular units that extend what an agent can do. Each can contribute tools, system prompt additions, and UI features. Browse the full [Capabilities reference](https://everruns.com/docs/capabilities/) for the complete list organized by category.
---
# Base Harness
> The root of the built-in harness tree, carrying the system essentials every agent needs to run reliably.
Source:
The **Base** harness is the root of the [built-in harness tree](https://everruns.com/docs/features/harnesses/#built-in-harnesses). It carries only what every agent needs to run reliably, and adds no workspace, shell or chat tools. ## When to Use * Custom tool composition on a reliable foundation * Testing individual capabilities without a workspace or delegation * Building your own harness family with Base as the parent ## Configuration | Property | Value | | ----------------- | ---------------------------------------------------------------------------------------------------------- | | **Name** | `base` | | **Parent** | None | | **Capabilities** | Context compaction, error disclosure, tool-call repair, loop detection, parallel tool calls, soft approval | | **System Prompt** | None. When no harness, agent or session supplies a prompt, the runtime uses “You are a helpful assistant.” | | **Default Model** | None (inherits from agent or organization) | Soft approval is guidance, not a permission wall. It adds the approval tools and costs nothing on safe work; turn it off per agent with `{"mode": "off"}`. ## Usage Assign the Base harness when creating an agent or session:
```bash
curl -X POST http://localhost:9300/api/v1/agents \
-H "Content-Type: application/json" \
-d '{
"name": "Minimal Agent",
"harness_name": "base",
"capabilities": ["web_fetch"]
}'
```
The agent’s own capabilities are added on top. In this example `web_fetch` is the only domain tool.
```rust
let harness = everruns::Harness::base();
```
For a harness with no capabilities at all, build one with `Harness::builder` in the Framework or create a custom harness without a parent on the Platform. ## See Also * [Conversation Harness](https://everruns.com/docs/built-ins/harnesses/conversation/), the default for simple dialogue * [Worker Harness](https://everruns.com/docs/built-ins/harnesses/worker/), the worker kit without compute * [Harnesses feature guide](https://everruns.com/docs/features/harnesses/), the tree and how to choose Compaction uses automatic strategy selection with proactive reduction and a 64,000-token working-history target. Child harnesses inherit it, including Conversation and the Worker variants. Inspect the effective policy and saved checkpoint through the session’s **Context** button or `GET /v1/sessions/{id}/context-report`. Framework sessions expose the same metadata through `session.inspect().await?.compaction`. See [compaction](https://everruns.com/docs/advanced/compaction/) for configuration and storage guarantees.
---
# Bashkit Worker Harness
> Worker plus the Bashkit virtual shell, sealed to one recoverable Bashkit virtual workspace.
Source:
**Bashkit Worker** extends [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) with the Bashkit shell and fixes the primary Sandbox to Everruns’ managed Bashkit Virtual Workspace. | | | | ------------------- | ----------------------------------------------- | | **Name** | `bashkit-worker` | | **Parent** | `worker` | | **Adds** | `bashkit_shell` | | **Sandbox policy** | Fixed; Agent and Session overrides are rejected | | **Primary Sandbox** | Managed Bashkit Virtual Workspace | Use Bashkit Worker for support, operations, and general assistants that need a durable virtual filesystem and Bash-like commands but do not need native packages, processes, ports, or PTYs. It needs no sandbox provider, and the logical Sandbox and workspace survive replacement of runtime compute. [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) runs on it. Choose [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) when an agent needs a real machine, or [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) when it needs no shell. Add `sandbox_fleet` separately when an Agent should keep its primary workspace while creating and operating multiple explicitly addressed resource Sandboxes. Custom Harnesses may inherit from Bashkit Worker, but they inherit the sealed Sandbox policy as well. Renaming the child or changing its capabilities does not make the primary Sandbox overridable.
```rust
let harness = everruns::Harness::bashkit_worker();
```
---
# Conversation Harness
> The default harness for simple dialogue, with no workspace and no shell.
Source:
Conversation inherits [Base](https://everruns.com/docs/built-ins/harnesses/base/) and adds the two chat affordances, `ask_user` for structured questions and `message_metadata` so the model sees when each message was sent. It provides no filesystem, bash, storage, delegation or web search tools. Add [Web Search](https://everruns.com/docs/capabilities/web-search/) on the agent when an assistant should search. It is the organization default. Use it for chat assistants, support bots and Q\&A. Dad Jokes uses this harness plus `current_time`. Add task-specific capabilities on the agent when needed. Workers do not inherit Conversation: [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) builds on Base directly, so an unattended worker does not pick up chat affordances it has no one to use with. Choose `conversation` with the API’s `harness_name` or the CLI’s `--harness` option.
```rust
let harness = everruns::Harness::conversation();
```
Framework constructors load the same capability data as the hosted presets. Enable the host integrations required by the tools you use; a preset does not compile optional integrations into your application. See [Harnesses](https://everruns.com/docs/features/harnesses/) for selection and inheritance.
---
# Data Analyst Harness
> Data analysis harness with SQL databases, persistent memory, interactive charts, and a structured analysis pipeline inspired by OpenAI's Dash.
Source:
The **Data Analyst** harness extends the [Bashkit Worker harness](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) with capabilities for data analysis: SQL databases, cross-session agent memory, rich visualization via OpenUI, and a curated knowledge scaffold. Its system prompt implements a structured 6-step analysis pipeline inspired by [OpenAI’s Kepler data agent](https://openai.com/index/inside-our-in-house-data-agent/) and the open-source [Dash](https://github.com/agno-agi/dash) project. ## When to Use * Natural-language data analysis (ask questions, get SQL + charts) * Interactive data exploration with visualization * Agents that learn from corrections and remember them across sessions * Analytics workflows grounded in curated knowledge bases (table docs, business rules, validated SQL) ## Configuration | Property | Value | | ----------------- | ------------------------------------------ | | **Type** | `data-analyst` | | **System Prompt** | Structured 6-step analysis pipeline | | **Default Model** | None (inherits from agent or organization) | ## Analysis Pipeline The system prompt guides the agent through six steps on every data question: 1. **Recall**: Read `/memory/agent/` for corrections, column mappings, and business definitions from earlier sessions 2. **Inspect**: Use `sql_schema` to verify table structure before writing SQL 3. **Plan**: State the query plan: tables, joins, filters, expected grain, and potential pitfalls 4. **Execute & Validate**: Run the query, then validate (zero rows? duplicates? NULL aggregations?). Self-correct if results look wrong 5. **Visualize**: Summarize findings in plain language, then render charts and tables via OpenUI 6. **Learn**: Write corrections and patterns to a file under `/memory/agent/` for future sessions This mirrors the six-layer context pattern described in [OpenAI’s data agent blog post](https://openai.com/index/inside-our-in-house-data-agent/) and implemented by [Dash](https://github.com/agno-agi/dash). ## Bundled Capabilities All [Bashkit Worker harness capabilities](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) plus: | Capability | What it provides | | -------------------- | --------------------------------------------------------------------------------------------------------- | | Session SQL Database | `sql_execute`, `sql_query`, `sql_schema`, session-scoped SQLite databases that auto-create on first write | | OpenUI | Rich interactive charts, tables, dashboards, and KPI cards rendered inline in chat | | Todo List | `write_todos`, track multi-step analysis tasks | | Data Knowledge | Mounts `/knowledge/` scaffold with directories for table docs, business rules, and validated SQL patterns | ## Knowledge Files The harness mounts a `/knowledge/` directory scaffold in every session:
```plaintext
/knowledge/
index.md
tables/index.md # Add one .md per table: columns, types, gotchas
business/index.md # Add metric definitions, business rules, domain terms
queries/index.md # Add validated .sql files as reusable templates
```
These files are read-only scaffolds. Populate them with your organization’s curated knowledge to ground the agent’s SQL generation in reality. The agent reads these files before writing any SQL query. Combined with [agent memory](https://everruns.com/docs/features/memory-scopes/), which the server mounts at `/memory/agent` in every session of the agent and which the agent edits with its file tools, this implements the layered context pattern: | Layer | Source | | ----------------------- | ---------------------------------------- | | Table usage & schema | `sql_schema` tool + `/knowledge/tables/` | | Business annotations | `/knowledge/business/` + AGENTS.md | | Validated queries | `/knowledge/queries/` | | Institutional knowledge | MCP servers (Slack, Notion, Confluence) | | Learning memory | Files under `/memory/agent/` | | Runtime context | `sql_query` / `sql_execute` | ## Example Session
```plaintext
User: Load this CSV and tell me which product category has the highest revenue
Agent: [reads /memory/agent/] [inspects any existing schema]
[creates table, imports data]
[runs SELECT category, SUM(revenue) ... GROUP BY category]
[validates: 5 categories, no NULLs, totals match]
[renders bar chart via OpenUI]
[appends to /memory/agent/corrections.md: "revenue is net of refunds"]
```
## See Also * [Bashkit Worker Harness](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/), the parent harness this extends * [Capabilities overview](https://everruns.com/docs/features/capabilities/), full capability catalog including memory and OpenUI * [Harnesses feature guide](https://everruns.com/docs/features/harnesses/), harness selection and API management
---
# Generic Harness (deprecated)
> The default harness, bundling core capabilities for general-purpose agent sessions.
Source:
The **Generic** harness is deprecated. Existing agents, sessions and child harnesses retain its legacy behavior. Choose [Conversation](https://everruns.com/docs/built-ins/harnesses/conversation/) for dialogue, [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) for files, skills and delegation, or [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) or [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) for a shell. Generic is not an alias for Worker. It configures 24 capabilities. Together they cover file operations, command execution, web access, memory, budgeting, context management, durable tool output, citations, and runtime safeguards. ## Legacy use * General-purpose assistants * Coding and scripting tasks * Research workflows * Any session where you want a solid set of defaults ## Configuration | Property | Value | | ----------------- | ------------------------------------------------------------- | | **Type** | `generic` | | **System Prompt** | Instruction hierarchy only; the agent’s own prompt follows it | | **Default Model** | None (inherits from agent or organization) | ## Bundled Capabilities | Capability | What it provides | | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [File System](https://everruns.com/docs/capabilities/file-system/) | Read, write, edit, list, grep, stat, and delete files in the session workspace (`/workspace`) | | [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/) | Sandboxed bash shell for running commands, scripts, and text processing | | [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/) | Fetch web content with file download support | | [Storage](https://everruns.com/docs/capabilities/session-storage/) | Key/value store for general data and encrypted secret storage | | [Session](https://everruns.com/docs/capabilities/session/) | Access session metadata and manage session title | | [Session Schedules](https://everruns.com/docs/capabilities/session-schedules/) | Create and manage cron-style schedules that wake the session | | [AGENTS.md](https://everruns.com/docs/capabilities/agent-instructions/) | Reads AGENTS.md from workspace and injects project-level instructions | | [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/) | Discover and activate skills from `/.agents/skills/` | | [Auto Tool Search](https://everruns.com/docs/capabilities/tool-search/#auto-tool-search) | Defers tool schema loading to reduce prompt size, using the provider’s native tool search where available | | [Context Compaction](https://everruns.com/docs/advanced/compaction/) | Manages working context and durable continuity, including permitted `query_history` retrieval | | [Budgeting](https://everruns.com/docs/capabilities/budgeting/) | Budget awareness in the system prompt and a `check_budget` tool, which currently returns a placeholder; use the REST budget-check endpoint for detailed status | | [Self-Budget](https://everruns.com/docs/capabilities/self-budget/) | Prompt-only guidance for reasoning about a user-requested indicative budget using session usage data | | [Ask User](https://everruns.com/docs/capabilities/ask-user/) | Ask the user 1–4 structured questions, or collect a credential, and wait for the answer | | Soft Approval | Prompt-level gate asking permission before a destructive, irreversible, or outward-facing action | | Tool Output Persistence | Persists full tool output to `/.outputs/` before truncation for lossless retrieval | | Tool Output Distillation | Distills large tool output before it enters the context | | [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/) | Claim-level citations for answers drawn from retrieval feeds | | [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/) | Stamps faithfulness verdicts on citations (deterministic `heuristic` mode by default) | | [Parallel Tool Calls](https://everruns.com/docs/capabilities/parallel-tool-calls/) | Prefers parallel tool calls where the provider supports them | | [Message Metadata](https://everruns.com/docs/capabilities/message-metadata/) | Annotates messages with timestamps | | Human Intent | Adds model-authored intent narration to each tool call for UI rendering | | BTW | Ephemeral side-question command for the current session | | Tool Loop Detection | Detects repeated tool loops and injects a warning to break them | | Error Disclosure | Shows full provider error detail (`detailed` mode) | Context Compaction includes history retrieval through its compatibility dependency; no separate Infinity Context entry is needed. See [Context Compaction](https://everruns.com/docs/advanced/compaction/#worker-harness-defaults) for details. ## See Also * [Base Harness](https://everruns.com/docs/built-ins/harnesses/base/), minimal safeguards and context compaction * [Platform Chat Harness](https://everruns.com/docs/built-ins/harnesses/platform-chat/), focused operator chat built on Base * [Harnesses feature guide](https://everruns.com/docs/features/harnesses/), harness selection and API management
---
# Platform Chat
> The managed Agent for Everruns platform conversations, running on Bashkit Worker.
Source:
**Platform Chat** is a managed Agent that helps you operate your Everruns organization. It runs on [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/), which supplies a sealed, recoverable Bashkit virtual workspace. The Agent supplies its identity, instructions, platform access, introduction, conversation starters, and durable operator memory. Platform Chat is built in and read-only: you cannot edit, archive, or delete it from the UI or the API. Use **Copy** on its page to make an editable Agent from it. ## Main chat, side chats and threads The sidebar’s **Main chat** entry is your permanent conversation. It cannot be renamed, unpinned, archived, deleted, or reassigned. **Side chats +** opens a fresh conversation with the same Agent. Its session is created when you send the first message; it starts without copied conversation history or workspace files. Each side chat has its own transcript, workspace files and threads. **All chats** lists your side chats. Playground conversations and runs with other agents stay outside Chat; use Playground to test an Agent or harness. Every chat can hand longer work to a **thread**: a child conversation with a brief, a checklist and a worker. Chat tells you when it starts one. **Threads** in the conversation header opens the chat’s Threads panel on the right, grouped into Needs you, Working, Ready for review and Resolved; it opens by itself when a new thread starts. Click a thread to open it next to the chat, and steer it by telling the chat or replying in the thread. Threads belong to the chat that started them. ## Chat beside your pages The app has two layouts, and you pick one under **Layout** in the profile menu or on **Profile**. The choice is saved to your account, so it follows you to every device, browser and organization. * **Classic** (the default) keeps the left sidebar. Under **Chat in Classic** you choose how Chat opens: **Full screen** (the default) replaces the page; **Floating** shows a card over the page that you can move by its grip and resize from its top-left corner; **Docked** puts Chat in a column on the right of the page with a divider you can drag. **Command-J** (**Ctrl-J** on Windows and Linux) shows or hides Chat, and **Command-Shift-J** goes full screen. * **Chat first** keeps the conversation on the left of every page, with navigation in a rail on the right edge. The rail’s » opens the full sidebar, and system pages and Settings sit under one menu. In Chat first, and with floating or docked Chat in Classic, the conversation can see the page next to it. Drag the visible divider between them to resize, or double-click it to reset. Links in Chat’s replies open in the page pane, so the conversation stays put. **Main chat ▾** in the conversation header switches between Main chat and side chats; opening a thread shows it in the page pane, and the browser’s Back button returns to the page. **Full screen** in the conversation header (or **Command-Shift-J**) hides the page; **Show beside page** brings back the last page you were on. Nothing reloads when you switch, so streams and drafts survive. Command/Ctrl-J focuses the composer. Each message shares the current page’s identity with Chat. On an Agent page, Chat can read the live form, including unsaved instructions and configuration, and apply requested edits to that draft. Gold markers identify **Draft edited by Chat**. Review the result, then use **Save changes** to persist it or **Discard** to reset the draft. Draft **Undo** restores the preceding form values, including your earlier manual edits, and refuses to overwrite later manual edits. If you change the form while Chat is thinking, its stale patch fails so it can read the current draft again. Chat does not edit credentials or connection grants through this form; sandbox policy uses its dedicated editor. For separately requested saved-resource operations, Platform Chat still uses platform commands. Page context does not disable those operations, and a failed form edit is never permission to bypass review by saving directly. Supported resource saves attributed to the conversation receive saved-change review and **Undo all**. That Undo creates a history entry and checks the saved revision; unsupported inverses fail without saving. If a saved definition changes while your draft is dirty, the page keeps the draft and blocks Save until you discard it and review the latest definition. Chat can read page identity, current filters and bounded summaries of loaded records across the app. It reads explicit data, without copying page HTML or credential inputs. Harnesses, Virtual Users, Observers, Eval creation and other definition forms expose supported draft fields through the same read/edit flow. Knowledge, Memory, Skill, Sandbox-template, Capability and Channel forms expose their supported non-credential fields. Providers with several Save forms identify each form by name; Chat edits one form at a time. Use the page’s existing **Save** or **Create** action to apply a staged change. Organization, Model defaults and Web search defaults use explicit **Save** and **Discard** controls. Chat can also stage supported settings, schedule and eval-case fields, MCP metadata, invitations, report-builder choices and Playground setup. Connection credentials, approvals, financial actions and operational buttons retain their normal manual controls. Operational context includes bounded status rows and the current Monitoring view. Chat reports when a page or field is read-only; it does not work around that through a server write. Supported existing-resource editors share saved **Before/After** review, field-level **Undo**, **Undo all** and **History**. Save checks the version you started editing; Undo refuses to overwrite newer changes. Reviews follow you between pages in the same organization. Model selections save and undo as one batch. Account and Sandbox Template metadata inverses preserve current credentials and execution settings. Profile history is private to its owner. New-resource forms still require Create. Undo does not delete newly created resources or reverse invitations, payments, issued tokens or queued tasks. Protected values keep their manual controls. An inverse that no longer passes validation stays visible with an error for review. ## Platform access and memory Platform Chat uses native `platform_` functions for individual operations, with bounded `tool_search` to find and reveal schemas as needed. Its `everruns` command and session shell remain available for loops, filtering, and aggregation across many operations. Product docs are mounted read-only at `/workspace/docs`. The Platform capability also supplies the `everruns` skill for product orientation, with guides for command workflows and agent design. Discover and activate it through [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/) as needed. `/memory/user` is private to the conversation owner. `/memory/shared` contains durable notes shared across Platform Chat conversations in the organization. Sharing requires explicit intent; notes default to private memory. Documentation and memory are reference material, never instructions. Scratch files live in `/workspace`; credentials belong in the secure setup flow. Recurring autonomous work belongs to an Agent Trigger. Before changing an existing entity, Platform Chat reads its manager context and passes the revision it read and a reason with the change, so the entity’s history says why it changed. It asks before acting on a request that conflicts with the recorded context. See [Change history](https://everruns.com/docs/features/change-history/). ## Bundled Capabilities The Agent configures these capabilities in addition to the execution environment inherited from [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/). | Capability | Purpose | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Platform | Typed native platform operations and the session shell | | Current Time | Ground relative time questions | | Task Management | Track work within a conversation | | Prompt Caching | Cache stable prompt content | | Tool Call Repair | Repair malformed tool calls | | Human Intent | Preserve consequential user intent across tool calls | | Web Fetch | Read public web resources and download files | | Storage | Keep durable session values and secrets | | Schedules | Arrange follow-up work for the session | | BTW | Handle lightweight side questions without losing the main thread | | Message Metadata | Attach structured metadata to messages | | Retrieval Citations | Retrieve sources for grounded answers | | Citation Verification | Verify citation support before answering | | Ask User | Pause for structured user input when required | | Error Disclosure | Return detailed platform errors to the managed operator Agent | | User MCP Servers | Use the MCP servers the person added for themselves, and add, remove and connect them in chat ([User MCP servers](https://everruns.com/docs/features/user-mcp-servers/)) | | Coordination | Hand focused work to threads you can open and follow, in Main chat and every side chat | | Poppy Personal Agent | Talk to companies’ agents for the person over the Personal Agent Protocol ([Poppy Personal Agent](https://everruns.com/docs/capabilities/poppy-personal-agent/)) | | Tool Search | Discover native operations on demand with bounded schema disclosure ([Tool Search](https://everruns.com/docs/capabilities/tool-search/)) | | Image Generation | Draw images, animated GIFs and SVGs on the organization’s default image model ([Image Generation](https://everruns.com/docs/capabilities/image-generation/)) | ## Existing conversations The dedicated Platform Chat harness and its interim Generic binding are retired. Existing platform conversations move to the managed Agent on Bashkit Worker while keeping their IDs, history, workspace files, owners, and memory. Older custom agents, apps, triggers, and child harnesses retain their original execution bindings so their authored behavior is preserved; the retired harness remains stored for those bindings and historical accounting. The Agent name `platform-chat` is reserved for the managed assistant. An existing custom Agent with that name is renamed to `platform-chat-custom-`; its ID and bindings stay intact. Clients using its old name should switch to its ID. Conversation introductions and starters now belong exclusively to Agents. Existing harness presentation is copied to its assigned Agents when those Agent fields are empty. Harness presentation fields are deprecated and no longer accepted on writes.
---
# Sandbox Worker Harness
> Worker plus a full sandbox shell, for agents that need real processes, packages and builds.
Source:
**Sandbox Worker** extends [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) and requires a full sandbox: a container or a managed provider such as Daytona, E2B or Modal. The Agent’s Sandbox policy chooses which one. | | | | ------------------- | ----------------------------------------------------------- | | **Name** | `sandbox-worker` | | **Parent** | `worker` | | **Sandbox policy** | Required; must name a container or managed Sandbox Template | | **Primary Sandbox** | Whatever the Agent’s policy selects | Use it for coding agents, data work that installs packages, browser automation and long builds. The [Coding](https://everruns.com/docs/how-to/customize-a-harness/) harness example builds on it. Sandbox Worker never falls back to Bashkit: * Saving an Agent whose Sandbox policy can only resolve to Bashkit is rejected. * An Agent with no Sandbox policy saves, but starting a Session on it fails with a message that names the missing policy. Choose [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) for a virtual shell that needs no provider. Custom Harnesses that inherit from Sandbox Worker inherit the requirement too. Sandbox Worker is a Platform harness. In the Framework, express the same need as an Environment requirement on your harness and bind an Environment that provides it. See [Sandbox Templates](https://everruns.com/docs/features/sandbox-templates/) for configuring providers.
---
# Worker Harness
> The worker kit with no compute, for agents that work through tools, MCP servers and files.
Source:
Worker inherits [Base](https://everruns.com/docs/built-ins/harnesses/base/) and adds everything a working agent needs except a shell: session files, project instructions (`AGENTS.md`), session tools, durable and distilled tool output, skills, history retrieval, automatic tool discovery, budget awareness, todo lists, subagents, task controls, [Web Search](https://everruns.com/docs/capabilities/web-search/) on the organization’s default provider, and [Image Generation](https://everruns.com/docs/capabilities/image-generation/) on the organization’s default image model. It runs no code. Choose it for agents that act through tools and MCP servers: triage and integration agents over Linear, Slack or GitHub, research agents over knowledge and files, and organizations that want no code execution at all. It needs no sandbox provider. Worker is also the parent of the two shell workers: * [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) adds the Bashkit virtual shell. * [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) adds a full sandbox. An Agent on Worker may still set a Sandbox policy; the selected Sandbox Template then supplies the shell. Pick one of the shell workers when the agent always needs one. Subagents create separate child sessions. Ordinary children inherit the parent configuration; blueprints provide specialist behavior. Depth and root-tree task limits bound delegation. Assigning this harness requires permission to assign its high-risk capabilities. Web fetch, secret/KV tools, organization memory mounts and session scheduling remain opt-in. Recurring agent execution is configured with Agent Triggers. Choose `worker` with the API’s `harness_name` or the CLI’s `--harness` option.
```rust
let harness = everruns::Harness::worker();
```
Framework constructors load the same capability data as the hosted presets. Enable the host integrations required by the tools you use; a preset does not compile optional integrations into your application. Delegation also needs a host with subagent and task backends. The default in-memory framework host does not supply these services; unregistered capability references remain inert. See [Harnesses](https://everruns.com/docs/features/harnesses/) for selection and inheritance.
---
# Worker Base Harness (deprecated)
> Retired level kept for existing agents; new agents choose Worker, Bashkit Worker or Sandbox Worker.
Source:
**Worker Base** was the middle of the old single chain (Base, Conversation, Worker Base, Worker). The [harness tree](https://everruns.com/docs/features/harnesses/#built-in-harnesses) replaced it: its files and project instructions moved into [Worker](https://everruns.com/docs/built-ins/harnesses/worker/), and its shell moved into [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) and [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/). The row stays active and managed, with its name, ID, parent (Conversation) and capabilities unchanged, so agents, sessions and adopted harness examples bound to it keep working. Selectors hide it until you choose Show deprecated. | Instead of Worker Base | Choose | | --------------------------- | ------------------------------------------------------------------------------- | | Files and bash, no provider | [Bashkit Worker](https://everruns.com/docs/built-ins/harnesses/bashkit-worker/) | | Files and a real machine | [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) | | Files and tools, no shell | [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) | In the Framework, `Harness::worker_base()` is deprecated and returns `Harness::bashkit_worker()`.
---
# Read Tools
> Parameters, pagination, content-type defaults, and exec output retrieval for the read-category tools.
Source:
Agents spend most of their context window on tool results. A single `cat` of a large file can consume thousands of tokens that crowd out reasoning space. The read-category tools are built to return the part the agent asked for and nothing else. Three tools form the read category: | Tool | Purpose | | ---------------- | ---------------------------------------------------------------------------------- | | `read_file` | Read file content with offset/limit pagination and line numbers | | `grep_files` | Search file contents by regex — returns matching lines with paths and line numbers | | `list_directory` | List files and directories with metadata (size, type) | Together they implement a **search → locate → read** workflow: `grep_files` finds where something is, `read_file` reads the relevant section, and `list_directory` provides structural context. ## read_file ### Parameters | Parameter | Type | Default | Description | | --------- | ------- | ------------ | --------------------------------------------------- | | `path` | string | *(required)* | Absolute file path (e.g., `/workspace/src/main.rs`) | | `offset` | integer | 0 | Starting line number (0-indexed) | | `limit` | integer | 2000 | Maximum lines to return | ### Response
```json
{
"path": "/workspace/src/main.rs",
"content": "1|use std::io;\n2|use serde::Serialize;\n3|\n4|fn main() {\n...",
"total_lines": 450,
"lines_shown": { "start": 1, "end": 450 },
"truncated": false,
"content_type": "source",
"read_mode": "offset",
"size_bytes": 12480,
"content_hash": "sha256:a1b2c3..."
}
```
Key response fields: * **`content`** — Line-numbered output in compact `N|content` format. The `N|` prefix uses minimal bytes while giving agents precise line references for edits. * **`total_lines`** — Total lines in the file. Use this to know if more content exists beyond the current window. * **`lines_shown`** — 1-based start/end of the returned window. * **`truncated`** — `true` if more content exists beyond the returned window. * **`content_type`** — Detected content type (e.g., `log`, `csv`, `minified`, `source`). Reflects the heuristic applied. * **`read_mode`** — `tail` when reading log files from the end; `offset` otherwise. * **`content_hash`** — SHA-256 hash of the file content, used by `edit_file` for compare-and-set safety. ### Content-Type Defaults When the agent doesn’t specify `offset` or `limit`, `read_file` adjusts defaults based on file extension: | Content Type | Extensions | Default Limit | Read Mode | Rationale | | ------------ | --------------------------------- | ------------- | ------------------- | ------------------------------------------------------ | | Source code | `.rs`, `.ts`, `.js`, `.py`, etc. | 2000 lines | From offset | Standard — agent usually needs context around a region | | Log files | `.log`, `.out` | 500 lines | **From end (tail)** | Errors cluster at the end — recent output matters most | | CSV/TSV data | `.csv`, `.tsv` | 100 lines | From offset | Schema + sample rows; header always included | | Config | `.json`, `.yaml`, `.yml`, `.toml` | 2000 lines | From offset | Usually need full structure | | Minified | `.min.js`, `.min.css` | 20 lines | From offset | Single-line files would blow token budgets | | Text | `.md`, `.txt`, `.rst` | 2000 lines | From offset | Standard | **Explicit parameters override only the defaults they control.** An explicit `limit` overrides the content-type default limit. An explicit `offset` does **not** change the default limit by itself; it only controls where reading starts, and for log files it disables the default tail-biased read mode in favor of reading from that offset. If both `offset` and `limit` are provided, both behaviors are explicitly controlled. For CSV files, the header row (line 1) is always included in the response, even when reading with an offset. This ensures the agent always has column names for context. ### Image and Binary Handling * **Images** (`.png`, `.jpg`, `.gif`, `.webp`) are returned as **native image content blocks**, not text. The agent sees the image directly. * **Binary files** (base64-encoded) are returned with `"encoding": "base64"` and no line formatting. * A **hard byte cap** (50 KB) acts as a safety net for pathological files like minified bundles. ## Pagination For files larger than the default window, page through with `offset` and `limit`:
```json
// First read — gets lines 1-2000
{ "path": "/workspace/big_file.rs" }
// Response shows total_lines: 5000, truncated: true
// Continue reading:
{ "path": "/workspace/big_file.rs", "offset": 2000, "limit": 2000 }
// Gets lines 2001-4000. Continue until truncated: false.
```
The 2000-line default covers most source files entirely in a single read. For the rare cases where files are larger, the `total_lines` field tells the agent exactly how much remains. ## Keeping read results small The system prompt guides agents toward efficient reading patterns: 1. **Search before read** — Use `grep_files` to find relevant lines, then `read_file` with a targeted `offset` around the match. This avoids reading thousands of irrelevant lines. 2. **Don’t re-read** — Files already in conversation context don’t need to be read again. The agent should reference prior reads. 3. **Check `total_lines`** — When a read is truncated, the agent knows how much remains and can decide whether to continue or search within the unread portion. 4. **Use offset to continue** — After a truncated read, use `offset` to pick up where the previous read left off. ## Exec Output as Readable Files When sandbox tools (`bash`, `daytona_exec`, `e2b_exec`, etc.) produce output, the inline result is truncated based on the `output` verbosity parameter (default: `concise` \~2 KiB). But the **full output is always persisted** to the session filesystem. ### How It Works The `tool_output_persistence` capability (included in the Generic harness) writes full output before truncation: * **stdout** → `/.outputs/{tool_call_id}.stdout` * **stderr** → `/.outputs/{tool_call_id}.stderr` The truncated inline result includes metadata pointing to the persisted files:
```json
{
"stdout": "[truncated to 2 KiB — full output saved]",
"stderr": "",
"exit_code": 0,
"success": true,
"full_output": "/.outputs/call_abc123.stdout",
"total_lines": 8450,
"output_files": [
"/.outputs/call_abc123.stdout",
"/.outputs/call_abc123.stderr"
]
}
```
The agent can then `read_file` the persisted output selectively:
```json
// Read last 100 lines of build output
{ "path": "/.outputs/call_abc123.stdout", "offset": 8350, "limit": 100 }
```
### Priority-Aware Truncation When output is truncated, the system preserves error-relevant content. Lines matching error patterns (`error`, `Error`, `FAILED`, `panicked`, stack traces) are prioritized over noise like `Compiling...` or `Downloading...`. This means the inline 2 KiB concise output is more likely to contain the diagnostically useful parts. ### Output Verbosity Modes All exec tools accept an `output` parameter: | Mode | Budget | Use case | | --------- | --------- | ---------------------------------- | | `silent` | \~200 B | Fire-and-forget commands | | `concise` | \~2 KiB | Builds, installs (**default**) | | `normal` | \~8 KiB | General debugging | | `verbose` | \~16 KiB | Test failures, error investigation | | `full` | unlimited | When the agent needs every line | ## Content Hash and Edit Safety Every `read_file` response includes a `content_hash` (SHA-256). The `edit_file` tool requires this hash via its `expected_hash` parameter — if the file has changed since the read, the edit is rejected. This **compare-and-set** mechanism prevents stale edits in long conversations where the agent may have read a file many turns ago and the file has since been modified (by another tool call or external process).
```json
// read_file returns content_hash
{ "content_hash": "sha256:a1b2c3..." }
// edit_file uses it as expected_hash — rejected if file changed
{
"path": "/workspace/src/main.rs",
"expected_hash": "sha256:a1b2c3...",
"old_text": "fn main() {",
"new_text": "fn main() -> Result<()> {"
}
```
If an edit is rejected due to a stale hash, the agent should re-read the file to get the current content and hash, then retry the edit. ## Structural Outlines When `read_file` returns a truncated result, the response includes a **structural outline** of the unread portions — function/class/method signatures without bodies. The agent can orient itself in any file with a single partial read.
```plaintext
1|use std::collections::HashMap;
2|use serde::Serialize;
... (lines read normally) ...
100| let result = process(&input);
--- Outline of lines 101-500 (not shown) ---
// L105: fn process(input: &Input) -> Result { ... }
// L180: fn validate(output: &Output) -> bool { ... }
// L220: struct Config { ... }
// L235: impl Config { ... }
// L236: fn load(path: &str) -> Result { ... }
// L270: fn merge(&mut self, other: &Config) { ... }
// L310: #[cfg(test)] mod tests { ... }
```
### Supported Languages | Language | Extensions | | ---------- | ----------------------------- | | Rust | `.rs` | | TypeScript | `.ts`, `.tsx`, `.mts` | | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | | Python | `.py` | ### What Gets Outlined * **Functions/methods** — name, parameters, return type * **Structs/classes/enums** — name * **Impl blocks / trait implementations** — with nested methods * **Modules** — including `#[cfg(test)]` detection * **Interfaces and type aliases** (TypeScript) For unsupported languages, no outline is generated — the response still works, just without structural context for unread portions.
---
# Capabilities Overview
> Capabilities give an agent tools, system prompt fragments, and execution features. Index of every built-in capability.
Source:
Capabilities are modular units that extend what an agent can do. Each capability can contribute: * **Tools**: callable functions the agent can invoke during conversations * **System prompt additions**: context and instructions prepended to the agent’s prompt * **Features**: UI elements unlocked when the capability is active (e.g., the Files tab) Agents compose capabilities; enable only what you need. ## Capability Reference Every capability a production deployment offers, with the number of tools it adds by default. Rows marked **dev-only** are registered only at the `dev` deployment grade. A `FEATURE_*` variable identifies a [rollout grade override](https://everruns.com/docs/sre/environment-variables/#feature-rollout-grades); organisation enrolment also applies before assigning or using gated capabilities. ### Core Fundamental capabilities for file operations, command execution, web access, session management, time awareness, task tracking, scheduling, and agent coordination. | Capability | ID | Tools | | ---------------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------- | | [File System](https://everruns.com/docs/capabilities/file-system/) | `session_file_system` | 10 | | [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/) | `bashkit_shell` | 1 | | [Shell Code Mode](https://everruns.com/docs/capabilities/shell-code-mode/) | `shell_code_mode` | 1 (`tools`, hidden from the model; it is the shell command) | | [Host Shell](https://everruns.com/docs/capabilities/host-shell/) | `host_shell` | 1 (Framework-only) | | [Session](https://everruns.com/docs/capabilities/session/) | `session` | 2 | | [Automatic session titles](https://everruns.com/docs/capabilities/automatic-session-titles/) | `automatic_session_titles` | 0 | | Reactions | `reactions` | 1 | | [Storage](https://everruns.com/docs/capabilities/session-storage/) | `session_storage` | 2 | | [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/) | `web_fetch` | 1 | | [Web Search](https://everruns.com/docs/capabilities/web-search/) | `web_search` | 1 | | [Current Time](https://everruns.com/docs/capabilities/current-time/) | `current_time` | 1 | | [Message Metadata](https://everruns.com/docs/capabilities/message-metadata/) | `message_metadata` | 0 | | [Ask User](https://everruns.com/docs/capabilities/ask-user/) | `ask_user` | 1 | | [Task Management](https://everruns.com/docs/capabilities/task-management/) | `stateless_todo_list` | 2 | | [Schedules](https://everruns.com/docs/capabilities/session-schedules/) | `session_schedule` | 3 | | [Auto-Continue After Usage Limit](https://everruns.com/docs/capabilities/usage-limit-auto-continue/) | `usage_limit_auto_continue` | 0 | | [AGENTS.md](https://everruns.com/docs/capabilities/agent-instructions/) | `agent_instructions` | 0 | | [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/) | `skills` | 2; `FEATURE_SKILLS` grade | | Channel Thread Context | `channel_context` | 0 | | System Commands | `system_commands` | 0 | ### Orchestration Delegating work to other sessions and running it in the background. | Capability | ID | Tools | | ------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------- | | [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/) | `subagents` | 0 (contributes the `spawn_agent` delegation target) | | Session Tasks | `session_tasks` | 5 | | Background Execution | `background_execution` | 1 | | [Agents](https://everruns.com/docs/capabilities/agent-handoff/) | `agent_handoff` | 2 (and contributes the `agent` `spawn_agent` target) | | Run conversation | `run_conversation` | 2 (added to every agent a run hands work to) | | [A2A Agent Delegation](https://everruns.com/docs/capabilities/a2a-agent-delegation/) | `a2a_agent_delegation` | 0 (contributes the `external_a2a` `spawn_agent` target) | | AG-UI Agent Delegation | `ag_ui_delegation` | 0 (contributes the `external_ag_ui` `spawn_agent` target) | | [Coordination](https://everruns.com/docs/framework/coordination/) | `coordination` | 5 | ### Sandboxes Cloud and container sandbox environments for isolated code execution. | Capability | ID | Tools | | -------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------- | | Managed Environment | `session_sandbox` | 8 | | [Sandbox Desktop](https://everruns.com/docs/capabilities/computer-use/#desktop-in-a-sandbox) | `sandbox_desktop` | 1 (added by a Sandbox Template with a desktop) | | [Sandbox Fleet](https://everruns.com/docs/capabilities/sandbox-fleet/) | `sandbox_fleet` | 8 | | [Daytona](https://everruns.com/docs/capabilities/daytona/) | `daytona` | 10 | | [E2B](https://everruns.com/docs/capabilities/e2b/) | `e2b` | 6 | | [Modal](https://everruns.com/docs/integrations/modal/) | `modal` | 8 | | [boxd](https://everruns.com/docs/integrations/boxd/) | `boxd` | 6 | | [Container Sandbox](https://everruns.com/docs/capabilities/container-sandbox/) | `container_sandbox` | 8 (needs `FEATURE_CONTAINER_SANDBOX=prod`) | ### Code navigation Editor-grade understanding of the code in a session’s sandbox. | Capability | ID | Tools | | ------------------------------------------------------------------------------------------------- | ---------- | ----- | | [Language Server (LSP)](https://everruns.com/docs/capabilities/code-navigation/#language-servers) | `lsp` | 7 | | [AST Grep](https://everruns.com/docs/capabilities/code-navigation/#structural-search) | `ast_grep` | 1 | | [AST Edit](https://everruns.com/docs/capabilities/code-navigation/#structural-edit) | `ast_edit` | 1 | | [Repo Map](https://everruns.com/docs/capabilities/code-navigation/#repository-map) | `repo_map` | 2 | ### Browser Browser automation and web interaction capabilities. | Capability | ID | Tools | | -------------------------------------------------------------------- | -------------- | ------------------------- | | [Browserless](https://everruns.com/docs/capabilities/browserless/) | `browserless` | 9 | | [Browser Use](https://everruns.com/docs/capabilities/browser-use/) | `browser_use` | 1; Browserless connection | | [Computer Use](https://everruns.com/docs/capabilities/computer-use/) | `computer_use` | 1; Browserless connection | ### Data and knowledge Structured data, knowledge retrieval, and memory. | Capability | ID | Tools | | -------------------------------------------------------------------------------------- | ----------------------- | ---------------------------- | | [SQL Database](https://everruns.com/docs/capabilities/sql-database/) | `session_sql_database` | 3 | | [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/) | `citation_retrieval` | 0 | | [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/) | `citation_verification` | 0 | | [Web Citations](https://everruns.com/docs/capabilities/citation-web/) | `citation_web` | 0 | | [Data Knowledge](https://everruns.com/docs/capabilities/data-knowledge/) | `data_knowledge` | 0 | | [Knowledge](https://everruns.com/docs/capabilities/knowledge/) | `knowledge` | 2; `FEATURE_KNOWLEDGE` grade | | [Memory](https://everruns.com/docs/capabilities/memory/) | `memory` | 0; `FEATURE_MEMORY` grade | ### Media Image generation and editing: stills, animated GIFs and SVGs. | Capability | ID | Tools | | ---------------------------------------------------------------------------- | ------------------ | ----- | | [Image Generation](https://everruns.com/docs/capabilities/image-generation/) | `image_generation` | 2 | ### Models and provider tools Provider-executed tools and model selection. | Capability | ID | Tools | | ------------------------------------------------------------------------------------------ | ------------------------- | ----- | | [OpenAI Server Tools](https://everruns.com/docs/capabilities/openai-server-tools/) | `openai_server_tools` | 0 | | [OpenRouter Server Tools](https://everruns.com/docs/capabilities/openrouter-server-tools/) | `openrouter_server_tools` | 0 | | Model Scout | `model_scout` | 0 | | OpenRouter Workspace | `openrouter_workspace` | 2 | ### Integrations External-service capabilities and blueprint-backed workflows. | Capability | ID | Tools | | ------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------- | | [GitHub](https://everruns.com/docs/capabilities/github/) | `github` | 6 (7 with `allow_pull_requests`, 2 more with `allow_merge`) | | [GitHub Scout](https://everruns.com/docs/capabilities/github-scout/) | `github_scout` | 0 | | [Repositories](https://everruns.com/docs/capabilities/repositories/) | `repositories` | 3 (4 with a writable repository) | | [Slack](https://everruns.com/docs/capabilities/slack/) | `slack` | 4 | | Cursor | `cursor` | 9 | | [Agentic Resource Discovery](https://everruns.com/docs/integrations/ard/) | `resource_discovery` | 3 | | [AgentID Sign-In](https://everruns.com/docs/integrations/agentid/) | `agentid` | 1 | | [Brave Search](https://everruns.com/docs/integrations/brave-search/) | `brave_search` | 1 | | [DuckDuckGo](https://everruns.com/docs/integrations/duckduckgo/) | `duckduckgo` | 1 | | [Parallel Search and Fetch](https://everruns.com/docs/integrations/parallel/) | `parallel_search` | 0 (hosted MCP tools from Parallel: search, fetch, decisions, image search) | | [Jev Decisions](https://everruns.com/docs/integrations/typesafe/) | `jev` | 1 | | [User MCP Servers](https://everruns.com/docs/capabilities/user-mcp-servers/) | `user_mcp` | 7 (only with `manage` on) | | [Poppy Personal Agent](https://everruns.com/docs/capabilities/poppy-personal-agent/) | `poppy_client` | 5 | ### Platform Agent self-management and platform control. | Capability | ID | Tools | | ------------------------------------------------------------ | ---------- | ----- | | [Platform](https://everruns.com/docs/capabilities/platform/) | `platform` | 3 | ### Generative UI Structured UI the agent renders in the chat. | Capability | ID | Tools | | ---------- | -------- | ----- | | OpenUI | `openui` | 0 | | A2UI | `a2ui` | 0 | ### Optimization Performance and cost optimization for LLM interactions. | Capability | ID | Tools | | ---------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------- | | [Infinity Context](https://everruns.com/docs/capabilities/infinity-context/) | `infinity_context` (deprecated) | 1 | | [Context Compaction](https://everruns.com/docs/advanced/compaction/) | `compaction` | 0 | | [Dreaming](https://everruns.com/docs/features/dreaming/) | `dreaming` | 0 | | [Auto Tool Search](https://everruns.com/docs/capabilities/tool-search/#auto-tool-search) | `auto_tool_search` | 0 (adds `tool_search` on models without native tool search) | | [OpenAI Tool Search](https://everruns.com/docs/capabilities/tool-search/#hosted-openai) | `openai_tool_search` | 0 | | [Claude Tool Search](https://everruns.com/docs/capabilities/tool-search/#hosted-claude) | `claude_tool_search` | 0 | | [Tool Search](https://everruns.com/docs/capabilities/tool-search/#client-side) | `tool_search` | 1 | | [Budgeting](https://everruns.com/docs/capabilities/budgeting/) | `budgeting` | 1 | | [Self-Budget](https://everruns.com/docs/capabilities/self-budget/) | `self_budget` | 0 | | [Parallel Tool Calls](https://everruns.com/docs/capabilities/parallel-tool-calls/) | `parallel_tool_calls` | 0 | | Native Async Tools | `native_async_tools` | 0 | | [Prompt Caching](https://everruns.com/docs/capabilities/prompt-caching/) | `prompt_caching` | 0 | | [Claude Message Threads](https://everruns.com/docs/capabilities/claude-message-threads/) | `claude_message_threads` | 0 | ### Safety Streaming-output guardrails and runtime safety nets. | Capability | ID | Tools | | ------------------------------------------------------------------------------------------ | ------------------------- | ----- | | [Prompt Canary Guardrail](https://everruns.com/docs/capabilities/prompt-canary-guardrail/) | `prompt_canary_guardrail` | 0 | | [Tool Call Repair](https://everruns.com/docs/capabilities/tool-call-repair/) | `tool_call_repair` | 0 | | [Output Truncation](https://everruns.com/docs/capabilities/output-truncation/) | `output_truncation` | 0 | | [Guardrails](https://everruns.com/docs/capabilities/guardrails/) | `guardrails` | 0 | | [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) | `tool_approval` | 0 | | [Dry Run](https://everruns.com/docs/capabilities/dry-run/) | `dry_run` | 0 | | Progress Guard | `progress_guard` | 0 | | [Soft Approval](https://everruns.com/docs/capabilities/soft-approval/) | `soft_approval` | 3 | | [Tool Loop Detection](https://everruns.com/docs/capabilities/loop-detection/) | `loop_detection` | 0 | The [`guardrails`](https://everruns.com/docs/capabilities/guardrails/) capability runs config-driven checks over model output and tool activity, blocking or logging per check. Checks can be deterministic (regex, blocklist, tool-call patterns) or model-backed, an `llm_judge` policy or a `moderation` decision, plus delegation to an external guardrail over scoped MCP. Each check binds a rule to a stage (`output`, `tool_use`, `tool_output`) with an `on_fail` of `block` or `log`; model-backed and MCP checks send a bounded excerpt off the sync path and fail open. Use advisory mode and the `POST /v1/capabilities/guardrails/dry-run` endpoint to tune against false positives before enforcing. For ready-made starting points, list the gallery at `GET /v1/capabilities/guardrails/examples`, each preset carries a `data_egress` signal (`none` vs. `utility_llm`), and drop a preset’s `config` into the agent’s `guardrails` capability config. ### Automation Run shell commands at lifecycle and tool events. Block, mutate, or audit agent actions from outside the model. | Capability | ID | Tools | | ---------------------------------------------------------------- | ------------ | ----- | | [User Hooks](https://everruns.com/docs/capabilities/user-hooks/) | `user_hooks` | 0 | Harnesses also compose capabilities that are settings rather than features: Human Intent, BTW, Error Disclosure, and Tool Output Persistence and Distillation. The canonical [harness levels](https://everruns.com/docs/features/harnesses/) and [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) harness pages describe them. ## Quick Start ### Enable via API
```bash
curl -X POST http://localhost:9300/api/v1/agents \
-H "Content-Type: application/json" \
-d '{
"name": "My Agent",
"system_prompt": "You are a helpful assistant.",
"capabilities": ["session_file_system", "bashkit_shell", "web_fetch"]
}'
```
### Enable via UI 1. Navigate to the Agent detail page 2. Open the **Capabilities** section 3. Toggle capabilities on/off 4. Reorder with drag handles (order affects system prompt priority) 5. Save ### List available capabilities
```bash
curl http://localhost:9300/api/v1/capabilities
```
### Create a declarative capability Declarative capabilities are persisted capability definitions made from data: system prompt text, scoped MCP servers, text file mounts, and skill packages. They use a public resource ID like `cap_...` and a stable capability reference like `declarative:research_pack`.
```bash
curl -X POST http://localhost:9300/api/v1/capabilities \
-H "Content-Type: application/json" \
-d '{
"definition": {
"name": "research_pack",
"display_name": "Research Pack",
"description": "Default research behavior and resources.",
"system_prompt": "Prefer primary sources and cite them clearly.",
"risk_level": "low"
}
}'
```
Agents and harnesses can use the canonical reference:
```json
{ "ref": "declarative:research_pack" }
```
For convenience, agent and harness write APIs also accept the plain unique name when it matches a declarative capability:
```json
{ "ref": "research_pack" }
```
## Key Concepts ### Dependencies Some capabilities depend on others. Dependencies are resolved automatically at runtime, you don’t need to manually add them. | Capability | Depends On | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Context Compaction](https://everruns.com/docs/advanced/compaction/) | [Infinity Context](https://everruns.com/docs/capabilities/infinity-context/) (history retrieval included automatically) | | [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [Shell Code Mode](https://everruns.com/docs/capabilities/shell-code-mode/) | [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/) | | [Host Shell](https://everruns.com/docs/capabilities/host-shell/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [Platform](https://everruns.com/docs/capabilities/platform/) | [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/), [File System](https://everruns.com/docs/capabilities/file-system/) (when embedded docs are enabled) | | [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [GitHub Scout](https://everruns.com/docs/capabilities/github-scout/) | [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/) | | Managed Environment | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Sandbox Desktop](https://everruns.com/docs/capabilities/computer-use/#desktop-in-a-sandbox) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Sandbox Fleet](https://everruns.com/docs/capabilities/sandbox-fleet/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [E2B](https://everruns.com/docs/capabilities/e2b/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Modal](https://everruns.com/docs/integrations/modal/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [boxd](https://everruns.com/docs/integrations/boxd/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Daytona](https://everruns.com/docs/capabilities/daytona/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Browserless](https://everruns.com/docs/capabilities/browserless/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Browser Use](https://everruns.com/docs/capabilities/browser-use/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Computer Use](https://everruns.com/docs/capabilities/computer-use/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [Data Knowledge](https://everruns.com/docs/capabilities/data-knowledge/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [Knowledge](https://everruns.com/docs/capabilities/knowledge/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [Memory](https://everruns.com/docs/capabilities/memory/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [Dreaming](https://everruns.com/docs/features/dreaming/) | [File System](https://everruns.com/docs/capabilities/file-system/) | | [Container Sandbox](https://everruns.com/docs/capabilities/container-sandbox/) | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | [A2A Agent Delegation](https://everruns.com/docs/capabilities/a2a-agent-delegation/) | Session Tasks | | AG-UI Agent Delegation | Session Tasks | ### Features Capabilities declare UI features they contribute. The session aggregates features from all active capabilities to decide which UI tabs to render. | Feature | UI Element | Contributed By | | -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `file_system` | Files tab, filesystem | [File System](https://everruns.com/docs/capabilities/file-system/), [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), [Host Shell](https://everruns.com/docs/capabilities/host-shell/) | | `secrets` | Files tab, key values | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | `key_value` | Files tab, key values | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | `schedules` | Files tab and Work tab | [Schedules](https://everruns.com/docs/capabilities/session-schedules/) | | `sql_database` | Database tab | [SQL Database](https://everruns.com/docs/capabilities/sql-database/) | | `subagents` | Subagents tab | [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/) | | `citations` | Inline citation chips + Sources strip | [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/), [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/) | ### Ordering Capabilities are applied in the order configured on the agent. Earlier capabilities’ system prompt additions appear first. Place the most important context-setting capabilities first. ## See Also * [Concepts](https://everruns.com/docs/getting-started/concepts/), how capabilities fit into the Harness → Agent → Session model * [API Reference](https://everruns.com/docs/api/), full API documentation * [MCP Servers](https://everruns.com/docs/features/mcp/), external tool servers as virtual capabilities
---
# A2A Agent Delegation
> Delegate work to configured external agents over the A2A protocol through spawn_agent, in the foreground or as a background session task.
Source:
| | | | ---------------- | ---------------------- | | **ID** | `a2a_agent_delegation` | | **Category** | Orchestration | | **Features** | `agent_runs` | | **Dependencies** | `session_tasks` | | **Risk** | High | | **Availability** | Experimental | A2A Agent Delegation lets an agent hand work to agents that run outside Everruns and speak the [A2A protocol](https://everruns.com/docs/features/a2a/). The agents it may call are listed in the capability’s configuration, so the model can only reach URLs you configured. The capability adds the `external_a2a` target type to the shared `spawn_agent` tool, the same dispatcher that [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/) and [Agent Handoff](https://everruns.com/docs/capabilities/agent-handoff/) extend. **Experimental.** On the platform, adding the capability to an agent is the opt-in; there is no separate feature flag. In the [Framework](https://everruns.com/docs/framework/), turn on the `a2a` Cargo feature of `everruns` (it implies `local`) and add the capability by ID. See [A2A](https://everruns.com/docs/features/a2a/#a2a-in-the-framework). ## Configuration
```json
{
"ref": "a2a_agent_delegation",
"config": {
"agents": [
{
"id": "research",
"name": "Research agent",
"description": "Researches a topic and returns notes.",
"base_url": "https://agents.example.com/research"
}
]
}
}
```
| Field | Required | Description | | ------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Yes | Stable key the model passes as `target.id` | | `name` | Yes | Human-readable name, shown in the system prompt | | `description` | No | What the agent does, shown in the system prompt | | `base_url` | One of `base_url` or `agent_card` | Where the Agent Card is fetched from (`/.well-known/agent-card.json`) | | `agent_card` | One of `base_url` or `agent_card` | An inline Agent Card, used instead of discovery | | `headers` | No | Static headers sent to the A2A endpoint. They are stored in the config, so they must not hold secrets | | `preferred_binding` | No | `JSONRPC` or `HTTP+JSON` | | `poll_interval_ms` | No | How often to poll the remote task, 100 to 60000. Default 1000 | | `allow_local_urls` | No | Allows localhost and private addresses for local development. Honored only when `DEPLOYMENT_GRADE=dev`; rejected otherwise. Default `false` | Without `allow_local_urls` (or outside `DEPLOYMENT_GRADE=dev`), `base_url` and every interface URL in an inline Agent Card must pass the safe-URL check, which refuses localhost, private ranges, and metadata addresses. At request time the same URLs are DNS-pinned and redirects are disabled. A session’s network access policy is also applied to the endpoint before and after the Agent Card is resolved. ## `spawn_agent` | Parameter | Required | Description | | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- | | `instructions` | Yes | Instructions sent to the external agent | | `target` | Yes | `{ "type": "external_a2a", "id": "" }`. `target.external_agent_id` is a deprecated spelling of `id` | | `mode` | No | `foreground` (default) or `background` | | `wait_timeout_secs` | No | How long to wait for the remote task, 1 to 86400. Default 300 | | `wake_on_completion` | No | Wake the session when a background run finishes. Default `true` | | `result_schema` | No | JSON Schema for a required structured result from the external agent | `message_schema` is not supported: a remote agent cannot call `report_task_progress`, so passing one fails. Text results are truncated to 8192 characters. `foreground` waits for the remote task and returns its reply. `background` returns a `task_id` at once. When task tracking is available, each run is a session task of kind `external_agent`, so `wait_task` collects the result, `message_task` answers a remote task that asks for input, and `cancel_task` stops it. ## See also * [A2A](https://everruns.com/docs/features/a2a/), serving agents over A2A and the delegation overview * [Agent Handoff](https://everruns.com/docs/capabilities/agent-handoff/), delegation to first-party agents * [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), the session task tools
---
# Agents
> Delegate work to configured first-party agents with spawn_agent, as a background task, a blocking call, or an invited participant in the current session.
Source:
| | | | ---------------- | ---------------- | | **ID** | `agent_handoff` | | **Category** | Orchestration | | **Features** | `agent_handoffs` | | **Dependencies** | None | | **Risk** | High | | **Availability** | Experimental | The Agents capability (`agent_handoff`) lets an agent hand work to other first-party Everruns agents. The agents it can use are listed ahead of time, so the model can only pick from that list. In the UI, add them from the agent’s **Agents** tab: link an existing agent, or create a new one there. Agents created there are exported and imported together with the agent that uses them. The capability adds the `agent` target type to the shared `spawn_agent` tool, the same dispatcher that [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/) and [A2A Agent Delegation](https://everruns.com/docs/capabilities/a2a-agent-delegation/) extend. The child runs as its own session, or joins the current session as a member. **Experimental.** Adding the capability to an agent is the opt-in; there is no separate feature flag. For delegation to agents outside Everruns, see [A2A Agent Delegation](https://everruns.com/docs/capabilities/a2a-agent-delegation/). For ad hoc child sessions that use the parent’s own configuration, see [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/). ## Configuration
```json
{
"ref": "agent_handoff",
"config": {
"targets": [
{
"agent_id": "agent_...",
"required_connections": ["github"]
}
]
}
}
```
| Field | Required | Description | | ---------------------- | -------- | -------------------------------------------------------------------------------------- | | `agent_id` | Yes | Public ID of the target agent | | `id` | No | Key the model passes as `target.id`; filled from the agent when saved | | `name` | No | Shown in the system prompt; filled from the agent’s name when saved | | `description` | No | Shown in the system prompt; filled from the agent’s description when saved | | `harness_id` | No | Harness to run the target on; defaults to the agent’s current harness at hand-off time | | `required_connections` | No | Provider connections that must exist before the handoff starts | | `required_scopes` | No | Non-secret scope labels recorded for audit and resource metadata | The system prompt lists every configured target by name, ID, and description. ## `spawn_agent` | Parameter | Required | Description | | ---------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `name` | Yes | Name for this delegated run | | `instructions` | Yes | Instructions for the target. Must not contain credentials | | `target` | Yes | `{ "type": "agent", "id": "" }` | | `mode` | No | `background`, `foreground`, or `invite` | | `public_context` | No | Non-secret structured context, appended to the instructions | | `result_schema` | No | JSON Schema for the child’s final result. The child must call `report_result` before the task can succeed | | `message_schema` | No | JSON Schema for structured progress messages. The child gets `report_task_progress` | ### Modes | Mode | Behavior | | ------------ | -------------------------------------------------------------------------------------- | | `background` | Default when session task tracking is available. Returns a `task_id` right away | | `foreground` | Default otherwise. Blocks until the handoff finishes and returns the result | | `invite` | Adds the target agent as a member of the current session instead of starting a new one | A background handoff is tracked as a session task of kind `agent_handoff`, so the parent manages it with the session task tools (`list_tasks`, `get_task`, `message_task`, `cancel_task`, `wait_task`). Background mode fails when task tracking is not available. Invite mode does not create a child task, so it rejects `result_schema` and `message_schema`. It also refuses the invite when the target’s configuration conflicts with the current session’s: the same capability with a different config, the same mounted file path with different contents, or the same MCP server name with a different definition. ### Connections When a target lists `required_connections` and the session cannot resolve a connection for one of those providers, `spawn_agent` returns a `connection_required` result naming the provider. The client collects the credentials through the Connections flow. The system prompt tells the agent never to ask for tokens in chat or pass them in tool arguments. ### Approvals and questions When an agent the session handed work to needs an approval or asks a question, the person answers it in the conversation they started, not in the other agent’s session. Chat and Playground show the card headed with that agent’s name. Over the API, `GET /v1/sessions/{session_id}/run-requests` on the first session lists what the other agents wait on, each with the asking agent and its `session_id`. Answer with the usual `POST /v1/sessions/{session_id}/tool-approvals` or `…/question-answers` on either session: the first session routes the answer to the agent that asked. On the Agent Execution API, `pending_approvals` and `pending_questions` on the session include these requests with `agent` and `session_id`, and answers on the session are routed the same way. Only a person (or the API key holder) answers; another agent’s message never approves. ### Team folder Every agent in one run shares a `team/` folder in its files. What one agent writes there, the others can read straight away, and the files stay after the run ends. The routing agent is told to have each agent write its results under `team//` and to pass file paths in its instructions instead of pasting long content. Each run gets its own folder: starting the same agent again starts with an empty one. A session that is not part of a run (an agent without this capability, on its own) has no team folder. The folder does not show up in the organization’s Memory list. ### Starting with a copy of the files By default an agent starts with its own files. Set a member’s **Files** to **A copy of this agent’s** on the Agents tab (or `"files": "copy"` on its target) and each hand-off starts with a copy of the handing-off session’s files. The agent works on the copy; the originals stay as they were, and the results come back through the team folder. ### Agents talking to each other Agents in one run can message each other while they work. Each has two tools: * `message_agent` posts a message. Set `to` to an agent’s name and that agent gets it in its own conversation; set `to` to `everyone` and every agent in the run does. Without `to`, the message is only posted for others to read. * `read_run_conversation` reads the latest messages and lists the agents you can message. The messages are kept in the team folder under `team/conversation/`, so you can read the whole exchange in the first session’s Files. A message from another agent is always marked as such: it never counts as your answer to an approval or a question. A run stops accepting messages after 200, so two agents cannot keep answering each other forever. ## See also * [A2A Agent Delegation](https://everruns.com/docs/capabilities/a2a-agent-delegation/), delegation to external agents * [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), child sessions from the parent’s own configuration, and the session task tools
---
# AGENTS.md
> Project instructions resolved hierarchically from workspace files such as AGENTS.md and injected as the leading user message on every turn.
Source:
| | | | ---------------- | -------------------- | | **ID** | `agent_instructions` | | **Category** | Core | | **Features** | None | | **Dependencies** | None | Resolves project instruction files hierarchically, from the session filesystem root down to the working directory, and injects them as the leading user-role message on every turn. By default it reads `AGENTS.md`, Everruns’ implementation of the [`AGENTS.md`](https://agents.md/) open convention. Configure `files` when an agent should also resolve another file such as `CLAUDE.md` at every hierarchy level. Workspace files are untrusted third-party content, so they never enter the system prompt: harness safety instructions always take precedence, and file edits never invalidate the cache-stable system prefix. ## Tools None. This capability only contributes conversation context, never system prompt. ## How it works 1. The agent receives a message. 2. Before the model call, the capability resolves the configured filenames from the filesystem root down to the working directory. A `docs/AGENTS.md` applies to work under `docs/`; deeper files override shallower ones on conflict. Files in sibling subtrees are never loaded. 3. The assembled block opens with a trust framing header and wraps each file in `` tags, broadest scope first. 4. The block is injected as the leading user-role message: visible to the model, re-resolved every turn, and below system instructions in precedence. Edits during a session apply on the next turn, with no restart. If a configured file doesn’t exist, the agent operates normally. ## Prompt order Every turn the model sees, top to bottom: 1. **System prompt**: harness safety instructions, tool guidance, role (cache-stable). 2. **Conversation context**: the resolved `AGENTS.md` hierarchy, broadest scope first. 3. **Conversation history and the latest user message**. Explicit user instructions win over project files on conflict; system instructions always win over both. ## Config
```json
{
"files": ["AGENTS.md", "CLAUDE.md"]
}
```
`files` is optional. When omitted, Everruns resolves `AGENTS.md` at every level from the root to the working directory. A config may list at most 16 files. ## Limits * **32 KiB per file**. Longer content is truncated with a warning. * **128 KiB total per turn**, which bounds hierarchy depth. Deeper files past the budget are omitted with an explicit note. * At most 16 instruction files resolved per turn. * Plain Markdown, no required sections. ## Notes * Works with [File System](https://everruns.com/docs/capabilities/file-system/) tools, so an agent can update its own instructions. * Missing configured files are ignored, with no error. ## Do something * [Use AGENTS.md for project instructions](https://everruns.com/docs/how-to/use-agents-md/): full guide with examples. * [Equip an agent with tools](https://everruns.com/docs/how-to/equip-agents-with-tools/): adding capabilities generally. ## See also * [File System](https://everruns.com/docs/capabilities/file-system/): manage the AGENTS.md file. * [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/): another way to inject specialized instructions. * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Agent Skills
> Discover and activate portable skill packages from the session workspace at runtime.
Source:
| | | | ---------------- | ---------------------------------------------------------------------------- | | **ID** | `skills` | | **Category** | Core | | **Features** | None | | **Dependencies** | [`session_file_system`](https://everruns.com/docs/capabilities/file-system/) | Discover and activate skills from `/.agents/skills/` in the session filesystem. Skills are portable instruction packages following the [Agent Skills](https://agentskills.io/) open specification. ## Tools ### `list_skills` Scan `/.agents/skills/` for available skills. Returns names and descriptions only (\~100 tokens per skill). ### `activate_skill` Load a skill’s full instructions by name. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------- | | `name` | string | yes | Skill name (directory name under `/.agents/skills/`) | Returns: full SKILL.md content and list of bundled files. ## How It Works Skills use progressive disclosure to keep context efficient: 1. **Discovery** (\~100 tokens), `list_skills` returns only names and descriptions 2. **Activation** (<5000 tokens), `activate_skill` loads the full SKILL.md instructions 3. **Resources** (on-demand), bundled files accessible via [File System](https://everruns.com/docs/capabilities/file-system/) tools ## Workspace layout
```plaintext
/.agents/skills/
deploy/
SKILL.md
templates/
k8s-deploy.yaml
code-review/
SKILL.md
```
## Notes * Skills are per-session (uploaded to session filesystem) * Path traversal protection on skill names * Invalid SKILL.md files are reported but don’t block discovery of other skills * For organization-wide skills, see the [Skills Registry](https://everruns.com/docs/features/skills/#skills-registry) ## See Also * [Agent Skills feature guide](https://everruns.com/docs/features/skills/), detailed skills documentation * [Skills Registry](https://everruns.com/docs/features/skills/#skills-registry), API-managed skills * [AGENTS.md](https://everruns.com/docs/capabilities/agent-instructions/), simpler alternative for project context * [File System](https://everruns.com/docs/capabilities/file-system/), upload skill files * [Capabilities Overview](https://everruns.com/docs/capabilities/) ## Prompt caching during installation Skill discovery instructions stay in the system prompt. When installation or an edit changes the available skills, the inventory is delivered as a later conversation update. Unchanged inventories add no repeated update; removed inventories receive an explicit clearing update. Updates survive worker restarts through stored conversation metadata. The same behavior applies to multi-scope skills and optional inspection reports. `list_skills` still returns the current full catalog, and `activate_skill` loads the selected instructions through the authorized filesystem. Sessions carrying these updates use local history reduction rather than opaque provider-managed checkpoints.
---
# Ask User
> Let an agent ask the user a small batch of structured questions, and wait for the answer, instead of guessing or ending the turn in prose.
Source:
| | | | ---------------- | ---------- | | **ID** | `ask_user` | | **Category** | Core | | **Features** | None | | **Dependencies** | None | Gives the agent one tool for collecting decisions it cannot make on its own. Instead of guessing, or ending the turn with a paragraph of questions and hoping the user answers all of them, it asks 1–4 structured questions and waits. The user sees a card with the questions. Choice questions show described options, and text questions show a free-form field. Answering resumes the turn. Opt-in on the canonical levels. Included in deprecated [Generic](https://everruns.com/docs/built-ins/harnesses/generic/) and [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) harnesses. Not on [Base](https://everruns.com/docs/built-ins/harnesses/base/), which has no interactive surface. ## When to enable it Enable it for agents that work *with* a person: anything where the agent’s first guess about intent, scope, or preference is likely to be wrong and expensive to undo. Leave it off for agents that run unattended on a schedule or a trigger. It will not hang them — a client that cannot render a choice gets the model’s declared defaults immediately, while text and secret questions are declined — but an agent nobody is watching should be built to decide, not to ask. ## Not a consent gate This is the boundary worth being clear about before enabling both: | | `ask_user` | `request_approval` | | --------- | ---------------------------------------- | --------------------------- | | For | Decisions and preferences | Permission to act | | Example | “Which environment?” | “May I delete this bucket?” | | No answer | Choice defaults; text and secret decline | Stays unresolved | Choice questions **auto-resolve**. A choice nobody answers falls back to the option the model marked as recommended. Text and secret questions are skipped instead because they have no default value. None of these outcomes grants permission, so a destructive, irreversible, or outward-facing action must go through `request_approval` (the `soft_approval` capability), whose wait does not auto-resolve. Both are enabled together on the interactive harnesses for exactly this reason: the agent needs somewhere to put a preference so it stops putting permission questions there. The system prompt states the rule, but the capability pairing is what makes it followable. ## Question kinds **Choice** — 2 to 6 options, single- or multi-select, optionally with a free-text “Something else” path. Options are ordered most-applicable-first, because that is the order a fallback follows. **Text** — one free-form answer with no options. Use it for open questions such as a branch name. An unanswered text question is declined rather than submitted as an empty answer. **Secret** — collects a credential. The value is stored encrypted in [session storage](https://everruns.com/docs/capabilities/session-storage/) and the agent receives a reference (`session:MY_TOKEN`), never the value itself, so it cannot reach the conversation history or the agent’s context. Tools resolve the reference by name. A secret question never auto-resolves: there is no such thing as a default credential, so an unanswered one is declined and proceeding without it becomes the agent’s explicit decision. Use the secret kind rather than asking for a key in chat. A key typed into an ordinary message stays in the session history in plain text. ## Tools | Tool | Description | | ---------- | ------------------------------------------------------------------------------------------ | | `ask_user` | Ask 1–4 choice or free-form questions, or collect one credential, and wait for the answer. | ## Configuration None. Limits are fixed by the contract: | Limit | Value | | --------------------------- | ------------------------------------------------------- | | Questions per call | 1–4 (a secret question must be alone) | | Options per choice question | 2–6 | | Timeout | 300 seconds, which the agent may shorten but not extend | ## What the agent is told The result says what was chosen **and who chose it** — a person, a timeout, or an unattended fallback. An agent that reads a fallback as a considered answer will act with more confidence than the answer deserves, so provenance travels with it. A declined question is a finished decision. The agent must not ask it again. ## See Also * [Session Storage](https://everruns.com/docs/capabilities/session-storage/), where a collected secret is kept * [Implementing a responder](https://everruns.com/docs/framework/ask-user/), for embedding applications * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Automatic session titles
> Automatically name conversations and update titles when the primary topic changes, independently of the agent's tools.
Source:
| | | | ---------------- | -------------------------- | | **ID** | `automatic_session_titles` | | **Category** | Session | | **Tools** | None | | **Dependencies** | None | Enable **Automatic session titles** on a harness, agent, or session. The platform checks the conversation after a completed turn without waiting on the title model before delivering the agent’s answer. The `session` capability and its `write_session_title` tool are optional. ## Model selection By default, titles use the organization’s **Small model**, configured under **Models → Defaults**. If that setting is empty, titles inherit the session’s model, including its agent, harness, and organization defaults. In capability settings, choose **Use session model** to always inherit the session model, or select a specific model and provider. An unavailable selected model skips generation; it never switches accounts or uses deployment utility credentials. Title requests count toward session usage and budgets.
```json
{
"ref": "automatic_session_titles",
"config": {
"model_id": "session",
"retitle": true
}
}
```
Omit `model_id` to use the organization Small model default. Set `retitle` to `false` to generate only the initial title. ## When titles change The first check follows the first completed turn with a user message. Greetings or insufficient context can leave the session untitled. Later checks require at least five minutes and new user messages: 4 after a changed title, then 8, 16, and 32 between checks if the current title stays useful. The interval stays at 32 until a title changes. Failed attempts also back off. Autonomous turn continuations do not count as new user messages. One bounded model request decides whether to keep the title or replace it. There is no separate intent-classification request on every turn. The title model sees a limited recent text transcript and no tool results or attachments. Generation is best effort: an outage leaves the existing title in place. ## Explicit titles take priority A title supplied at creation, renamed through the API or UI, or written with `write_session_title` becomes explicit and is never overwritten automatically. Writing the same text explicitly also takes ownership. An explicit rename wins even when a title request is already running. The existing [Session capability](https://everruns.com/docs/capabilities/session/) remains available for agent-directed naming. Leave its `auto_title` flag off when using this capability; enabling that flag asks the main agent to name the session explicitly, which takes priority over automatic maintenance. Title text changes emit the usual `session.title.updated` event.
---
# Bashkit Shell
> Run Bash commands in a sandboxed interpreter with process isolation, resource limits, streaming output, and workspace-only filesystem access.
Source:
| | | | ---------------- | ---------------------------------------------------------------------------- | | **ID** | `bashkit_shell` (legacy alias: `virtual_bash`) | | **Category** | Execution | | **Risk** | High, assignment requires an org **Admin** | | **Features** | `file_system` (enables the Files tab) | | **Dependencies** | [`session_file_system`](https://everruns.com/docs/capabilities/file-system/) | Execute bash commands in a sandboxed environment with no access to the host system. The session filesystem is mounted at `/workspace`, so commands read and write the same files as the [File System](https://everruns.com/docs/capabilities/file-system/) tools. ## About Bashkit This capability runs on [**Bashkit**](https://bashkit.sh), a virtual Bash interpreter written in Rust. It executes shell scripts in-process, with no real shell, no subprocess spawning, and no host access, which makes it suitable for running untrusted scripts in multi-tenant agent environments. Browse the source on [GitHub](https://github.com/everruns/bashkit). Bashkit provides: * **The shell language**: variables, parameter expansion, command substitution, arithmetic, pipelines, redirections, control flow, functions, arrays, globs, and here-documents. * **Built-in commands** implemented in Rust: file I/O and navigation (`cat`, `ls`, `find`, `cp`, `mv`), text processing (`grep`, `sed`, `awk`, `jq`, `sort`), archives (`tar`, `gzip`), and network commands (`curl`, `wget`). * **A pluggable virtual filesystem**: Everruns plugs in the session file store, so there is no copy step before or after a command. * **Resource limits** on command count, loop iterations, and function depth, so a runaway script cannot exhaust shared infrastructure. Because the interpreter is sandboxed by construction, bash here is **not** a shell-out to the host: there is no `/bin/bash` process, no direct network stack, and no filesystem beyond the session workspace. Outbound HTTP for `curl`/`wget` is off by default and can be enabled per agent (see **Outbound HTTP** below). ## Tools ### `bash` Execute a shell command (or a multi-line script). | Parameter | Type | Required | Description | | ------------- | ------- | -------- | -------------------------------------------------------- | | `commands` | string | yes | Shell command(s) to execute | | `working_dir` | string | no | Working directory (default: `/workspace`) | | `timeout_ms` | integer | no | Timeout in milliseconds (default: `30000`, max: `60000`) | | `output` | string | no | Output verbosity (`auto`, `normal`, …; default: `auto`) | Returns `stdout`, `stderr`, `exit_code`, and a `success` flag. Output streams live to the UI and CLI via `tool.output.delta` events while the command runs. On timeout, any partial output captured so far is returned alongside the error. This tool also supports background execution, long scripts can run detached and report progress without blocking the agent loop. ## Filesystem The interpreter exposes a single mount: * **`/workspace`** maps to the session file store. Reads and writes are live, files created by bash are immediately visible to the File System tools and vice versa. * Paths outside `/workspace` (for example `/etc`, `/home/agent`, `/tmp`) do not exist and cannot be written. * Symlinks are unsupported; `chmod` is a no-op (the session filesystem does not track Unix permissions, and files are executable by default). Default environment: `HOME=/home/agent`, `SHELL=/bin/bash`, `PATH=/usr/local/bin:/usr/bin:/bin`, `WORKSPACE=/workspace`, user and host `everruns`. ## Resource limits Every invocation runs under fixed limits to prevent runaway scripts: | Limit | Value | | -------------------- | ------------------------------------- | | Max commands per run | 1,000 | | Max loop iterations | 10,000 | | Max function depth | 100 | | Max script size | 1 MB | | Max memory | 10 MB | | Parser timeout | 5 s | | Wall-clock timeout | `timeout_ms` (default 30 s, max 60 s) | ## Outbound HTTP (optional) Set the capability config `{"enable_http": true}` to let scripts use `curl` and `wget`. Every request, including each redirect hop, is routed through the platform egress boundary, where the agent/session network access list and the deployment-wide system allowlist are enforced. Policy denials surface as curl’s native `access denied` failure (exit code 7). Without the flag, the interpreter has no network path at all. ### API keys the agent never sees A **bound secret** is an API key stored with the URL it may be sent to and how (`Authorization: Bearer`, or a named header). With outbound HTTP on, the shell sees `$NAME` as a placeholder, and the platform swaps in the real key only in that header and only for requests to the bound URL:
```bash
curl -sS https://api.example.com/v1/items -H "Authorization: Bearer $EXAMPLE_API_KEY"
```
The model can never read the value: printing `$NAME` shows an opaque handle. A request that places that handle on another host, path, header, or form field is refused before it is sent, including a redirect to another destination. A response that echoes the key is redacted. The bound URL still has to pass the agent’s network access list. A Daytona, E2B, or Modal command runs without these bindings. `sandbox_exec` does not expand `$NAME`, and those providers do not add the credential to outbound HTTPS. Modal’s GitHub connection injection is a separate, domain-wide control. Set one for every session of an agent on the agent’s **Credentials** tab: **Add binding**, choose **HTTP API**, and give the shell variable, the URL and how it is sent. Platform Chat or the CLI can declare it without a value, and you paste the value on that tab:
```bash
everruns agents credentials create --agent-id agent_01h9 \
--env-name EXAMPLE_API_KEY --url https://api.example.com --label 'Example API key'
```
Set one for a single session with `bindings` on `PUT /v1/sessions/{session_id}/storage/secrets`. Over MCP, `session_set_secret` takes `url`, `auth`, `header` and `scope` and collects the value on a secure page, so it never passes through the MCP client. ## Security * **Sandboxed**: no direct network access (outbound HTTP is opt-in and egress-routed), no host filesystem, no subprocess spawning. * **High risk**: because it exposes arbitrary scripted code execution, assigning `bashkit_shell` to an agent requires an org **Admin**. Existing agents that already had it keep working; the gate applies to new assignments only. * Built-in observability hooks emit structured `tracing` events per builtin and on interpreter errors (tagged with the session ID) without logging argument values or command output. ## Notes * Commands operate on the same `/workspace` as [File System](https://everruns.com/docs/capabilities/file-system/) tools. * Built-in commands support ` --help`, and many also support ` --version`. * Common builtins: `cd`, `ls`, `cat`, `echo`, `grep`, `head`, `tail`, `sed`, `find`, plus shell features like pipes, redirections, and command substitution. `grep` is backed by the session’s indexed search. ## See Also * [Bashkit project](https://bashkit.sh), the interpreter powering this capability * [File System](https://everruns.com/docs/capabilities/file-system/), file operations on the same workspace * [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), background and parallel execution * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Browser Use
> Let an agent work in a browser through the page structure, with element refs, form filling, and tabs, on any model.
Source:
| | | | ---------------- | ---------------------------------------------------------- | | **ID** | `browser_use` | | **Category** | Browser | | **Features** | Leased resources | | **Dependencies** | `session_storage` | | **Risk** | High (the model reads and acts on whatever the page shows) | | **Availability** | Experimental | Browser use lets an agent work in a web browser through what the page is made of, not only what it looks like. The agent reads the page as an accessibility tree, where every element it can act on carries a ref such as `ref_3`. It then clicks, hovers, scrolls to, or fills that element by ref. It can still take screenshots and act on viewport coordinates when the structure is not enough, and it can open, switch, and close tabs. The `browser` tool is a regular function tool, so it works with any model. Screenshots and `zoom` need a model that accepts images; the other actions return text. It follows the action vocabulary of Claude’s `browser_toolset_20260801`. On Claude models that take that toolset, the agent uses Claude’s own browser tool instead, which those models are trained on, and reads the open tabs from the toolset’s browser state. The actions, the safety rules, and the limits are the same either way. The browser is the session’s persistent [Browserless](https://everruns.com/docs/capabilities/browserless/) browser. Connect Browserless from **Settings → Connections** first. The agent shares that browser with the Browserless tools and with [Computer Use](https://everruns.com/docs/capabilities/computer-use/), so a page one opens is a page the others see. ## Tools ### `browser` Performs one action. Every successful result carries a `browser_state` object: every open tab with its `tab_id`, title and URL, which tab is active, and in `state_changes` the tabs opened since the previous result. A target is either `{"type": "ref", "ref": "ref_3"}` or `{"type": "coordinate", "x": 412, "y": 230}`, in pixels of the viewport. | `action` | Parameters | What it does | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `read_page` | optional `filter` (`interactive` or `all`), `depth`, `ref` | Read the page as an accessibility tree with refs. By default it lists what is in the viewport; `interactive` lists only the controls; `all` includes the rest of the page; `ref` reads one element’s subtree | | `find` | `query` | Up to 20 elements that best match a description such as `search box` or `sign up button` | | `get_page_text` | none | The page’s text, main content first | | `form_input` | `target` (a ref), `value` (text, a choice, or `true`/`false` for a checkbox) | Set a field’s value and fire its `input` and `change` events | | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click` | `target`, optional `modifiers` such as `shift` | Click the element’s center or the point | | `hover`, `mouse_move` | `target` (`mouse_move` takes a coordinate) | Move the pointer | | `left_click_drag` | `from`, `target` | Press, drag, and release | | `left_mouse_down`, `left_mouse_up` | `target` | Press or release the left button there | | `scroll` | `target`, `scroll_direction`, optional `scroll_amount` (1 to 10, default 3) | Scroll at that point | | `scroll_to` | `target` (a ref) | Scroll the element into view | | `type` | `text` | Type at the keyboard focus | | `key` | `text` (space-separated keys or combos, such as `Tab Tab Enter` or `ctrl+a`), optional `repeat` | Press keys | | `hold_key` | `text`, `duration` (seconds, up to 30) | Hold keys down, then release them | | `wait` | `duration` (seconds, up to 30) | Pause | | `screenshot` | none | Capture the viewport | | `zoom` | `region` (`[x0, y0, x1, y1]`) | That part of the viewport, enlarged to the viewport size | | `navigate` | `url`, or `back`, `forward`, `reload` | Load a page or step through history | | `new_tab`, `list_tabs` | none | Open a blank tab and make it current, or list the tabs | | `switch_tab`, `close_tab` | `tab_id` | Make a tab current, or close it | Any action also takes an optional `tab_id` to act on that tab; it becomes the current tab. Example calls:
```json
{ "action": "find", "query": "email field" }
{ "action": "form_input", "target": { "type": "ref", "ref": "ref_4" }, "value": "ada@example.com" }
{ "action": "left_click", "target": { "type": "ref", "ref": "ref_7" } }
```
Refs belong to the page they were read from. After a navigation, or when the page removes the element, using one returns an error that tells the agent to read the page again; a ref is never applied to a different element. `javascript_exec`, `file_upload`, `read_console`, and `read_network` are not offered. A call that asks for one is refused. ## Configuration | Field | Default | Description | | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | `viewport_width` | `1280` | Viewport width in pixels (320 to 1920) | | `viewport_height` | `800` | Viewport height in pixels (320 to 1200) | | `max_actions_per_session` | `500` | Hard cap on actions in one session | | `native_tools` | `true` | Use Claude’s native browser toolset on models that have one. When off, every model uses the `browser` function tool. | When Claude sends several browser actions in one turn and one fails, the later ones are not run; each answers that an earlier action failed. ## Safety * **The model reads everything on the page.** Text, tab titles, and URLs can try to steer the agent. The capability tells the model to treat them as untrusted data and to stop and ask before typing credentials, making purchases, sending messages, or confirming irreversible actions. Add [`tool_approval`](https://everruns.com/docs/capabilities/tool-approval/) when a person must approve every `browser` call before it runs. * **Refs stay out of the page.** Everruns keeps the table that maps refs to elements; the page cannot read or move it, so a ref read as “Cancel” cannot be pointed at “Buy”. * **Page scripts cannot tamper with reads and fills.** `get_page_text` and `form_input` run in a separate script world, so a page that overrides built-in functions does not change what they read or write. * **Keep credentials out of reach.** Do not give a browser-use agent a browser that is signed in to accounts it should not use. * **Egress.** `navigate` takes only http and https addresses; an address without a scheme is read as https. It refuses private and internal addresses and follows the session’s network access list. Everruns makes every request the page makes, in every tab, and applies the same rules to each one. If a page navigates somewhere blocked on its own, it is reset to a blank page and the action reports an error. * **Budget.** `max_actions_per_session` stops runaway loops. ## Availability Browser use is available on every deployment. Add the `browser_use` capability to an agent and connect your own Browserless account.
---
# Browserless
> Headless browser automation through Browserless for screenshots, DOM reading, scraping, page interaction, and persistent sessions for login-protected pages.
Source:
## Framework Enable the `browserless` Cargo feature and bind application-owned services with `.browserless(credentials)`. See [Framework services](https://everruns.com/docs/framework/native-services/) for credentials, persistence and a complete real-model example. The remaining setup sections describe the hosted Platform. | | | | ---------------- | ---------------------------------------------------------------------------- | | **ID** | `browserless` | | **Category** | Browser | | **Features** | None | | **Dependencies** | [`session_storage`](https://everruns.com/docs/capabilities/session-storage/) | Cloud browser automation powered by [Browserless](https://www.browserless.io/). Agents can navigate pages, take screenshots, read rendered DOM content, scrape structured data, and interact with pages using click, type, keyboard, mouse, and touch events. ## Set up 1. In the [Browserless Dashboard](https://www.browserless.io/account/home), open **API Keys** in your account settings and copy your API token. 2. In Everruns, open **Settings** > **Connections**, find **Browserless**, select **Connect**, and paste the token. Once connected, agents with the Browserless capability can use the tools below. ## Two operating modes **Stateless (default).** Each tool call opens a fresh browser that is destroyed after the response. Nothing persists between calls, and no cleanup is needed. Use it for one-shot screenshots or scraping. **Persistent session (CDP).** `browserless_open_browser` creates a browser over the Chrome DevTools Protocol that stays alive between tool calls, keeping login state, cookies, and navigation history. Tools use the persistent browser automatically when one is active. A persistent browser expires after 60 seconds of inactivity by default; call `browserless_close_browser` when done for immediate cleanup. Both modes connect over the Chrome DevTools Protocol, so the Browserless token needs WebSocket (CDP) access. A Browserless cloud token without it falls back to the Browserless REST API for the stateless tools; see [Security](#security). A typical flow for a login-protected page: 1. `browserless_open_browser` with the login page URL. 2. `browserless_interact` to fill credentials and submit the form. 3. `browserless_navigate` to browse authenticated pages. 4. `browserless_screenshot` to capture the authenticated page state. 5. `browserless_close_browser` to release resources. ## Saved logins A sign-in can outlive the browser. `browserless_save_login` stores the persistent browser’s cookies, plus the local storage of the page it has open, as a named login in your Browserless account. A later session passes that name as `login` to `browserless_open_browser` and starts signed in, without typing the password again. Logins belong to the Browserless account of the connection the agent uses. With a personal Browserless connection, they are yours. A login you create in the Browserless dashboard, where you sign in through a remote browser yourself (handy for MFA or a CAPTCHA), works the same way. `browserless_list_logins` shows their names and counts, never the cookie values. A typical flow: 1. `browserless_open_browser` with the login page URL, then sign in with `browserless_interact`. 2. `browserless_save_login` with a name such as `github-work`. 3. In a later session: `browserless_open_browser` with `login: "github-work"` and the page URL. Cookies apply to every site in the login. A site’s local storage is written on the first page load of that site in the same `browserless_open_browser` call, so pass `url` when the site keeps its sign-in there. A saved login is as sensitive as the password it replaces: anyone whose agent uses the same Browserless connection can open it. Browserless deletes a login that goes unused for a year. ## Tools ### `browserless_open_browser` Open a persistent browser session via CDP. | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------- | | `url` | string | no | Initial URL to navigate to | | `timeout_ms` | integer | no | How long the browser stays alive between calls (default: 60000) | | `login` | string | no | Name of a saved login to restore before the first page loads | ### `browserless_close_browser` Close the persistent browser session and release resources. Takes no parameters. ### `browserless_save_login` Save the persistent browser’s sign-in as a named login. Saving under an existing name replaces it. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | `name` | string | yes | Up to 255 characters, no spaces or `/ ? # % &` | ### `browserless_list_logins` List the saved logins in the connection’s Browserless account: name, cookie and site counts, and last change. Takes no parameters. ### `browserless_navigate` Navigate to a URL and return page metadata (title, links, headings, meta tags). | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | ------------------------------------------- | | `url` | string | yes | The URL to navigate to | | `wait_for_selector` | string | no | Wait for this CSS selector to appear | | `wait_for_timeout` | integer | no | Wait this many milliseconds after page load | ### `browserless_screenshot` Take a PNG screenshot of a page. Returns base64-encoded image data. | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | ---------------------------------------------------- | | `url` | string | yes | The URL to screenshot | | `full_page` | boolean | no | Capture the full scrollable page (default: true) | | `selector` | string | no | CSS selector to screenshot a specific element | | `wait_for_selector` | string | no | Wait for this CSS selector before taking screenshot | | `wait_for_timeout` | integer | no | Wait this many milliseconds before taking screenshot | ### `browserless_content` Get the fully rendered HTML content (DOM) of a page, including JavaScript-rendered content. | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | --------------------------------------------------------------- | | `url` | string | yes | The URL to read | | `wait_for_selector` | string | no | Wait for this CSS selector before reading content | | `wait_for_timeout` | integer | no | Wait this many milliseconds before reading content | | `best_attempt` | boolean | no | Continue even if async events fail or time out (default: false) | ### `browserless_scrape` Extract structured data from a page using CSS selectors. Returns JSON with matched elements. | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | ------------------------------------------- | | `url` | string | yes | The URL to scrape | | `elements` | array | yes | Array of `{selector}` objects to extract | | `wait_for_selector` | string | no | Wait for this CSS selector before scraping | | `wait_for_timeout` | integer | no | Wait this many milliseconds before scraping | ### `browserless_interact` Navigate to a URL, then perform a sequence of actions. | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `url` | string | yes | The initial URL to navigate to | | `steps` | array | yes | Ordered list of interaction steps | | `return_screenshot` | boolean | no | Return a base64 screenshot after all steps (default: false) | | `return_content` | boolean | no | Return DOM content after all steps (default: false). With both flags true, both are returned; with neither, DOM content is returned | **Supported step actions:** | Action | Key Parameters | Description | | ------------------- | --------------------- | -------------------------------------- | | `click` | `selector` or `x`,`y` | Click element or coordinates | | `type` | `selector`, `value` | Type text into input field | | `keyboard` | `key` | Press a key (Enter, Tab, Escape, etc.) | | `mouse_move` | `x`, `y` | Move mouse to coordinates | | `touch` | `selector` | Tap element (mobile touch simulation) | | `scroll` | `value` | Scroll page by pixel amount | | `wait` | `wait_ms` | Wait for milliseconds | | `wait_for_selector` | `selector`, `wait_ms` | Wait for element to appear | | `navigate` | `value` | Navigate to a different URL | ## Uses * **Accessibility testing**: navigate pages, read the DOM, check ARIA attributes and heading structure. * **Regression testing and visual QA**: take before and after screenshots and verify content after changes. * **Login flows**: authenticate in a persistent session and test protected pages. * **Web scraping**: extract structured data from a website. ## Security * API tokens are encrypted at rest (AES-256-GCM envelope encryption). * Browser sessions are isolated on Browserless servers. * The browser has no network access of its own. Everruns makes every request the page makes, including each redirect hop, scripts, and images. Private, loopback, link-local, and cloud metadata addresses are refused, both as URLs and as DNS answers, and the session’s network access list applies to every request. A blocked page load returns an error, never the page. * WebSockets and other connections a page opens outside HTTP requests are refused. * A relayed response is limited to 10 MB. * The REST fallback for Browserless cloud tokens without CDP access runs in Browserless’ network and checks only the URL you pass. A self-hosted Browserless never falls back. * CDP session state stores only the WebSocket endpoint (no secrets), scoped per session. * Large DOM responses are truncated to 100KB to prevent context flooding. ## See also * [Browserless documentation](https://docs.browserless.io/) * [Integrations](https://everruns.com/docs/integrations/): every vendor integration. * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Budgeting
> Expose active budgets to the agent so it can check the remaining balance and adjust its own spending.
Source:
| | | | ---------------- | -------------- | | **ID** | `budgeting` | | **Category** | Cost Control | | **Features** | `budgeting` | | **Included in** | Worker harness | | **Dependencies** | None | Makes an agent aware of its budget constraints. The agent receives budget information in its system prompt and can proactively check remaining balance before expensive operations. ## Tools ### `check_budget` Query the budget status for the current session. > The tool reports whether budgets are configured. For balances, limits, and the status of each budget, use `GET /v1/sessions/{id}/budget-check`. | Parameter | Type | Required | Description | | --------- | ---- | -------- | ---------------------- | | *(none)* | | | No parameters required | ## Behavior When the `budgeting` capability is enabled: 1. **System prompt injection**: The agent’s system prompt includes a “Budget Awareness” section with the current budget status and guidelines for efficient output. 2. **Self-regulation**: When budget is running low, the agent prioritizes completing current tasks efficiently rather than exploring new directions or generating verbose output. 3. **Proactive checking**: The agent can call `check_budget` before starting expensive operations (large code generation, multi-step tool chains) to decide whether to proceed or ask the user. ## Related * [Budgets](https://everruns.com/docs/advanced/budgets/), full budgeting system documentation (limits, currencies, API, CLI)
---
# Retrieval Citations
> Attach claim-level citations to an agent's answer from its knowledge retrieval results, so each grounded sentence links back to the source that supports it.
Source:
| | | | ---------------- | -------------------- | | **ID** | `citation_retrieval` | | **Category** | Knowledge | | **Features** | `citations` | | **Dependencies** | None | Turn the sources an agent retrieves into **claim-level provenance** on its answer. When the agent grounds a reply in a knowledge search, `citation_retrieval` links each grounded sentence to the passage that backs it, and the UI renders those links as inline numbered chips with a hover preview and a deduped **Sources** strip. It contributes **no tools** and **no system prompt**, and it never rewrites the model’s answer. After the agent responds, it inspects the turn’s retrieval results, aligns each retrieved passage to the sentence it best supports, and attaches a citation there. Alignment is deterministic token overlap, no extra model call, so it is model- and provider-agnostic. ## How it looks Grounded sentences get an inline numbered chip. Hovering a chip previews the source (title, snippet, and link); a deduped **Sources** strip sits below the message. When [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/) is also enabled, each source carries a faithfulness badge.  ## Feed Reads the results of the agent’s knowledge retrieval tools: | Tool | Source shape | | ------------------ | ---------------------------------------------------------------------------------------- | | `search_index` | Knowledge-index chunks (`kchk_…`), `source_uri`, `document_title`, `snippet`, `location` | | `search_knowledge` | Knowledge-base entries (`kbe_…`), `resource`, `title`, `snippet` | Both shapes are normalized into the shared citation envelope. A retrieval result with no usable snippet is skipped, there is nothing to align a claim to. > **This capability is a no-op on its own.** It cites what the agent retrieves, so it only produces citations when the agent also has a retrieval capability (a knowledge index or knowledge base) that surfaces `search_index` / `search_knowledge` results. With no retrieval feed, there is nothing to cite and the answer is unchanged. ## Configuration | Field | Type | Default | Description | | ------------- | ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `min_overlap` | number (0–1) | `0.5` | Minimum token-overlap ratio for a retrieved passage to attach to a sentence. Overlap is `shared tokens / passage tokens`, so `0.5` means at least half the passage’s distinctive words appear in the sentence. | Raise `min_overlap` for stricter, higher-precision attachment (fewer chips, each more defensible); lower it for broader coverage when the model paraphrases retrieved text. ## Notes * **No answer rewrite**: the streamed answer is never changed; annotations attach to sentence spans after generation. * **Alignment is lexical**: a sentence that paraphrases a source heavily enough to fall below `min_overlap` will not be cited. This favors precision over recall. * **Opt-in**: add `citation_retrieval` to a canonical harness to emit citations from a retrieval feed. Deprecated Generic includes it. * **Persistence**: annotations ride the message in the event log, so they survive reload, forking, and session export, no separate store. * **Org scoping**: sources are derived only from already-authorized retrieval results, so a citation can never reference a document the requesting org cannot read. ## See Also * [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/), stamp a faithfulness verdict on each citation * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Citation Verification
> Verify that each cited source actually supports the claim it is attached to, stamping a faithfulness verdict on every citation produced by any feed.
Source:
| | | | ---------------- | ----------------------- | | **ID** | `citation_verification` | | **Category** | Knowledge | | **Features** | `citations` | | **Guardrail** | Yes | | **Dependencies** | None | Check that each citation is **faithful**: that the source it points to actually supports the sentence it is attached to, and stamp a verdict on it. It is a guardrail capability, decoupled from the feeds: it consumes the citations collected during a turn (from [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/) or any future feed) and verifies them uniformly, so any feed can be paired with any verifier. It contributes **no tools** and **no system prompt**. The verdict renders in the UI as a badge on each source. ## Verdicts Each citation gets one of three verdicts, shown as a badge on the chip preview and in the **Sources** strip: | Verdict | Meaning | | ------------- | ---------------------------------------------------------------------------------- | | `entailed` | The source supports the claim. Rendered as a green **verified** badge. | | `unsupported` | The source does not support the claim. Rendered as an amber **unsupported** badge. | | `uncertain` | Support could not be established. Rendered as an **unverified** badge. |  ## Modes | Mode | Cost | Behavior | | --------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `heuristic` (default) | Free | Deterministic lexical entailment, token overlap between the claim span and the source snippet. No model call. A weak but honest baseline, strongest on verbatim citations. | | `llm` | One utility-model call per citation | A utility-model judgement per claim/source pair (claim = hypothesis, snippet = premise). More accurate; falls back to the heuristic when no utility model is configured. | ## Configuration | Field | Type | Default | Description | | ----------- | ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | `"heuristic"` \| `"llm"` | `"heuristic"` | Verification strategy (see above). | | `threshold` | number (0–1) | `0.5` | Entailment threshold for the heuristic verdict, the fraction of the claim’s distinctive tokens the source must cover to be `entailed`. | ## Notes * **Feed-agnostic**: verifies citations from any feed via the shared render contract, so evals can hold the feed fixed and vary only the verifier. * **Opt-in**: add `citation_verification` in `heuristic` mode to a canonical harness to verify citations with no model cost. Deprecated Generic includes it. * **`llm` mode needs a utility model**: with none configured it degrades gracefully to the heuristic rather than failing. * **No new data egress**: the verifier reasons only over text the feed already retrieved. ## See Also * [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/), the feed that produces the citations this verifies * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Web Citations
> Attach claim-level citations to an agent's answer from its web search results, whether the web_search tool or the model's own search found them.
Source:
| | | | ---------------- | -------------- | | **ID** | `citation_web` | | **Category** | Knowledge | | **Features** | `citations` | | **Dependencies** | None | Turn the pages an agent found with [Web Search](https://everruns.com/docs/capabilities/web-search/) into **claim-level provenance** on its answer. Each sentence the model backed with a search result links to that page, and the chat renders the links as the same inline numbered chips, hover preview, and **Sources** strip that [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/) use. It contributes **no tools** and **no system prompt**, and it never rewrites the model’s answer. After the agent responds, it reads the turn’s search results and the citations the model provider returned, and attaches a citation to each cited sentence. No extra model call is made. ## Feed | Source | How a citation is found | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `web_search` function results (free search, Brave, Parallel) | The tool asks the model to cite each claim with a result’s `url` or `id` (`w3f9a1c`). A URL in the answer that matches a result, or a result id, cites the sentence it sits in. A citation alone after its sentence, such as `Source: https://…`, cites the sentence before it. | | Native search: Anthropic | Text blocks with `web_search_result_location` citations; the block is the cited claim. | | Native search: OpenAI, OpenRouter | `url_citation` annotations on the answer text. | | Native search: Gemini | Grounding supports and their sources. | | `brave_web_search` results | Matched by URL, like `web_search` results. | Matching is exact, never fuzzy. A URL matches when it names the same page: scheme and host compare without case, and a `#fragment` or trailing slash does not count. The path and query must be equal. A provider’s citation keeps its place only while the text it covered is still there in the final answer; otherwise it is dropped rather than attached to the wrong words. Each citation carries the page `url`, its title, a snippet (the result’s snippet, or the provider’s quoted text), and the result id as `external_id`. Native citations get the same id the `web_search` tool would give the page. > **This capability is a no-op on its own.** It cites what the agent searched, so it only produces citations when the agent also has [Web Search](https://everruns.com/docs/capabilities/web-search/) (or `brave_web_search`). Answers without search results are unchanged. ## Configuration None. ## Notes * **Opt-in**: add `citation_web` next to `web_search`. The built-in harness presets turn on Web Search but not citations. * **Verification**: pair it with [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/) to stamp a faithfulness verdict on each citation, exactly as for retrieval citations. * **No answer rewrite**: the streamed answer is never changed; annotations attach to spans after generation. * **Persistence**: annotations ride the message in the event log, so they survive reload, forking, and session export. * **Untrusted sources**: a citation links to a public web page the search returned; the page content is not checked beyond what the verification capability does. ## See Also * [Web Search](https://everruns.com/docs/capabilities/web-search/) * [Retrieval Citations](https://everruns.com/docs/capabilities/citation-retrieval/) * [Citation Verification](https://everruns.com/docs/capabilities/citation-verification/) * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Claude Message Threads
> Send only new messages on compatible Claude turns, with full local history and automatic replay when temporary thread state expires.
Source:
| | | | ---------------- | ------------------------ | | **ID** | `claude_message_threads` | | **Category** | Optimization | | **Tools** | None | | **Features** | None | | **Dependencies** | None | Enable this capability on an agent or harness to use Anthropic’s optional message threads beta. The first request sends the full conversation; compatible later turns send only new messages. It adds no tools or system prompt text. Other provider drivers ignore the option. Everruns keeps the full transcript. If a thread expires or cannot be continued, the driver replays that history. Restarts, edits, changed settings, credentials, or concurrent turns can start fresh threads. Compaction and batch requests stay unthreaded; incomplete responses never advance thread state. **Data retention:** Anthropic temporarily retains thread content. This beta is not eligible for zero data retention or HIPAA. Enable it only when that retention is acceptable for your workload. Threads reduce repeated history uploads, but do not change token pricing. [Prompt Caching](https://everruns.com/docs/capabilities/prompt-caching/) remains a separate capability. See [the Anthropic provider guide](https://everruns.com/docs/providers/anthropic/#message-threads-beta) for configuration examples, retention details, and recovery behavior.
---
# Code Navigation
> Language servers, structural search and edit, and repository maps for agents that work on code in a sandbox.
Source:
Code navigation gives an agent the tools a developer’s editor has: jump to a definition, find every use of a symbol, rename it everywhere, search code by its structure, and get a symbol map of an unfamiliar repository. Text search answers “where does this string appear”. These answer “where is this symbol used”, which text search gets wrong for same-named symbols, aliases and re-exports. It is four capabilities. Add the ones the agent needs: | Capability | ID | Tools | | --------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- | | [Language servers](#language-servers) | `lsp` | `lsp_diagnostics`, `lsp_definition`, `lsp_references`, `lsp_hover`, `lsp_rename`, `lsp_symbols`, `lsp_code_actions` | | [Structural search](#structural-search) | `ast_grep` | `ast_grep` | | [Structural edit](#structural-edit) | `ast_edit` | `ast_edit` | | [Repository map](#repository-map) | `repo_map` | `repo_map`, `repo_symbols` | All four work on the code in the session’s sandbox, under `/workspace`. The session needs a sandbox: without one, each tool answers with an error that says so. Paths in arguments and results are relative to `/workspace`, so a workspace that holds several repositories names files as `my-app/src/main.rs`. ## Language servers `lsp` runs real language servers and asks them the question. It knows these out of the box: | Language | Server | Files | | ------------------------- | ---------------------------- | ------------------------------------------------------------ | | Rust | `rust-analyzer` | `.rs` | | TypeScript and JavaScript | `typescript-language-server` | `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` | | Python | `pyright-langserver` | `.py`, `.pyi` | | Go | `gopls` | `.go` | | C and C++ | `clangd` | `.c`, `.h`, `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh` | The server binary has to be installed in the sandbox image. When it is not, the tool names the missing binary, and the agent can install it and call again. A server starts the first time a file of its language is queried, so the first call is slower while the project is indexed. It then stays up inside the sandbox and later calls reuse it. In a workspace with several repositories each repository gets its own server, started in that repository’s root (the nearest directory with a `.git`). | Tool | What it answers | | ------------------ | --------------------------------------------------------------------------------------------- | | `lsp_diagnostics` | Errors and warnings in one file, without running a build | | `lsp_definition` | Where the symbol at a position is defined (also type definition, implementation, declaration) | | `lsp_references` | Every use of the symbol at a position, across the project | | `lsp_hover` | Type signature and documentation at a position | | `lsp_rename` | Renames a symbol everywhere it is used; `dry_run` previews the edits | | `lsp_symbols` | The outline of a file, or a fuzzy symbol search across the project | | `lsp_code_actions` | Quick fixes and refactorings at a position, and applies one by title | Positions are 1-based `line` and `column`, counted in characters. `lsp_rename` and `lsp_code_actions` change files. An edit is refused when it would touch anything outside the workspace or inside `.git`, `node_modules`, `target` and other vendored or build directories. ### Configuration
```json
{
"ref": "lsp",
"config": {
"servers": {
"python": { "command": "basedpyright-langserver", "args": ["--stdio"] },
"zig": { "command": "zls", "extensions": ["zig"] },
"go": { "enabled": false }
},
"request_timeout_ms": 60000,
"diagnostics_wait_ms": 15000
}
}
```
| Field | Default | Meaning | | -------------------------- | -------- | -------------------------------------------------- | | `servers..command` | built-in | Executable to run for this server | | `servers..args` | built-in | Its arguments | | `servers..extensions` | built-in | File extensions routed to it | | `servers..enabled` | `true` | `false` turns a built-in server off | | `request_timeout_ms` | `60000` | How long one request to a server may take | | `diagnostics_wait_ms` | `15000` | How long `lsp_diagnostics` waits for fresh results | A key that is not built in (`zig` above) adds a server and needs both `command` and `extensions`. ## Structural search `ast_grep` searches code by shape with [ast-grep](https://ast-grep.github.io/) patterns. `$NAME` matches one node and `$$$ARGS` matches any number:
```json
{
"name": "ast_grep",
"arguments": {
"pattern": "console.log($$$ARGS)",
"language": "typescript",
"path": "my-app/src"
}
}
```
It reads Rust, Python, TypeScript, TSX, JavaScript, Go, C#, CSS, HTML and Bash. Each match comes back with its file, position, text and captured variables. ## Structural edit `ast_edit` rewrites every match of a pattern with a replacement that can use the captured variables. It previews by default: the first call returns a diff and changes nothing. Calling again with `dry_run: false` applies it.
```json
{
"name": "ast_edit",
"arguments": {
"pattern": "console.log($$$ARGS)",
"replacement": "logger.info($$$ARGS)",
"language": "typescript",
"dry_run": false
}
}
```
## Repository map `repo_map` returns a compact map of the symbols in the workspace or a subdirectory, grouped by file: functions, types, methods and their signatures. It is the first thing to call in unfamiliar code. `repo_symbols` returns the same symbols as a flat list ranked against a `query`. Both read Rust, Python, JavaScript, TypeScript, C#, Go, Zig, CSS, HTML, Bash, SQL, Java, C, C++, PHP, Ruby, Kotlin and Scala. ## Limits Structural search, structural edit and repository maps read the source files out of the sandbox for each call. One call covers up to 20,000 source files and 24 MiB of compressed source. Past that the tool asks for a narrower `path`. Files larger than 1 MiB and vendored or build directories (`.git`, `node_modules`, `target`, `dist`, `build`, `.venv` and similar) are skipped. ## See Also * [Daytona](https://everruns.com/docs/capabilities/daytona/), [E2B](https://everruns.com/docs/capabilities/e2b/) and [Container Sandbox](https://everruns.com/docs/capabilities/container-sandbox/), the sandboxes these tools work in * [GitHub](https://everruns.com/docs/capabilities/github/), for pull requests on the code
---
# Computer Use
> Let an agent see a browser through screenshots and operate it with clicks, typing, scrolling, and key presses, with any model that accepts images.
Source:
| | | | ---------------- | ----------------------------------------------------------- | | **ID** | `computer_use` | | **Category** | Browser | | **Features** | Leased resources | | **Dependencies** | `session_storage` | | **Risk** | High (the model sees and acts on whatever the screen shows) | | **Availability** | Experimental | Computer use lets an agent work a screen the way a person does. It takes a screenshot, decides where to click or what to type, and gets a new screenshot after each action. It works on pages that selector-based browser tools cannot handle, such as canvas apps, heavy single-page apps, and custom widgets. The capability is provider-neutral. It is a regular function tool that returns images, so it works with OpenAI, Anthropic, Gemini, and any other model that accepts images in tool results. On models with a native computer tool (OpenAI GPT-5.4 and later through the Responses API, recent Claude models with `computer_toolset_20260801`, and Gemini 4 models on Google’s own endpoint), the agent uses the provider’s own tool instead, which those models are trained on. The display, the actions, and the limits are the same either way. The display is a Chromium page on a [Browserless](https://everruns.com/docs/capabilities/browserless/) browser. Connect Browserless from **Settings → Connections** first. The agent shares one persistent browser per session with the Browserless tools, so a page opened by `browserless_open_browser` is the page `computer` sees. ## Tools ### `computer` Performs one action and returns a screenshot of the display afterwards. Coordinates are pixels in the latest screenshot, with the origin at the top left. | `action` | Parameters | What it does | | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `screenshot` | none | Capture the display | | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click` | `coordinate` (optional `[x, y]`, defaults to the cursor), `text` (optional modifiers such as `shift` or `ctrl+shift`) | Click | | `left_click_drag` | `start_coordinate`, `coordinate`, `text` (optional modifiers held during the drag) | Press, drag, and release | | `left_mouse_down`, `left_mouse_up` | none | Press or release the left button at the cursor, for drags that need several moves | | `mouse_move` | `coordinate` | Hover without clicking | | `cursor_position` | none | Report where the cursor is, as text | | `scroll` | `scroll_direction` (`up`, `down`, `left`, `right`), `scroll_amount` (wheel clicks, 1 to 50), optional `coordinate` | Scroll | | `type` | `text` | Type text at the keyboard focus | | `key` | `text` (a key or combo such as `Return`, `Tab`, `ctrl+a`), optional `repeat` | Press keys | | `hold_key` | `text` (a key or combo), `duration` (seconds, up to 30) | Hold keys down, then release them | | `wait` | `duration` (seconds, up to 30) | Pause | | `zoom` | `region` (`[x0, y0, x1, y1]`) | Return that part of the screen enlarged to the display size, to read small text | | `navigate` | `url` | Load a page | Example call:
```json
{ "action": "left_click", "coordinate": [412, 230] }
```
## Configuration | Field | Default | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `display_width` | `1280` | Display width in pixels (320 to 1920) | | `display_height` | `800` | Display height in pixels (320 to 1200) | | `screenshot_after_action` | `true` | Return a screenshot after every action. When off, only `screenshot` returns an image. | | `max_actions_per_session` | `300` | Hard cap on actions in one session, screenshots included | | `native_tools` | `true` | Use the provider’s native computer tool on models that have one. When off, every model uses the `computer` function tool. | Screenshots are billed as image tokens. A smaller display, or turning off `screenshot_after_action`, lowers the cost per step. ## Safety * **The model sees everything on the screen.** Text on a page can try to steer the agent. The capability tells the model to treat screen contents as untrusted and to stop and ask before typing credentials, making purchases, sending messages, or confirming irreversible actions. Add the `soft_approval` capability when you want those confirmations recorded, and the [`tool_approval`](https://everruns.com/docs/capabilities/tool-approval/) capability when a person must approve every `computer` call before it runs. * **Soft approval, no built-in hard gate.** No `computer` call waits for a person by default, whether it clicks, types, presses Enter, navigates, or carries a provider safety check. Approval rests on the stop-and-ask rule above, recorded with `soft_approval`. Add `tool_approval` when every call must be approved before it runs. * **Keep credentials out of reach.** Do not give a computer-use agent a browser that is signed in to accounts it should not use. * **Egress.** `navigate` refuses private and internal addresses and follows the session’s network access list. Everruns makes every request the page makes and applies the same rules to each one, including redirects and DNS answers. If a page navigates somewhere blocked on its own, the page is reset to a blank page and the action reports an error. * **Budget.** `max_actions_per_session` stops runaway loops. Each screenshot shows as a thumbnail on the tool call in the session view; click it for the full frame. ## Desktop in a Sandbox To give the agent a full Linux desktop instead of a browser page, turn on **Desktop** in a Daytona, E2B or Isolated sandbox [Sandbox Template](https://everruns.com/docs/features/sandbox-templates/#desktop). The Agent then gets the same `computer` tool, driving the desktop of the Session’s own Sandbox, so the shell, the files and the desktop are one machine, and the template’s outbound network rule covers the desktop too. It takes the same configuration as `computer_use`. * There is no `navigate` action: the agent opens a browser on the desktop and types the address. * A template with a desktop replaces `computer_use`: both provide the `computer` tool. Saving an agent, harness, or session with `computer_use` and `sandbox_desktop` together fails with an error naming the two. * On Daytona, every action goes through the sandbox’s Computer Use API, so typed text and key names reach the desktop as data and never pass through a shell, and `zoom` returns the region at its own size.
---
# Container Sandbox
> Self-hosted Linux container per session through the Docker Engine API, with shell execution, file I/O, and file transfer to session storage.
Source:
| | | | ---------------- | ------------------------------------------------------------------ | | **ID** | `container_sandbox` | | **Category** | Execution | | **Features** | `leased_resources` | | **Dependencies** | [Storage](https://everruns.com/docs/capabilities/session-storage/) | | **Risk** | High | Container Sandbox gives an agent a Linux container to run code in. The platform talks to a Docker Engine you operate over its REST API, so no sandbox vendor is involved. Each session gets at most one container, on its own Docker network. **Off by default.** Set `FEATURE_CONTAINER_SANDBOX=prod` on the server and on every worker to register the capability and enable it by default for organisations. Use `dev` for local development or `preview`/`adoption` for explicit enrolment. Each capability has its own grade; the Docker flag does not enable the sandbox. ## Setup 1. Run a Docker Engine the server and workers can reach. 2. Set `CONTAINER_SANDBOX_DOCKER_HOST` to its `http://` or `https://` URL, on the server and every worker. 3. Set `FEATURE_CONTAINER_SANDBOX=prod` in the same places. 4. Add `container_sandbox` to a custom agent or harness. For coding work, inherit [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) and optionally add [GitHub Scout](https://everruns.com/docs/capabilities/github-scout/). Without `CONTAINER_SANDBOX_DOCKER_HOST` the client defaults to `unix:///var/run/docker.sock`. The client cannot use a Unix socket yet, so every tool call then fails with an error asking for an `http(s)://` host. This is deliberate: it never falls back to an unauthenticated TCP endpoint. Use `https://` with mutual TLS for any Docker daemon that is not on loopback, and never expose a plaintext Docker port on a network. ## Tools | Tool | Parameters | What it does | | -------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `sandbox_create` | `image` (optional) | Creates the session’s network and container and starts it | | `sandbox_exec` | `command`, `working_dir`, `output` | Runs a shell command and returns stdout, stderr, and the exit code | | `sandbox_read_file` | `path`, `offset`, `limit` | Reads a text file as a line window (`limit` defaults to 2000 lines). For a binary file it returns only the size | | `sandbox_write_file` | `path`, `content` | Writes text to a file, replacing it in full | | `sandbox_upload` | `session_path`, `container_path` | Copies a file from session storage into the container, byte for byte | | `sandbox_download` | `container_path`, `session_path` | Copies a file out of the container into session storage, where it outlives the container | | `sandbox_list` | none | Lists the session’s sandbox with its state | | `sandbox_manage` | `action`: `stop`, `start`, or `remove` | `stop` keeps the filesystem, `start` runs it again, `remove` deletes the container, its network, and every file that was not downloaded | The capability’s system prompt describes the lifecycle (`sandbox_create`, then exec and file tools, then `sandbox_manage` with `remove`) and tells the agent to remove the sandbox when it is done. ## Container defaults | Setting | Value | | ----------------- | ------------------------------------------------------ | | Image | `ubuntu:24.04`, unless `sandbox_create` passes `image` | | Working directory | `/workspace` | | Memory limit | 2 GiB | | CPU limit | 1 CPU | | Process limit | 256 | | Runtime | The Docker daemon’s default runtime (normally `runc`) | | Network | A bridge network per session, named after the session | These values are fixed in the platform. The capability takes no configuration, and the image is the only setting a tool call can change. Exec output and file transfers are capped at 8 MiB per response, and a single file transfer at 4 MiB. Each create, exec, and start refreshes a 20-minute lease on the container in the session’s leased resources. ## Security * Each session’s container runs on its own Docker network, and container and network names are derived from the session ID. * Memory, CPU, and process limits are applied through cgroups. * The Docker socket is never mounted into a container. * No egress filtering is applied. A container can reach whatever its bridge network routes to, including private address ranges and cloud metadata endpoints. Restrict egress at the network or firewall layer. * `runc` shares the host kernel. For untrusted or multi-tenant workloads, configure a hardened default runtime on the Docker daemon, such as `sysbox-runc`, gVisor, or Kata. ## See also * [Daytona](https://everruns.com/docs/capabilities/daytona/) and [E2B](https://everruns.com/docs/capabilities/e2b/), hosted sandbox providers * [Storage](https://everruns.com/docs/capabilities/session-storage/), where uploaded and downloaded files live
---
# Current Time
> Read the current date and time in a chosen format and timezone.
Source:
| | | | ---------------- | -------------- | | **ID** | `current_time` | | **Category** | Core | | **Features** | None | | **Dependencies** | None | Provides a tool to get the current date and time. Supports multiple formats and timezones. ## Tools ### `get_current_time` Get the current date and time. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------- | | `timezone` | string | no | IANA timezone (e.g., `America/New_York`, `Europe/London`) | | `format` | string | no | Output format: `iso8601`, `unix`, `human` | ## See Also * [Schedules](https://everruns.com/docs/capabilities/session-schedules/), schedule future tasks * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Data Knowledge
> Mount a read-only /knowledge/ Open Knowledge Format scaffold for table docs, business rules, and validated SQL, used by the Data Analyst harness.
Source:
| | | | ---------------- | ------------------------------------------------------------------ | | **ID** | `data_knowledge` | | **Category** | Data | | **Tools** | None | | **Features** | `file_system` | | **Dependencies** | [File System](https://everruns.com/docs/capabilities/file-system/) | | **Risk** | Low | The `data_knowledge` capability mounts a read-only `/knowledge/` directory into the session and tells the agent to read it before writing SQL. The directory is shaped as an [Open Knowledge Format](https://everruns.com/docs/how-to/share-knowledge-with-okf/) (OKF) bundle: Markdown files with YAML frontmatter, navigated through `index.md` files. The [Data Analyst](https://everruns.com/docs/built-ins/harnesses/data-analyst/) harness includes it. ## What gets mounted
```text
/knowledge/
index.md # OKF root index (okf_version "0.1")
tables/index.md # how to document a table or data source
business/index.md # how to document metrics and business rules
queries/index.md # how to document validated query patterns
```
Each `index.md` explains what belongs in its directory. The mount is a fixed, read-only scaffold built into the capability: the agent cannot write to it, and the capability has no configuration for adding your own files to it. To give the agent your organization’s curated data knowledge, put it in a [Knowledge Base](https://everruns.com/docs/capabilities/knowledge-base/) (OKF bundles import directly) or in an organization [Memory](https://everruns.com/docs/capabilities/memory/) mounted under `/workspace`. ## System prompt The capability adds one instruction: curated data knowledge is mounted at `/knowledge/{tables,business,queries}`, and the agent should read it before writing SQL and treat it as ground truth for schema semantics, metrics, and validated queries. ## Configuration None.
```json
{ "ref": "data_knowledge" }
```
## See also * [Data Analyst harness](https://everruns.com/docs/built-ins/harnesses/data-analyst/) * [Share knowledge with OKF](https://everruns.com/docs/how-to/share-knowledge-with-okf/) * [Knowledge Base](https://everruns.com/docs/capabilities/knowledge-base/)
---
# Daytona
> Run agent code in Daytona cloud sandboxes with command execution, file access, git, workspace downloads, and session-scoped lifecycle controls.
Source:
| | | | ---------------- | ---------------------------------------------------------------------------- | | **ID** | `daytona` | | **Category** | Sandboxes | | **Features** | None | | **Dependencies** | [`session_storage`](https://everruns.com/docs/capabilities/session-storage/) | Run code in cloud sandboxes powered by [Daytona](https://www.daytona.io/). An agent can create several isolated Linux environments per session, each with network access, then execute commands, manage files, clone repositories, and download results. The capability is marked experimental and may change. ## Set up 1. In the [Daytona Dashboard](https://app.daytona.io), open **API Keys** in your account settings, select **Create New API Key**, and copy the key. 2. In Everruns, open **Settings → Connections**, find **Daytona**, select **Connect**, and paste the key. Once connected, agents with the Daytona capability can use the tools below. ## Tools ### `daytona_create_sandbox` Create and start a new sandbox. | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `title` | string | no | Sandbox name | | `size` | string | no | `small` (1 vCPU, 1 GiB RAM, 3 GiB disk, default), `medium` (2 vCPU, 4 GiB, 8 GiB), or `large` (4 vCPU, 8 GiB, 10 GiB) | | `snapshot` | string | no | Daytona snapshot name; overrides `size` | | `auto_stop_minutes` | integer | no | Minutes of inactivity before auto-stop, 1 to 60 (default 5) | | `upload_files` | array | no | `{session_path, sandbox_path}` pairs to copy from session storage | ### `daytona_exec` Run a shell command in a sandbox and wait for it. | Parameter | Type | Required | Description | | ------------ | ------- | -------- | ---------------------------------------------- | | `sandbox_id` | string | yes | Target sandbox | | `command` | string | yes | Shell command to execute | | `cwd` | string | no | Working directory (default: sandbox workspace) | | `timeout` | integer | no | Timeout in milliseconds (default 300000) | ### `daytona_read_file` Read a file from a sandbox. | Parameter | Type | Required | Description | | ------------ | ------- | -------- | -------------------------------------------- | | `sandbox_id` | string | yes | Target sandbox | | `path` | string | yes | File path | | `offset` | integer | no | Zero-based line offset to start reading from | | `limit` | integer | no | Maximum number of lines to return | ### `daytona_write_file` Write a file to a sandbox. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------- | | `sandbox_id` | string | yes | Target sandbox | | `path` | string | yes | File path | | `content` | string | yes | File content | ### `daytona_download_workspace` Download a sandbox directory to session storage. | Parameter | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------ | | `sandbox_id` | string | yes | Target sandbox | | `sandbox_path` | string | no | Root path in the sandbox (default: workspace path) | | `session_path` | string | no | Destination in session storage (default: `/workspace`) | ### `daytona_list_snapshots` List available Daytona snapshots (names, CPU, memory, and disk specs, state). Use a snapshot name as the `snapshot` parameter of `daytona_create_sandbox`. Takes no parameters. ### `daytona_list_sandboxes` List all sandboxes for the current session. Takes no parameters. ### `daytona_manage_sandbox` Stop or delete a sandbox. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------ | | `sandbox_id` | string | yes | Target sandbox | | `action` | string | yes | `stop` or `delete` | ### `daytona_git_clone` Clone a git repository into a sandbox. Uses your connected GitHub credentials for private repositories. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------------------------------------- | | `sandbox_id` | string | yes | Target sandbox | | `repo_url` | string | yes | Repository URL or `user/repo` shorthand | | `branch` | string | no | Branch to clone (default: the default branch) | | `path` | string | no | Clone destination (default: `/home/daytona//`) | ### `daytona_git_credentials` Configure git credentials in a sandbox so later `git push`, `pull`, and `fetch` commands run through `daytona_exec` authenticate. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------- | | `sandbox_id` | string | yes | Target sandbox | ### `daytona_api_call` (opt-in) Call any Daytona REST endpoint directly, for operations the dedicated tools do not cover. Only available when the capability config sets `enable_api_calling` to `true`. Authentication headers are injected automatically, and the Daytona OpenAPI spec is mounted at `/daytona/openapi.yaml`. | Parameter | Type | Required | Description | | --------- | --------------- | -------- | -------------------------------------------------------------------------------------- | | `method` | string | yes | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` | | `path` | string | yes | Management API path (`/sandbox/...`) or Toolbox API path (`/toolbox/{sandbox_id}/...`) | | `body` | object or array | no | JSON request body | ## Config
```json
{
"enable_api_calling": true
}
```
`enable_api_calling` is the only setting, and it defaults to `false`. ## Git * `daytona_git_clone` uses your connected GitHub account, so private repositories clone without extra setup. When no person is in the run, or the person has not connected GitHub, it uses the agent’s GitHub connection. * For push, pull, or fetch, call `daytona_git_credentials` once after creating the sandbox, then run git commands with `daytona_exec`. * Tokens written into the sandbox only reach repository contents: `daytona_git_clone`’s token covers the cloned repository alone, and `daytona_git_credentials` covers contents of every repository the connection reaches. Neither can open issues or review pull requests. * Repository arguments accept `user/repo` shorthand instead of full URLs. ## Sandbox lifecycle Sandboxes auto-stop after 5 minutes of inactivity by default as a safety net. Delete sandboxes when you are done: stopping only pauses a sandbox, and it stays visible in your Daytona dashboard. All sandbox-scoped tools require a `sandbox_id`. The exceptions are `daytona_create_sandbox`, `daytona_list_sandboxes`, and `daytona_list_snapshots`. ## Security * API keys are encrypted at rest (AES-256-GCM envelope encryption). * Each sandbox is isolated from other sandboxes and the host. * Git credentials are short-lived and scoped to the sandbox. * Sandbox state is stored in encrypted session secrets. ## See also * [Sandbox Templates](https://everruns.com/docs/features/sandbox-templates/#desktop): start the Session Sandbox with a desktop the agent drives with the `computer` tool. * [Storage](https://everruns.com/docs/capabilities/session-storage/): API key and state persistence. * [Daytona documentation](https://www.daytona.io/docs) * [Integrations](https://everruns.com/docs/integrations/): every vendor integration. * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Dry Run
> Try an agent without its side effects. Read-only tools run for real; every other tool call returns a simulated result and changes nothing.
Source:
| | | | ---------------- | --------- | | **ID** | `dry_run` | | **Category** | Safety | | **Tools** | None | | **Features** | None | | **Dependencies** | None | Dry run lets you see what an agent would do before it does it. A session with this capability runs tools that only read, and answers every other tool call with a simulated result. Nothing is sent, written, or deleted. The **Test run** button on an agent’s page starts a session with dry run on. ## What runs for real A tool runs for real when it declares itself read-only and nothing marks it destructive or requiring approval. MCP tools declare this through their own annotations or through a [risk label](https://everruns.com/docs/reference/cli/mcp-servers/) set on the connection. Every tool that does not declare itself read-only is simulated: a dry run errs on the side of not acting. ## What a simulated call returns The call is recorded as a successful result with a `dry_run` object that names the tool and its arguments:
```json
{
"dry_run": {
"simulated": true,
"tool": "visti_send",
"arguments": { "text": "main CI is red" },
"note": "Dry run: `visti_send` was not executed. Nothing was changed."
}
}
```
The agent is told it is in a dry run. It carries on as if simulated calls worked, so the rest of the run is exercised, and its final answer lists the actions it would have taken. The session trace marks simulated calls. ## Configuration Dry run has no settings. Add it to a session’s capabilities:
```json
{ "capabilities": [{ "ref": "dry_run" }] }
```
---
# E2B Sandboxes
> Run agent code in isolated E2B cloud sandboxes with your own API key, command execution, file access, and session-scoped lifecycle management.
Source:
## Framework Enable the `e2b` Cargo feature and bind application-owned services with `.e2b(credentials)`. See [Framework services](https://everruns.com/docs/framework/native-services/) for credentials, persistence and a complete real-model example. The remaining setup sections describe the hosted Platform. | | | | ---------------- | ---------------------------------------------------------------------------- | | **ID** | `e2b` | | **Category** | Sandboxes | | **Features** | None | | **Dependencies** | [`session_storage`](https://everruns.com/docs/capabilities/session-storage/) | Run code in cloud sandboxes powered by [E2B](https://e2b.dev/docs). An agent can create, pause, resume, delete, and work in several isolated Linux sandboxes per session. Sandboxes are tracked per session. You bring your own E2B API key. There is no platform-owned or environment-variable fallback, so sandbox costs and quotas stay in your own E2B account. ## Set up 1. In the [E2B Dashboard](https://e2b.dev/dashboard), create an API key and copy it. 2. In Everruns, open **Settings** > **Connections**, find **E2B**, select **Connect**, and paste the key. Every E2B operation requires a user-provided key. If none is configured, the agent shows an inline connection prompt. ## Tools ### `e2b_create_sandbox` Create a new E2B sandbox. Returns `sandbox_id` and connection details. | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------------------------------- | | `title` | string | no | Human-readable sandbox name | | `template` | string | no | E2B template ID (default `base`) | | `timeout_seconds` | integer | no | Sandbox TTL in seconds (default `3600`) | | `env_vars` | object | no | Environment variables injected into the sandbox | | `upload_files` | array | no | `{session_path, sandbox_path}` pairs to copy from session storage | ### `e2b_exec` Execute a shell command in a sandbox, capturing stdout, stderr, and the exit code. | Parameter | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------- | | `sandbox_id` | string | yes | Target sandbox | | `command` | string | yes | Shell command to run | | `cwd` | string | no | Working directory | | `timeout_ms` | integer | no | Command timeout in milliseconds | ### `e2b_read_file` Read a text file from a sandbox filesystem. | Parameter | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------- | | `sandbox_id` | string | yes | Target sandbox | | `path` | string | yes | File path | | `offset` | integer | no | Line offset to start reading from | | `limit` | integer | no | Maximum number of lines to return | ### `e2b_write_file` Write a text file into a sandbox filesystem. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------- | | `sandbox_id` | string | yes | Target sandbox | | `path` | string | yes | File path | | `content` | string | yes | File content | ### `e2b_list_sandboxes` List all E2B sandboxes created in the current session. Takes no parameters. ### `e2b_manage_sandbox` Pause, resume, or delete an E2B sandbox. | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------ | | `sandbox_id` | string | yes | Target sandbox | | `action` | string | yes | `pause`, `resume`, or `delete` | | `timeout_seconds` | integer | no | Timeout to apply when resuming | ## How it works E2B exposes two surfaces, and the capability uses both: * **Management API** (`api.e2b.app`): sandbox lifecycle, metadata, and timeout control. * **envd sandbox endpoint**: in-sandbox file access and command execution. Per-sandbox state (sandbox ID, domain, access token, workspace path, timeout) is stored in encrypted session secrets and registered as a leased resource, so orphaned sandboxes are cleaned up on the worker side. Every sandbox is tagged with Everruns ownership metadata (session, harness, org, and agent IDs) for dashboard traceability and audit review. File operations target the sandbox filesystem, not the session workspace. Each sandbox has internet access. Use `e2b_manage_sandbox` to delete sandboxes when you are done. ## Security * API keys resolve fresh from your user connection on each tool call. They are never stored in sandbox state or env vars, and never appear in tool output. * envd access tokens are session-scoped and stored only in encrypted session secrets (AES-256-GCM envelope encryption). * Sandbox isolation depends on E2B’s runtime boundaries plus Everruns session-scoped secret lookups. * E2B timeouts and auto-pause, plus Everruns leased-resource cleanup, limit resource leaks. ## See also * [Storage](https://everruns.com/docs/capabilities/session-storage/): API key and state persistence. * [E2B documentation](https://e2b.dev/docs) * [Integrations](https://everruns.com/docs/integrations/): every vendor integration. * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# File System
> Read, write, search, and manage files in an isolated per-session workspace, with glob, grep, and directory operations.
Source:
| | | | ---------------- | ------------------------------------- | | **ID** | `session_file_system` | | **Category** | File Operations | | **Features** | `file_system` (enables the Files tab) | | **Dependencies** | None | Provides tools to access and manipulate files in the session workspace. Each session has an isolated filesystem rooted at `/workspace`. Files persist for the session duration. `read_file` and `write_file` return a `content_hash` (`sha256:...`) so agents can make freshness-checked `edit_file` calls. ## Tools ### `read_file` Read the contents of a file. Successful responses include `content_hash`. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | `path` | string | yes | Absolute path (e.g., `/workspace/src/main.py`) | ### `read_many_files` Read 2-10 independent files in one ordered call. Only batch paths known before the call; if one file reveals another path, read it in a later call. Results keep per-file success or error details. Images return metadata only; read them individually with `read_file`. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------- | | `paths` | array | yes | Ordered list of 2-10 absolute paths | | `offset` | integer | no | Starting line applied to every file (0-indexed, default 0) | | `limit` | integer | no | Max lines per file | ### `write_file` Create or overwrite a file. Parent directories are created automatically. Successful responses include `content_hash`. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `path` | string | yes | Absolute path | | `content` | string | yes | File content | ### `edit_file` Apply one or more exact text replacements to an existing text file. This tool is text-only, requires the current `content_hash` from `read_file` or `write_file`, and uses compare-and-set semantics so concurrent writes fail cleanly instead of clobbering newer content. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `path` | string | yes | Absolute path to an existing text file | | `expected_hash` | string | yes | Current `content_hash` (`sha256:...`) | | `edits` | array | yes | One or more `{ old_text, new_text }` replacements matched against the original file. Use a single-element array for one replacement. | If `old_text` has no exact match, the error identifies the failed edit and may show up to three similar lines with line numbers. These are recovery hints only: read the file again and copy the exact text before retrying. The hint search is bounded and may omit distant or long lines. A substantial, unique whole-line `new_text` match may suggest that this edit was already applied, but does not establish its intended location or completion of other edits. Failed batches write nothing. Legacy top-level `old_text`/`new_text` are still accepted for backward compatibility, they are folded into `edits[]`, but new callers should always use `edits[]`. ### `list_directory` List files and directories at a given path. | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------- | | `path` | string | yes | Directory path | ### `grep_files` Search file contents with regex patterns. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------- | | `pattern` | string | yes | Regex pattern | | `path` | string | no | Directory to search (default: `/workspace`) | ### `glob` List files recursively under `/workspace` whose relative paths match a glob. Results are sorted and bounded. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------- | | `pattern` | string | yes | Glob relative to `/workspace` | | `limit` | integer | no | Maximum matches, from 1 to 1000 (default: 200) | ### `grep` Search UTF-8 files recursively under `/workspace` with a Rust regular expression. This is the provider-neutral search name used by managed Environments; `grep_files` remains available for existing file-system agents. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------- | | `pattern` | string | yes | Rust regular expression | | `glob` | string | no | Restrict searched files with a glob | | `offset` | integer | no | Skip this many matches (default: 0) | | `limit` | integer | no | Maximum matches, from 1 to 1000 (default: 200) | ### `delete_file` Delete a file or directory. | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------- | | `path` | string | yes | Path to delete | ### `stat_file` Get file metadata (size, type, timestamps). | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------ | | `path` | string | yes | Path to stat | ## `edit_file` request example
```json
{
"path": "/workspace/app.py",
"expected_hash": "sha256:1c4d...",
"edits": [
{
"old_text": "return 'Hello, World!'",
"new_text": "return 'Hello from Everruns!'"
}
]
}
```
## Notes * All paths must be under `/workspace` * Files are session-scoped, no cross-session access * Parent directories are auto-created on write * `edit_file` only works on text files and rejects binary/base64 content * `edit_file` applies all replacements against the original file content and rejects ambiguous or overlapping matches * `edit_file` preserves the file’s existing BOM and newline style (`LF`, `CRLF`, or `CR`) * `edit_file` returns a unified diff capped to a bounded size; oversized diffs are truncated and marked as such * Shared filesystem with [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/) (same `/workspace`) ## See Also * [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), execute commands against these files * [Storage](https://everruns.com/docs/capabilities/session-storage/), key/value and secret storage * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# GitHub
> Read and review GitHub pull requests with inline comments, keep one comment per pull request up to date, and file deduplicated issues.
Source:
| | | | ---------------- | ----------------------------------- | | **ID** | `github` | | **Category** | Integrations | | **Features** | `github` Cargo feature in Framework | | **Dependencies** | None | The GitHub capability gives an agent what it needs to work on one pull request: read it, read its diff, review it with inline comments, and leave a comment it can keep editing. It can also file findings as issues without duplicating them. Pair it with a GitHub trigger to build a pull request reviewer, or with a schedule trigger and a sandbox to build a security scanner. The [PR Reviewer and Security Scanner templates](https://everruns.com/docs/how-to/set-up-review-and-security-agents/) do both for you. ## Framework Enable the `github` Cargo feature and add `everruns::github::GitHub` to an agent. The Framework adapter accepts application-owned credentials and is read-only by default; explicit options add write tools. It also exposes repository search and file reads directly. See [Framework GitHub tools](https://everruns.com/docs/framework/github/) for its tool selection, token providers, and runnable PR reviewer. The following sections describe the hosted Platform capability, including its connection identities, triggers, and managed sandbox checkout. ## Tools | Tool | What it does | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_github_pull_request` | Title, description, author, state, branches, size, and up to 100 changed files. | | `get_github_pull_request_diff` | The unified diff, cut to `max_bytes` (default 60,000, at most 200,000). `truncated` says whether it was cut. | | `github_checkout_pull_request` | Checks the pull request out into the session’s [managed sandbox](https://everruns.com/docs/features/sandbox-templates/), or copies its files into the session files on Bashkit, private repositories included. See [Check out a pull request](#check-out-a-pull-request). | | `upsert_github_comment` | Posts a Markdown comment, or edits the one it posted earlier with the same `marker` (default `summary`). | | `submit_github_pull_request_review` | Submits one review (`COMMENT` or `REQUEST_CHANGES`; it cannot approve) with a summary and inline comments on changed lines. | | `upsert_github_issue` | Files a finding as an issue keyed by a `fingerprint`; updates the open issue for the same fingerprint, leaves a closed one closed. | | `create_github_pull_request` | Opens a pull request (draft by default) from a branch already pushed to the same repository. Only offered when `allow_pull_requests` is on. | | `mark_github_pull_request_ready` | Takes a draft pull request out of draft. Only offered when `allow_merge` is on. | | `merge_github_pull_request` | Merges a pull request that GitHub reports ready to merge. Only offered when `allow_merge` is on. See [Merge a pull request](#merge-a-pull-request). | The pull request tools take `repo` (`owner/repo`) and `number`. ### Merge a pull request `merge_github_pull_request` takes `head_sha`, the full head commit the agent read with `get_github_pull_request`, and merges only that commit: if someone pushed since, the merge is refused. `method` is `squash` (default), `merge` or `rebase`, and `commit_title` and `commit_message` set the resulting commit. GitHub decides whether the pull request may merge. The tool merges only when `mergeable_state` (also returned by `get_github_pull_request`) is `clean`: not a draft, no conflicts, required reviews in, and no failing or pending check on the head commit. Anything else is refused with the reason, and there is no argument to override it. Set what “ready” requires with branch protection on GitHub; the tool cannot bypass it. The agent cannot approve its own pull request, so a required review still needs a person. ### Check out a pull request `github_checkout_pull_request` fetches the pull request’s head and its base branch into `/workspace/` (or `path`, which must stay inside `/workspace`) and leaves the head checked out at a detached HEAD, so `bash` can build, test and diff it:
```json
{
"repo": "acme/app",
"number": 42
}
```
It returns `path`, `head_sha`, `base_ref` and `base_sha`; `depth` (default 100) sets how much history is fetched. This git checkout needs the Managed Sandbox (`session_sandbox`) capability on a Sandbox Worker. Without a managed sandbox, as on the Bashkit Worker harness, the tool copies the head’s text files into the session files at the same path instead, where `bash` (`grep`, `rg`, `find`, `cat`) and the file tools read them. That copy is a snapshot, not a repository: there is no git history, so get the change itself from `get_github_pull_request_diff`. Binary files and files over `max_file_kib` (default 1024) are skipped and counted in `skipped`; `paths` limits the copy to some files or directories, for example `["AGENTS.md", "crates/core"]`, and leaves the rest of an earlier copy in place. The token stays on the host, so a personal token or `GITHUB_TOKEN` session secret works here too. The result has `"mode": "files"`. The git checkout requires a GitHub App installation. The trusted resolver must supply installation-mint evidence that the token covers exactly this repository, grants only **Contents: read**, **Pull requests: read** and GitHub’s implicit **Metadata: read**, and expires within one hour. Missing evidence, personal OAuth tokens and `GITHUB_TOKEN` session-secret fallbacks are refused before any credential reaches the sandbox. This also fails closed with older control planes. For personal-token workflows, use `github_get_pull_request` and `github_get_pull_request_diff` to review on the trusted host, or connect an App installation for checkout. The tool hands the admitted token with **Contents: read** and **Pull requests: read** for that one repository to a single `git fetch` through a temporary file it removes before returning, so the token is not in `.git/config`, in later `bash` commands, or in sandbox checkpoints. Plain `git fetch` in `bash` therefore works only for public repositories; call the tool again to refresh a checkout. Concurrent code in the sandbox can read the temporary file; the enforced repository, permission and expiry limits bound this accepted exposure. ### Reviews without repeats Each inline comment from `submit_github_pull_request_review` starts with a hidden `` line. Pass a short, stable `key` per finding (such as `null-deref-parse-config`); a key the agent already posted on the pull request is skipped, so a review after a new push only adds what is new. A second review of the same head commit is skipped entirely, which makes webhook redeliveries harmless. Comments on lines that are not part of the diff would make GitHub reject the whole review, so the tool moves them into the review summary instead. Only comments, reviews and issues written by a bot count as the agent’s own, so a person cannot hide a finding by pasting a marker into their own comment. ## Settings | Setting | Default | Effect | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `acts_as` | `agent` | Whose GitHub identity the tools use: `agent`, `person`, or `person_or_agent`. See [Authentication](#authentication). | | `allow_pull_requests` | `false` | Adds `create_github_pull_request`. Pushing the branch also needs the GitHub App’s **Contents: write** permission. | | `allow_merge` | `false` | Adds `mark_github_pull_request_ready` and `merge_github_pull_request`. Merging also needs the GitHub App’s **Contents: write** permission. Independent of `allow_pull_requests`. | | `private_issues_only` | `false` | `upsert_github_issue` refuses public repositories, so a finding is never disclosed in a public issue. | `upsert_github_comment` starts the comment with a hidden `` line and looks for it on the next run, so an agent that runs on every push updates one comment instead of adding a new one each time. Use a different marker for each kind of comment. ## Authentication The tools act on GitHub as the identity `acts_as` names; only `person_or_agent` ever uses a second one: * `agent` (default) uses the agent’s own GitHub connection: its GitHub App when you connected one, so comments are posted as the agent’s bot and the tools reach only the repositories the App is installed on. An agent that chose **Use the Everruns app** acts as the shared Everruns App’s bot on the account an org admin linked. Use it for bots, and for anything triggered without a person. * `person` uses the GitHub connection of the person talking to the agent. Use it for a personal agent. A triggered run has no person, so it gets nothing. * `person_or_agent` uses the person’s connection when they have one, otherwise the agent’s. Each call gets a short-lived token limited to the one repository it names and the permissions that tool needs: the read tools ask for **Pull requests: read**, the checkout tool for **Contents: read** and **Pull requests: read**, the comment tool for **Issues** and **Pull requests: write**, the review tool for **Pull requests: write**, the issue tool for **Issues: write**, and `create_github_pull_request` for **Pull requests: write** and **Contents: read**, `mark_github_pull_request_ready` for **Pull requests: write**, and `merge_github_pull_request` for **Pull requests: write** and **Contents: write**. Without a connection for that identity the tools return `connection_required`. The session’s network access policy must allow `https://api.github.com/` when one is set.
---
# GitHub Scout
> Blueprint-only GitHub repository exploration capability that spawns read-only scout subagents.
Source:
| | | | ---------------- | ----------------------------------------------------------------- | | **ID** | `github_scout` | | **Category** | Integrations | | **Features** | None | | **Dependencies** | [`subagents`](https://everruns.com/docs/capabilities/sub-agents/) | GitHub Scout lets an agent spawn a specialist subagent for read-only GitHub repository exploration. The host agent receives `spawn_agent` with `target.type: "subagent"` through the dependency on `subagents`; monitoring and steering are handled by the generic `session_tasks` tools (`list_tasks`, `get_task`, `message_task`, `cancel_task`). The GitHub API tools stay private inside the spawned `github_scout` blueprint session. ## How to Use Enable the `github_scout` capability on an agent or harness. Then spawn the blueprint:
```json
{
"name": "spawn_agent",
"arguments": {
"name": "Scout",
"instructions": "Find where authentication middleware is implemented.",
"target": { "type": "subagent" },
"blueprint": "github_scout",
"config": {
"repos": ["fastify/fastify"]
}
}
}
```
The optional `repos` config scopes GitHub searches to `owner/repo` repositories. Config is validated against the blueprint’s schema before the child session is created: entries that are not `owner/repo` and unrecognized config keys are rejected with a schema error instead of being silently ignored. ## Private Blueprint Tools These tools are available only inside the GitHub Scout child session: | Tool | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `search_github_code` | Search code with GitHub code search qualifiers such as `repo:`, `path:`, `language:`, `symbol:`, and `filename:` | | `read_github_file` | Read a UTF-8 file from a repository by `repo`, `path`, and optional `ref` | | `search_github_issues` | Search issues and pull requests with qualifiers such as `repo:`, `is:issue`, `is:pr`, `state:`, `author:`, and `label:` | ## Authentication GitHub Scout uses the existing GitHub user connection. In local and compatibility flows, tools can also use a `GITHUB_TOKEN` session secret. Missing credentials return a connection prompt instead of asking for tokens in chat. ## Included Examples The adoptable **Coding (Daytona)** and **Coding (Container)** harness examples include `github_scout`, so coding agents based on those examples can delegate GitHub repository lookup work to Scout. ## See Also * [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), lifecycle tools used to spawn and manage Scout * [Author an agent blueprint](https://everruns.com/docs/framework/agent-blueprints/), how Scout and blueprints like it are built * [Capabilities Overview](https://everruns.com/docs/capabilities/), full capability catalog
---
# Guardrails
> Config-driven checks that constrain agent behavior, inspecting model output and tool activity, then blocking or logging when content matches a rule.
Source:
| | | | ---------------- | ------------------------------------------ | | **ID** | `guardrails` | | **Category** | Safety | | **Tools** | None | | **Dependencies** | Utility LLM (only for model-backed checks) | | **Risk** | Low | Guardrails are checks that constrain what an agent does. Where most [capabilities](https://everruns.com/docs/capabilities/) *grant* an ability, a guardrail *restricts* one: it inspects model output and tool activity, then **blocks** or **logs** when content matches a rule. Guardrails are opt-in. An agent with no guardrails is a fully supported configuration, there is no org-mandated enforcement layer. A [harness](https://everruns.com/docs/features/harnesses/) can attach guardrail capabilities as soft defaults that flow to every agent built on it, and an author can still remove them. This is the platform stance: guardrails are a default posture, not a cage. The `guardrails` capability holds no rules of its own. Its per-agent config is a declarative list of checks plus a mode; the capability compiles that config and contributes the matching runtime hooks. An empty config (or the capability being absent) contributes nothing, with zero added latency. ## Concepts A **check** binds a **rule** to a **stage** with an **on-fail action**. ### Stages | Stage | What it sees | | ------------- | ---------------------------------------------------------------------- | | `output` | Streamed assistant text | | `tool_use` | A tool call before it executes, the tool name and serialized arguments | | `tool_output` | A tool result before it enters model context | `tool_output` is the trust boundary for untrusted external content (web pages, MCP responses); indirect-injection and secret-leakage checks belong there. ### Rules | Rule (`type`) | What it matches | Valid stages | Execution | | -------------- | -------------------------------------------------------------------- | --------------- | ------------------- | | `regex` | Any of the patterns matches the stage text | all | in-process, sync | | `blocklist` | Any word/phrase appears as a substring (case-insensitive by default) | all | in-process, sync | | `tool_pattern` | The tool name matches a `*`-wildcard glob | `tool_use` only | in-process, sync | | `llm_judge` | A natural-language policy, evaluated by a system model | all | async, model-backed | | `mcp` | Decision delegated to an external guardrail served over scoped MCP | all | async, off-platform | | `moderation` | The finalized message scored against content categories | `output` only | async, model-backed | Deterministic rules (`regex`, `blocklist`, `tool_pattern`) run in the streaming and per-tool-call hot path, linear-time, no I/O, with hard limits on check count, entries, and lengths so an authored pattern can never wedge a worker. Model-backed and MCP rules run only in the async hook path (and, for `output`, on a post-generation end-of-message boundary), never on the sync hot path. On `output` they inspect the finished message once, after streaming, and a block replaces the whole message; an `mcp` check there receives `tool: null`. ### Engines The two model-backed types, `llm_judge` and `moderation`, choose which system model answers them with `engine`: * **`utility_llm`** (the default) prompts your org’s utility model for a verdict — `allow`/`block` for a judge, 0-100 scores per category for moderation. One request per check. * **`jev`** asks [Jev](https://everruns.com/docs/integrations/typesafe/), TypeSafe’s System One model, a typed question and gets a calibrated probability back. The `threshold` you configure (a percentage, default 50) decides the verdict, and every jev check on a stage is answered in a **single** request. It needs `UTILITY_TYPESAFE_API_KEY` on the deployment, or `UTILITY_DECISION_DRIVER=llm` to have the utility model answer the same questions (a yes/no label rather than a calibrated probability, so the threshold then only checks which answer it picked).
```json
{
"stage": "tool_use",
"type": "llm_judge",
"engine": "jev",
"threshold": 70,
"prompt": "Block any tool call that deletes customer records."
}
```
Two reasons to prefer `jev` once your deployment has a key configured. It is cheaper on latency: four judge checks on a tool call cost one round trip instead of four. And the verdict is yours — the model reports how likely a violation is, your threshold decides what to do about it, and there is no written verdict to misparse. For moderation it also reads the *tail* of the distribution rather than a score: content that is probably fine but 30% likely to be a clear violation trips a 30% threshold, where an averaged score would hide it. `utility_llm` stays the default, so existing configs are unchanged. Both engines fail open, honor `on_fail` and advisory mode identically, and send the same bounded excerpt. A check set to `jev` in a deployment with no TypeSafe key configured is skipped with a warning. #### Use your organization’s decision model By default, `jev` checks use the deployment’s decision model. An organization can answer them with its own model instead: pick a **Default decision model** on the Models page, then set **System decisions** to **This organization’s model** (or `PATCH /v1/orgs/{org}` with `"system_decisions": "organization"`). The checks then run on your provider account, count against the session’s budget, and show up in its usage, the same as the `jev_decision` tool. Once you opt in, the deployment’s model is never used for your checks. If your default decision model is missing, disabled, or failing, `jev` checks fail open with a warning. Switch back with `"system_decisions": "deployment"`. ### On-fail * `block`, suppresses the matched content: an `output`/`tool_output` block replaces the content with a notice; a `tool_use` block refuses the call and feeds the reason back to the model, which can self-correct. The model’s original tokens are never persisted. * `log`, records the hit and continues. An optional per-check `replacement` customizes the block notice or user-facing refusal message. ### Mode: active vs. advisory A config-level `mode` is `active` (default) or `advisory`. **Advisory downgrades every hit to `log`**: checks run and are recorded, but nothing is blocked. Advisory is how you tune a guardrail against false positives before enforcing it. Mode is per attachment, so the same catalog entry can be advisory on one agent and active on another. ## Config shape Config is a `GuardrailsConfig` stored under the `guardrails` capability in the agent’s config. Field names are `snake_case`; each check names its rule with a `type` tag alongside the shared `stage` / `on_fail` / `replacement` fields:
```json
{
"mode": "active",
"checks": [
{
"id": "no-secrets-in-output",
"stage": "output",
"on_fail": "block",
"replacement": "[Response withheld: appears to contain a credential.]",
"type": "regex",
"patterns": ["AKIA[0-9A-Z]{16}", "ghp_[A-Za-z0-9]{36}"]
},
{
"id": "no-shell",
"stage": "tool_use",
"on_fail": "block",
"type": "tool_pattern",
"tools": ["bash*", "*exec*"]
}
]
}
```
The `id` is optional but recommended, it is surfaced in reason codes and logs. ## Data egress and failure behavior * **Deterministic checks** (`regex`, `blocklist`, `tool_pattern`) run entirely in-process; no data leaves the platform. * **`llm_judge` and `moderation`** send a bounded content excerpt to a system model: with `engine: "utility_llm"`, your org’s *own* configured utility LLM, the same provider the agent already uses; with `engine: "jev"`, the deployment’s decision model, or your organization’s default decision model when **System decisions** is set to it. Either way it is an operator-configured destination, not a per-agent one. * **`mcp`** sends a bounded content excerpt to an external, operator-configured MCP guardrail endpoint. Tenant scoping is enforced by the host’s per-session scoped-MCP resolver, so a config can only reach servers scoped to its own session/org. Every async check is bounded (10 s timeout; at most 4 utility-LLM calls per tool call or finalized message, and one batched request for all `jev` checks on a stage) and **fails open**: a timeout, error, or unparseable verdict defaults to `allow`. A guardrail outage, or a hostile MCP endpoint, can only ever *allow*, never make execution more permissive than the no-guardrail baseline in a way that blocks a healthy turn. Model-backed checks flow through utility-LLM accounting, not the session model budget. ## Tuning: dry-run and advisory Two surfaces let you tune checks before enforcing them: * **`POST /v1/capabilities/guardrails/dry-run`** evaluates a config against sample text for a given stage, with no session and nothing persisted. It returns the triggered checks (id, rule type, effective action, reason code, matched excerpt) and whether the content would be blocked. It runs only deterministic checks, it never makes a network call, so it is the fast false-positive tuning loop for `regex`/`blocklist`/`tool_pattern`. * **Advisory mode** runs the full set (including model-backed checks) against real traffic in `log`-only form, so you can review what *would* have been blocked before switching to `active`. ## The gallery: ready-made presets Rather than authoring checks from scratch, list the **guardrail gallery**: a read-only catalogue of adoptable presets:
```plaintext
GET /v1/capabilities/guardrails/examples
```
Each listing carries a full `config` plus trust metadata so a picker can show what a preset does before adoption: | Field | Meaning | | ------------- | ------------------------------------------------------------------------------------------- | | `check_types` | The rule-type composition (e.g. `["regex"]`, `["llm_judge"]`) | | `stages` | Which stages the preset’s checks run in | | `data_egress` | `none` for deterministic presets; `utility_llm` when a preset contains a model-backed check | `data_egress` is **derived from the check types**, not hand-authored, so it stays correct as presets mix deterministic and model-backed checks. Adoption is client-side config composition: drop a preset’s `config` into the agent’s `guardrails` capability config (merging or replacing checks). The capability settings on an agent or harness do this in the editor: add a preset to append its checks, or add a check and set its rule, stage, and what happens on a match. There is no new persisted resource and no import endpoint. Noisy presets (PII, prompt-injection heuristics) ship `log`-only so they are safe to adopt active and tune before switching individual checks to `block`. Shipped presets include secret detection, a model-backed secret-leak judge, PII detection, a profanity starter, dangerous-shell blocking, shell-access blocking, and prompt-injection heuristics. ### Worked example: deterministic vs. model-backed secret guardrails Two presets guard the same risk, a secret reaching output or leaving through a tool, by complementary means. **`secret-detection`** matches known credential *formats* by pattern. It is in-process and reports no egress:
```json
{
"name": "secret-detection",
"check_types": ["regex"],
"stages": ["output", "tool_output"],
"data_egress": "none"
}
```
It blocks well-known formats (AWS, GitHub, Slack, Google keys, PEM private keys) in model output and in tool results before they reach context. High-precision, safe to run active. **`secret-leak-judge`** catches secrets by *intent*, including an opaque value whose form is unknown at config time (e.g. one freshly read from a secrets manager), which a regex structurally cannot see:
```json
{
"name": "secret-leak-judge",
"check_types": ["llm_judge"],
"stages": ["tool_use", "tool_output"],
"data_egress": "utility_llm"
}
```
Its `llm_judge` policy blocks a tool call (or result) that would print, echo, log, or transmit secret material in cleartext, while allowing comparisons that reveal only a hash, fingerprint, or redacted form. Because it sits on `tool_use` with `on_fail: block`, a blocked call is **recoverable**: the refusal reason is fed back and the model self-corrects to a safe form (comparing a hash instead of printing the secret). It is model-backed, so `data_egress` is `utility_llm`, adopters are correctly warned that a bounded excerpt leaves the generating path for evaluation. Run it advisory first to tune false positives. The two are meant to be layered: pattern-matching for known formats, the judge for everything else. ## Reason codes Every block or log carries a stable `guardrail.` code (e.g. `guardrail.regex`, `guardrail.llm_judge`, `guardrail.moderation`). Clients localize copy from the code rather than the human-readable text. (The separate [Prompt Canary Guardrail](https://everruns.com/docs/capabilities/prompt-canary-guardrail/) capability uses its own `system_prompt_leak` code.) ## Endpoints | Method | Path | Description | | ------ | -------------------------------------- | -------------------------------------------------------- | | `GET` | `/v1/capabilities/guardrails/examples` | List adoptable gallery presets with trust metadata | | `POST` | `/v1/capabilities/guardrails/dry-run` | Evaluate a config against sample text; nothing persisted | Both are gated by the same `capability.view` policy as other capability reads. ## Related * [Prompt Canary Guardrail](https://everruns.com/docs/capabilities/prompt-canary-guardrail/), a narrow streaming-output guardrail for naive system-prompt leakage. * [Agent Checks](https://everruns.com/docs/features/agent-checks/), advisory, config-*time* review of an agent’s setup. Distinct from guardrails, which enforce at *runtime*.
---
# Host Shell
> Run bash commands on the machine hosting the agent, bounded by a kernel policy (Landlock and seccomp on Linux, Seatbelt on macOS).
Source:
| | | | ---------------- | -------------------------------------------------------------------------------------------------------- | | **ID** | `host_shell` | | **Category** | Execution | | **Risk** | High | | **Features** | `file_system` (enables the Files tab) | | **Dependencies** | [`session_file_system`](https://everruns.com/docs/capabilities/file-system/), backed by a real directory | **Availability:** Framework (embedder) only. Not available in self-hosted Platform or the Everruns demo instance. Run bash commands as real child processes on the machine the agent is running on. Unlike [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), the toolchain is real: compilers, package managers and test runners work. A kernel policy bounds what those processes may write and whether they may reach the network. ## When to use this instead of Bashkit Both capabilities contribute a tool named `bash` over the session workspace, so enable one or the other, not both. | | Bashkit Shell | Host Shell | | ------------------ | ------------------------------------ | ------------------------------------ | | Where commands run | In-process interpreter | This machine, as child processes | | Native binaries | No | Yes | | Workspace | Session filesystem (virtual or real) | Must be a real directory | | Boundary | The interpreter, by construction | Landlock + seccomp, or Seatbelt | | Network | Off, or egress-routed HTTP | Denied unless containment is removed | Given a virtual session filesystem, `host_shell` refuses and says so rather than inventing a host path. ## Tools ### `bash` Execute a shell command or a multi-line script. | Parameter | Type | Required | Description | | --------------------- | ------ | -------- | ------------------------------------------------------- | | `command` | string | yes | Shell command(s) to execute | | `working_dir` | string | no | Directory to run in (default: the workspace root) | | `sandbox_permissions` | string | no | `use_default` or `require_escalated` | | `justification` | string | no | User-facing reason for `require_escalated` | | `output` | string | no | Output verbosity (`auto`, `normal`, …; default: `auto`) | `commands` is accepted as an alias for `command`, so an agent written against Bashkit Shell keeps working when the backend is swapped. Returns `stdout`, `stderr`, `exit_code`, `success`, and the `containment` that was in force. A failure that the containment would explain is flagged with `containment_denial: "likely"`. Output streams live to the UI and CLI while the command runs, and long scripts can run detached. Every call is a fresh non-interactive `bash -lc` (PowerShell on Windows) rooted at the workspace, so no working directory, variable or export survives between calls. ## Containment Configured per agent, never by the model. | Mode | Reads | Writes | Network | | --------------------------- | ---------- | ------------------------------------------------- | ------- | | `read-only` | the host | private temp only | denied | | `workspace-write` (default) | the host | workspace, `/tmp`, private temp, configured roots | denied | | `danger-full-access` | everything | everything | allowed | Host **reads** are allowed in every contained mode, for toolchain compatibility. The policy stops writes and network exfiltration; it does not stop a command reading unrelated files on the machine. That is the threat model, stated rather than implied. The environment a command inherits is an allowlist: `PATH`, locale, and toolchain variables survive; `HOME` and `TMPDIR` are replaced with a private per-process directory, and everything else, including every API key and agent socket path, is dropped. Two platform differences are deliberate: * `.git` below the workspace is read-only on macOS. Landlock path rules are additive and cannot subtract it, so Linux permits Git metadata writes inside the workspace. * Windows has no containment implementation. Every mode there runs uncontained, and the capability says so. On macOS and Linux, containment fails closed: if the OS primitive is unavailable, the command returns a setup error and is not retried on the host. ## Configuration
```json
{
"containment": "workspace-write",
"approval": "never",
"writable_roots": ["/var/cache/agent"],
"foreground_timeout_secs": 120,
"background_timeout_secs": 86400,
"max_output_bytes": 1048576
}
```
An unknown `containment` or `approval` name is rejected rather than defaulted, so a misspelled boundary cannot resolve to a wider one. `writable_roots` adds directories a build needs to write beyond the workspace, a package cache for example. It is ignored at `read-only`. ## Approvals | Policy | When a person is asked | | ----------------- | --------------------------------------------------------------------------------- | | `never` (default) | never; a request to escalate is refused | | `on-failure` | when a command fails in a way the containment would explain | | `on-request` | when the model sets `sandbox_permissions: require_escalated` with a justification | | `untrusted` | for anything outside a small read-only command set | That set is one literal command whose options cannot start another program. `rg --pre`, `rg -z`, and `rg --hostname-bin` ask for approval. `git status` asks unless the same command disables repository fsmonitor and hooks (`-c core.fsmonitor=` and `-c core.hooksPath=/dev/null`), because those settings run code during status. Every policy except `never` needs the host to supply an approval gate. Without one, a policy that would ask refuses instead: an unattended worker has nobody to ask, and a refusal is more honest than a silent escalation. Regardless of policy, a command that visibly signals the agent’s own process is refused before it is spawned. ## Deployment This is an embedder capability, not a hosted-product one. It ships in `everruns-core` (`host` feature) behind the `host-shell` feature (also reachable as `host-shell` on the `everruns` facade) and is deliberately absent from the hosted catalog: handing agents arbitrary host processes is something a CLI host, a CI runner, or an operator’s own box opts into, not something a shared multi-tenant worker should offer. On Linux the kernel policy is applied by a helper process, selected with the `launcher` config key: | `launcher` | Meaning | | ---------------------------- | -------------------------------------------------------------- | | `"discover"` (default) | find `everruns-sandbox-exec` beside the binary, then on `PATH` | | `{"helper": ""}` | run that binary | | `{"reexec_self": [""]}` | re-exec this binary with those leading arguments | `everruns-core` (`host` feature) ships `everruns-sandbox-exec` under the same feature, but cargo does not build a dependency’s binaries, so a single-binary host will not find one beside it. Such a host routes the arguments into `everruns_core::host::containment::worker::run_from_args` from its own `main` and selects `reexec_self`. See the [Host Shell Agent example](https://everruns.com/docs/framework/examples/host-shell-agent/). ## See Also * [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), the sandboxed interpreter * [File System](https://everruns.com/docs/capabilities/file-system/), file operations on the same workspace * [Daytona](https://everruns.com/docs/capabilities/daytona/) and [E2B](https://everruns.com/docs/capabilities/e2b/), real binaries on someone else’s machine * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Image Generation
> Generate and edit images, animated GIFs and SVGs with GPT Image 2.6 or any image model your organization has, and keep them as artifacts or workspace files.
Source:
| | | | ---------------- | ------------------ | | **ID** | `image_generation` | | **Category** | Media | | **Features** | None | | **Dependencies** | None | Image Generation gives an agent two tools, `generate_image` and `edit_image`. It draws stills (PNG, JPEG, WebP), animated GIFs and SVG vector images. New agents built from the Worker kit get it by default, and so does platform chat. The default model is [GPT Image 2.6 Flare](https://openai.com/index/introducing-images-2-6/). GPT Image 2.6 Sunburst, earlier GPT Image models and Meta’s Muse Image work too. ## Choosing the model The model comes from the first of these that is set: 1. The capability’s `model` setting on the agent. It accepts a model from the organization’s catalog (pick one in the agent’s capability settings) or a model name such as `gpt-image-2.6-sunburst`. 2. The organization’s **Default image model**, set under **Models → Defaults → Images** or with `everruns models images-default set `. 3. GPT Image 2.6 Flare. Image models appear on the Models page under the **Images** filter, with GIF, SVG and Edit badges showing what each one supports. A model name is served by the first provider that has it: OpenAI, then Azure OpenAI, then OpenRouter for GPT Image models, and Meta or OpenRouter for Muse Image. A provider that cannot produce the requested format is skipped: OpenRouter serves GPT Image 2.6 as PNG, JPEG and WebP only, so GIF and SVG need an OpenAI or Azure OpenAI provider. When no provider serves the chosen GPT Image model and `fallback` is `"auto"` (the default), the capability uses Muse Image on a Meta or OpenRouter provider instead. ## Settings
```json
{
"model": "gpt-image-2.6-flare",
"default_format": "png",
"default_quality": "medium",
"complexity": "low",
"gif_frames": 9,
"gif_frame_ms": 160,
"partial_images": 1,
"output_dir": "/workspace/images",
"fallback": "auto"
}
```
| Setting | Meaning | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `model` | Image model. Empty means the organization default. | | `default_format` | `png` (default), `jpeg`, `webp`, `gif` or `svg`, when a call does not choose. | | `default_quality` | `medium` (default), `low`, `high`, `xhigh`, `max` or `auto`. `xhigh` and `max` need GPT Image 2.5 or newer; a model without them uses its own default. | | `complexity` | `low`, `medium` or `high`: how much detail GPT Image 2.5 and newer put into a scene. Lower is faster. | | `gif_frames` | Frames in a GIF, 2 to 64. The model default is 9. | | `gif_frame_ms` | How long each GIF frame shows, 20 to 2000 ms. The model default is 200 ms. | | `partial_images` | 0 to 3 streamed progress updates for a single still image. | | `output_dir` | Session folder for saved images. Defaults to `/workspace/.outputs/images`. | | `fallback` | `auto` or `off`, see above. | ## Animated GIFs Ask for `format: "gif"` and describe the motion in the prompt. The model draws every frame in one request, so a GIF costs one call. The frame count sets the frame size, so `size` is ignored for GIFs. GIFs are generated, not edited, and each call makes one. The GIF is stored as an image artifact, and chat plays it with its frame count and loop length, a pause button and a download link. Chat models only accept still images, so the agent itself sees the first frame. ## SVG `format: "svg"` returns one vector image. SVGs are never kept as image artifacts, since an SVG served from the image endpoints could carry script. They are always written to the session filesystem and the tool result gives the path. ## Tools ### `generate_image` | Parameter | Type | Description | | -------------------- | ------- | ------------------------------------------------------- | | `prompt` | string | What to draw. For a GIF, describe the motion. Required. | | `format` | enum | `png`, `jpeg`, `webp`, `gif`, `svg` | | `frames` | integer | GIF frames, 2 to 64 | | `frame_duration_ms` | integer | GIF frame duration, 20 to 2000 ms | | `quality` | enum | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | | `complexity` | enum | `low`, `medium`, `high` | | `size` | enum | `1024x1024`, `1536x1024`, `1024x1536`, `auto` | | `background` | enum | `transparent`, `opaque`, `auto` | | `count` | integer | 1 to 10 stills. GIF and SVG make one. | | `save_to_session_fs` | boolean | Also save each image to the session filesystem | | `output_dir` | string | Session folder for saved images | | `filename_prefix` | string | Filename prefix | | `persist_artifact` | boolean | Keep each image as an artifact (default `true`) | ### `edit_image` Takes the same parameters except `frames` and `frame_duration_ms`, plus: | Parameter | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | `prompt` | string | The edit to make. Required. | | `image_id` | string | Image artifact to edit | | `path` | string | Session file to edit | | `markup_path` | string | A transparent PNG with drawn marks (circles, arrows, notes) showing where to change the image. GPT Image 2.6 only. | At least one of `image_id` or `path` is required. ## Result Both tools return the image for the model to see (the first frame for a GIF, nothing for an SVG) and JSON with the provider, model, format and token usage, and for each image its `artifact_id`, `session_file`, `filename`, `media_type`, `size_bytes`, `frames` and `revised_prompt` when present. ## Credentials and network Hosted Everruns resolves provider accounts on the server; the capability never reads provider keys from session secrets. In the [Framework](https://everruns.com/docs/framework/), enable the `images` feature and the capability reads `OPENAI_API_KEY` (and `OPENAI_BASE_URL`), `AZURE_OPENAI_API_KEY` with `AZURE_OPENAI_BASE_URL`, `OPENROUTER_API_KEY`, or `META_API_KEY` from the environment. Image requests leave through the platform’s outbound network boundary, like web fetch and MCP. The provider base URL must be allowed by the session’s network access policy and, when enabled, the system allowlist. Its hostname must resolve to public addresses only, and the connection is pinned to those addresses. Redirects from the image API are errors and never followed, so the provider key is only sent to the configured host. ## Notes * Transparent backgrounds need PNG, WebP or GIF * Higher quality and complexity take longer * Edit sources must be PNG, JPEG or WebP and at most 50 MB * `generate_image` and `edit_image` stay fully exposed when OpenAI `tool_search` is on ## See Also * [File System](https://everruns.com/docs/capabilities/file-system/), read and reuse workspace images * [Framework example](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/image_generation.rs), an agent that saves a GIF next to you * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Infinity Context
> Trim live prompt history and query older messages on demand, so conversation length is not bounded by the context window.
Source:
| | | | ---------------- | ------------------ | | **ID** | `infinity_context` | | **Category** | Optimization | | **Features** | None | | **Dependencies** | None | > **Deprecated configuration entry:** use [`compaction`](https://everruns.com/docs/advanced/compaction/) for managed long-session context. It includes permitted history retrieval and coordinates portable and native checkpoints. Existing `infinity_context` configurations remain supported. Used alone, this entry does not enable paid summaries. Limits the live prompt to recent conversation history while keeping older messages accessible through `query_history`. This is useful for long-running sessions where the agent should stay responsive without losing access to earlier decisions, identifiers, or requirements. ## Tools | Tool | Purpose | | --------------- | ------------------------------------------------------------ | | `query_history` | Search or retrieve earlier messages from the current session | ## How It Works 1. A message filter caps the number of recent messages sent to the model. 2. If older messages are excluded, the model sees a system notice telling it to use `query_history`. 3. The `query_history` tool can keyword-search history or fetch a specific absolute message range. ## Configuration Default configuration:
```json
{
"capabilities": ["infinity_context"]
}
```
Custom budget:
```json
{
"capabilities": [
{
"ref": "infinity_context",
"config": {
"context_budget_tokens": 80000,
"min_recent_messages": 12
}
}
]
}
```
| Field | Type | Default | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------- | | `context_budget_tokens` | integer | `100000` | Approximate token budget reserved for message history | | `min_recent_messages` | integer | `10` | Minimum recent messages to keep even when the budget is tight | ## Limitations * Search is keyword-based, not semantic; database-backed hosts use indexed full-text search * Search and range retrieval use bounded storage queries over retained session history, including messages still visible in the prompt * Budgeting uses token estimates, not guaranteed provider token counts ## See Also * [Context Compaction](https://everruns.com/docs/advanced/compaction/), The replacement capability for managed long-session context * [Capabilities Overview](https://everruns.com/docs/capabilities/) * [Harnesses](https://everruns.com/docs/features/harnesses/)
---
# Knowledge
> Attach versioned file collections to agents, browse originals and extracted text, and optionally index them for keyword or hybrid retrieval.
Source:
## Framework Enable the `knowledge` Cargo feature and bind application-owned services with `.knowledge(collection)`. See [Framework services](https://everruns.com/docs/framework/data-services/) for credentials, persistence and a complete real-model example. The remaining setup sections describe the hosted Platform. Knowledge brings notes, uploaded files, repository trees and Everruns documentation into one collection model. Indexing is optional. Files remain available to browse, read and grep when indexing is off. Open **Knowledge** and create a collection. A collection opens on a file browser: upload files or a folder with its relative paths, or create Markdown files with optional OKF frontmatter, on its **Files** tab, and connect a source on **Sources**. Search accounts for indexed collections live on the **Accounts** tab of the Knowledge page. GitHub sources reuse existing organization or virtual-user GitHub connections. Public HTTPS Git repositories work without a GitHub connection. Source roots must not overlap, and a connected source cannot overwrite a managed file. ## Attach to an agent Add the **Knowledge** capability and select collections in the agent editor, or use this capability reference:
```json
{
"ref": "knowledge",
"config": {
"collections": ["everruns-docs"],
"automatic": false,
"limit": 8
}
}
```
`everruns-docs` is predefined, requires no credentials, and contains a snapshot of the documentation bundled with the server. Indexing starts off. Managers may enable it like any other collection. The agent sees read-only mounts: * `/knowledge/index.md`: the attached collection catalog. * `/knowledge//`: original files, with their hierarchy preserved. * `/knowledge-text//`: extracted text where available. The existing **Data Knowledge** capability keeps its read-only `/knowledge/{tables,business,queries}` scaffold. Its index and the collection catalog share `/knowledge/index.md`; collection ID subtrees always use live collection permissions, including when a collection is detached. Directory listings and grep scoped to a Knowledge path include both sources. Read indexes first, then individual files as needed. An authored `index.md` is preserved; collections without one receive a bounded generated index. Use `browse_knowledge` or `knowledge files` to page through larger directories without enabling indexing. Request metadata only when needed; metadata pages are separately bounded. Knowledge bindings belong to the calling session, including when several sessions share a workspace. Sharing workspace files does not share Knowledge attachments. ## Ownership and attachment scope Collections, their indexes and search-provider accounts belong to an organization. Users manage them through organization permissions; a personal GitHub connection supplies source credentials, not a private user index. Attach collections through the **Knowledge** capability on a harness, agent or session. Configuration follows the existing capability precedence: harness, then agent, then session. A higher layer replaces the lower layer’s configuration for that capability, so list every collection the session should retain. Collections are shared rather than copied or reindexed for each agent or session. Runtime tools, Bashkit search, automatic retrieval and mounts use the calling session’s effective collection bindings and live file visibility. There are no separate user-, agent- or session-owned Knowledge indexes, and an agent does not automatically search every collection in its organization. Sharing a workspace does not share its sessions’ Knowledge bindings. ## Search and grep Choose **Off**, **Keyword**, or **Hybrid** in collection settings. Hybrid needs an enabled embedding model and a persistent Turbopuffer backend. Keyword indexing works with Turbopuffer or the local PostgreSQL full-text fallback. PostgreSQL stores catalog rows, fragment offsets and local lexical postings, not canonical passage text or binary payloads. Collections using a remote indexer keep their postings there. The `search_knowledge` tool accepts a query, optional collection subset, path prefix, user metadata filter, result limit and `lexical_only` flag. Requested collections are always intersected with the session’s current bindings. Returned passages carry immutable file/version IDs, source locators and extracted-text offsets. Bashkit uses the same retrieval service:
```bash
knowledge files --collection kn_0123456789abcdef0123456789abcdef --path /policies --limit 50
knowledge search --limit 5 'refund policy'
knowledge search --collection kn_0123456789abcdef0123456789abcdef --lexical 'retention'
knowledge search --metadata '{"team":"support"}' 'refund policy'
grep -n 'retention' /knowledge/kn_0123456789abcdef0123456789abcdef/policies.md
```
Exact grep is independent of the index. Scope it to `/knowledge-text` to search extracted documents. Scans and returned data are bounded; narrow the path if a scan exceeds its budget. With `automatic: true`, Everruns retrieves a small amount of relevant evidence for the incoming user message before model execution. Evidence is retained by input ID for replay, checked against live visibility, and added as source data. Retrieval has a five-second timeout and does not prevent a turn from running when unavailable. Query embedding calls use session usage events; ingestion embeddings are attributed to the organization. ## Content and metadata Original bytes are retained for every format. Markkit extracts HTML, DOCX and spreadsheets. Text and code retain their original UTF-8 representation. Markdown frontmatter, including OKF fields and unknown extensions, is preserved alongside user annotations. Links and file paths remain source-relative. OKF remains a directory of original files: concept Markdown, reserved `index.md` navigation, `log.md` history and binary assets all round-trip through uploads/downloads or a Git source. Unknown frontmatter fields remain intact, including BOM/CRLF files; there is no conversion into fixed entry kinds. `GET /v1/knowledge/{collection_id}/okf` validates a page of OKF v0.2 metadata and reserved-file structure. Follow `next_cursor` to validate the rest of a large catalog. This checks metadata requirements, not every Markdown link or authored index entry. Unsupported binaries, including PDFs, images, audio and video, remain downloadable. This release does not provide PDF extraction, OCR, transcription or multimodal embeddings. Files exceeding the extraction budget remain stored and report that state rather than disappearing. Collection rules independently exclude paths from ingestion, indexing or agent reads. File controls can disable indexing or agent reads without removing the original. Managers can annotate connected files; their source content stays read-only. ## Incremental processing and storage Sync compares Git blob identities before uploading content artifacts. Changed files receive immutable versions; unchanged files retain their version and citations. Extraction is reused for metadata-only edits, and embeddings are cached by organization, model profile and passage hash. Source deletions apply only after a successful complete traversal. Leased jobs renew during source fetches and indexing, retry interrupted work, and index generations publish after the catalog’s visibility checks pass. Uploads and downloads stream in bounded segments. Content uses the configured S3-compatible blob store; local development falls back to `KNOWLEDGE_STORAGE_ROOT` (default `.local/knowledge`). Use shared object storage for multiple server replicas. Back up the database and content store together. Organization search accounts reference encrypted, write-only organization service credentials. A revoked or invalid selected credential fails closed; it never falls back to the deployment account. Embedding provider credentials are configured separately in the model catalog. Embedding usage preserves the serving provider account for background indexing and query-time calls, so host-managed usage stays distinct from your own keys. Deployment-owned index backends can also record the resource quantities reported by the search provider. Your hosting service controls the prices and credit policy; self-hosted Knowledge does not require a billing service. ## Current bounds File catalogs paginate at up to 500 rows; pass `tree=true` to list one folder at a time (its files plus one entry per subfolder). Agent directory listings cap at 500 children, file reads at 1 MiB, extraction at 8 MiB, and exact grep at 5 MiB of scanned content, 5,000 candidate files and a 512 KiB per-file ceiling. Streamed originals have a 1 TiB per-file transfer ceiling; this is a safety limit, not a tested capacity claim. Git fetching streams shallow snapshot packs directly into the object store, with the existing 512 MiB pack limit. A synthetic million-file catalog and bounded streamed-original fixture qualify catalog/transfer behavior; these do not establish end-to-end terabyte indexing throughput. Source refresh is explicit. Retained versions currently have no automatic expiry; monitor content storage and keep it with database backups. Additional source adapters and document extractors can use the same collection boundary. Management APIs are under `/v1/knowledge` and `/v1/knowledge-indexers`; the generated command catalog exposes the corresponding `everruns knowledge` commands. Organization settings permissions govern management, and explicit agent/session bindings govern runtime reads. A read-only personal access token can browse, download, validate metadata and search; file changes, source refresh and configuration require a full-access token. ## Deployment storage Knowledge originals and extracted text need shared, persistent content storage on hosted replicas. `KNOWLEDGE_STORAGE_BACKEND=s3` uses the existing `STORAGE_S3_*` configuration for Knowledge alone, even while `STORAGE_BLOB_BACKEND=db` keeps workspace files and image bytes inline in PostgreSQL. It does not backfill or move existing files. The default `inherit` uses the existing shared blob backend or the local development fallback. Do not use the local fallback on ephemeral hosted containers. An invalid explicit S3 configuration fails startup; storage errors never silently switch to local disk.
---
# Knowledge Base
> The undeployed split knowledge features have been consolidated into Knowledge.
Source:
Use [Knowledge](https://everruns.com/docs/capabilities/knowledge/) for notes, files, source trees and optional indexing. The former `knowledge_base` capability is no longer registered.
---
# Knowledge Index
> The undeployed split knowledge features have been consolidated into Knowledge.
Source:
Use [Knowledge](https://everruns.com/docs/capabilities/knowledge/) for notes, files, source trees and optional indexing. The former `knowledge_index` capability is no longer registered.
---
# Tool Loop Detection
> Detects an agent repeating the same tool calls, results, failed edits, or file reads, and injects a warning that tells it to change approach.
Source:
| | | | ---------------- | ---------------- | | **ID** | `loop_detection` | | **Tools** | None | | **Features** | None | | **Dependencies** | None | Tool loop detection watches the conversation for an agent that keeps doing the same thing without progress. When it finds a loop, it adds a short system message after the latest input telling the model what it is repeating and what to do instead: change the arguments, look at a different source, or report the blocker. It does not stop the turn, block a call, or change any tool result. The warning is rebuilt from the conversation each time messages are loaded for the model, so it is never stored in session history, and later requests replay the same prompt prefix. Conversation and both Worker levels include it, as do deprecated Generic and Platform Chat. ## What counts as a loop The checks run in this order, and the first match produces the warning: | Pattern | Triggers at | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | A mutating tool (`edit_file`, `write_file`, `delete_file`, `bash`, or an MCP tool ending in `__` plus one of those names) failing the same way with identical arguments, in consecutive calls | `mutating_failure_threshold`, default 2 | | The same tool call returning the same result, in consecutive calls since the last user message | `threshold`, default 3 | | Repeated reads of the same file (`read_file`, `read_many_files`) at the same offset, mixed with reads of other ranges of that file | `threshold`, default 3 | | The same batch of tool calls with identical arguments in consecutive assistant messages, regardless of call order inside the batch | `threshold`, default 3 | The lower threshold for failed mutations interrupts a broken edit or command before a third identical attempt with side effects. ## Configuration
```json
{
"ref": "loop_detection",
"config": { "threshold": 3, "mutating_failure_threshold": 2 }
}
```
| Field | Default | Description | | ---------------------------- | ------- | ----------------------------------------------------------------------------------- | | `threshold` | `3` | Repetitions of the same call batch, call result, or read range that count as a loop | | `mutating_failure_threshold` | `2` | Identical failed results from a mutating tool that count as a loop | Both must be integers of at least 1. In the [Framework](https://everruns.com/docs/framework/advanced-capabilities/), add it by ID:
```rust
use everruns::CapabilityRef;
use serde_json::json;
let agent = Agent::builder()
// ...
.capability(CapabilityRef::new("loop_detection").config(json!({ "threshold": 4 })))
.build()?;
```
## See also * [Tool Call Repair](https://everruns.com/docs/capabilities/tool-call-repair/), recovery for malformed tool-call arguments * [Conversation harness](https://everruns.com/docs/built-ins/harnesses/conversation/), the default foundation that includes it
---
# Memory
> Mount named organization Memories into the session workspace, read-only by default or read-write as shared working memory across sessions.
Source:
| | | | ---------------- | ------------------------------------------------------------------ | | **ID** | `memory` | | **Category** | Memory | | **Tools** | None | | **Features** | `file_system` | | **Dependencies** | [File System](https://everruns.com/docs/capabilities/file-system/) | | **Risk** | Medium | The `memory` capability mounts organization Memories into a session’s `/workspace`. A Memory is a named, durable file store owned by the organization. Once mounted, the agent reads and writes it with the ordinary [file tools](https://everruns.com/docs/capabilities/file-system/), so the capability adds no tools of its own. Use it for reference material that many sessions share, such as runbooks or product documentation, or for working files that should outlive one session. This capability selects **organization** Memories only. Agent memory (`/memory/agent`) and user memory (`/memory/user`) are mounted by the server without this capability. [Agent and User Memory](https://everruns.com/docs/features/memory-scopes/) explains the three scopes and their privacy rules. ## Configuration
```json
{
"ref": "memory",
"config": {
"mounts": [
{
"memory": "mem_0193f0c2a1b27c4e8f5d6a7b8c9d0e1f",
"path": "/workspace/runbooks",
"mode": "readonly"
}
]
}
}
```
| Field | Required | Description | | ----------------- | -------- | --------------------------------------------------------- | | `mounts[].memory` | Yes | Memory ID, `mem_` followed by 32 lowercase hex characters | | `mounts[].path` | Yes | Absolute path under `/workspace` where the Memory appears | | `mounts[].mode` | No | `readonly` (default) or `readwrite` | An empty config, or no `mounts`, is valid and mounts nothing. Validation rejects: * a path outside `/workspace` * two mounts with the same path * overlapping paths, where one mount path is a parent of another (`/workspace/data` and `/workspace/data/inner`) The `/memory/*` namespace is reserved for the server-managed scopes and cannot be used as a mount path here. ## Access modes * `readonly` mounts reject writes with an error from the file tools. * `readwrite` mounts write through to the durable Memory, so later sessions see the change. * Memories synced from GitHub or Git are always read-only, whatever mode the mount asks for. The mount set is captured when the session is created. Archiving or renaming a Memory later does not change what a running session mounted. ## Managing Memories Create Memories and edit their files in the **Memory** page of the UI or through the `/v1/memories` API. The [API reference](https://everruns.com/docs/api/) has the request shapes. ## See also * [Agent and User Memory](https://everruns.com/docs/features/memory-scopes/), the three memory scopes * [Knowledge Base](https://everruns.com/docs/capabilities/knowledge-base/), curated entries the agent searches instead of reading files * [Knowledge Index](https://everruns.com/docs/capabilities/knowledge-index/), semantic search over a synced source * [File System](https://everruns.com/docs/capabilities/file-system/), the tools that read and write mounted files
---
# Message Metadata
> Annotate user and agent messages with metadata such as their timestamp when they are sent to the LLM, so agents can reason about timing and gaps between messages.
Source:
| | | | ---------------- | ------------------ | | **ID** | `message_metadata` | | **Category** | Core | | **Features** | None | | **Dependencies** | None | Annotates user and agent messages with metadata, currently each message’s timestamp (UTC), when building the LLM request. The model sees each message prefixed with an annotation like:
```plaintext
[time 2026-06-11T09:15:42Z] What changed since yesterday?
```
For user messages the timestamp is when the message was received; for agent messages, when the reply was generated. This lets agents reason about timing: how long ago something was said, gaps between messages, and whether earlier statements are stale. Opt-in on the canonical levels. Included in deprecated Generic and Platform Chat. Annotations are applied only to the prompt-facing view of the conversation. Stored messages are never modified, and timestamps are stable across turns so prompt caching is unaffected. A short system prompt addition explains the annotation format to the model and instructs it not to emit annotations in its replies. ## Tools None. ## Configuration | Field | Type | Default | Description | | -------- | ----- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fields` | array | `["timestamp"]` | Metadata fields to render, in order. Supported: `timestamp`. An empty array disables annotations. More fields (e.g. the LLM model) will be added over time. | User and agent messages are always annotated; system and tool-result messages never are. ## See Also * [Current Time](https://everruns.com/docs/capabilities/current-time/), tool to get the current wall-clock time * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# OpenAI Server Tools
> Enable OpenAI's hosted tools (web search, code interpreter, hosted shell, file search, remote MCP) for agents on the OpenAI or Azure OpenAI Responses API.
Source:
| | | | ---------------- | ------------------------------------------------------------ | | **ID** | `openai_server_tools` | | **Category** | Tools | | **Features** | None | | **Dependencies** | None | | **Risk** | High (grants provider-executed web reach and code execution) | Enables [OpenAI’s hosted tools](https://platform.openai.com/docs/guides/tools) on agents whose model runs on the [OpenAI](https://everruns.com/docs/providers/openai/) or Azure OpenAI provider. OpenAI runs a hosted tool inside the same response: the model decides to search, OpenAI performs the search, and the answer comes back grounded in the results with its sources cited. The agent loop never dispatches the call, so there is no extra round-trip through Everruns. | Tool | What OpenAI runs | | ------------------ | ---------------------------------------------------- | | `web_search` | Searches the web and cites the pages it used | | `code_interpreter` | Python in an OpenAI-managed container | | `shell` | Shell commands in an OpenAI-managed container | | `file_search` | Retrieval over your OpenAI vector stores | | `mcp` | Calls to remote MCP servers you list, after approval | ## Tools None. This capability configures the OpenAI request, it does not provide client-side tools. Hosted calls appear in the session’s activity (see [Activity and cost](#activity-and-cost)); their results stay inside OpenAI’s response and reach the conversation only through the answer. Code interpreter and shell run in OpenAI’s container, not in the session’s Everruns sandbox: files they create are not in the session file system. Use Everruns’ own execution capabilities when the agent’s work must land there. ## Configuration ### Enable web search
```json
{
"capabilities": [
{
"ref": "openai_server_tools",
"config": { "tools": ["web_search"] }
}
]
}
```
### Tune web search
```json
{
"capabilities": [
{
"ref": "openai_server_tools",
"config": {
"tools": ["web_search"],
"web_search_context_size": "high",
"web_search_allowed_domains": ["openai.com", "everruns.com"],
"web_search_user_location": { "country": "US", "city": "Chicago", "timezone": "America/Chicago" }
}
}
]
}
```
### Code, shell, and file search
```json
{
"capabilities": [
{
"ref": "openai_server_tools",
"config": {
"tools": ["code_interpreter", "shell", "file_search"],
"container_memory_limit": "4g",
"file_search_vector_store_ids": ["vs_abc123"],
"file_search_max_results": 8
}
}
]
}
```
### Remote MCP
```json
{
"capabilities": [
{
"ref": "openai_server_tools",
"config": {
"tools": ["mcp"],
"mcp_servers": [
{ "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp" },
{
"server_label": "docs",
"server_url": "https://docs.example.com/mcp",
"allowed_tools": ["search"],
"require_approval": "never"
}
]
}
}
]
}
```
OpenAI connects to each server and asks before every call. The turn pauses with an approval card in the chat that shows the server, the tool, and the exact arguments; **Approve** runs the call and **Deny** lets the model answer without it. API clients see the request as a `tool.call_requested` event with an `openai_mcp_approval` call and answer it through `POST /v1/sessions/{id}/tool-results` with `{"approve": true}` or `{"approve": false}`. Any other result, an error included, denies. A server can skip approval with `"require_approval": "never"`, but only for an explicit `allowed_tools` list, so every unattended call is a tool you named. A `server_url` must be `https` and must not carry a username or password, so it suits public servers. A server that needs an API key or an OAuth connection is named by `mcp_server`, the name of an MCP server registered in Everruns, instead of a URL:
```json
{ "server_label": "linear", "mcp_server": "linear" }
```
Its URL and credentials come from the MCP server registration and the session’s connections on every call, exactly as for the agent’s own MCP tools, and never appear in agent config, events, or logs. If the connection is missing, the turn fails with a message naming where to connect it. Servers that bind secrets to tool parameters cannot be used this way, because OpenAI calls them directly. Config rules: * `tools`, array of hosted tool names: `web_search`, `code_interpreter`, `shell`, `file_search`, `mcp`. Other names are rejected on write. * `web_search_context_size`, `low`, `medium`, or `high`: how much retrieved context the model may use per search. OpenAI defaults to `medium`. * `web_search_allowed_domains`, bare domains (no scheme or path) that limit where results may come from. * `web_search_user_location`, optional `country` (two-letter ISO code), `region`, `city`, and `timezone` (IANA name) used to localize results. * `container_memory_limit`, `1g`, `4g`, `16g`, or `64g`: memory for the container that runs `code_interpreter` and `shell`. OpenAI defaults to `1g`; larger containers cost more. * `file_search_vector_store_ids`, OpenAI vector store ids (`vs_...`) in the same OpenAI account as the provider’s API key. Required when `file_search` is on. * `file_search_max_results`, 1 to 50 results per search. * `mcp_servers`, at least one server when `mcp` is on. Each has a unique `server_label` (letters, digits, `-`, `_`), either an `https` `server_url` or a registered `mcp_server` name, optional `allowed_tools`, and `require_approval` (`always`, the default, or `never`). Each option only takes effect when its tool is in `tools`. ## Provider support Hosted tools run only on the OpenAI and Azure OpenAI Responses API. On any other provider, including OpenAI-compatible gateways, the turn fails with a message that names the provider, instead of answering without the tools. Switch the agent’s model or remove the capability. For OpenRouter models, use [OpenRouter Server Tools](https://everruns.com/docs/capabilities/openrouter-server-tools/). Each model decides which hosted tools it supports; OpenAI rejects a request that asks a model for a tool it does not offer, and that error is shown on the turn. ## Security Hosted tools send conversation content to OpenAI-side tools. Web search gives the model **provider-executed web reach**, code interpreter and shell give it **code execution in an OpenAI container**, and file search reads whatever the listed vector stores hold. Remote MCP sends the model’s tool arguments to the servers you list, which are third parties to both OpenAI and Everruns; approval shows each call before it happens. OpenAI performs the requests, so Everruns’ own egress controls do not apply, the same data-exfiltration class as client-side [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/). The capability is rated **High risk** and uses the admin-only assignment gate. Grant it only to agents you trust with outbound web access and code execution, list only vector stores whose contents every user of the agent may see, and list only MCP servers you trust with the conversation. ## Activity and cost Each hosted call shows up in the session’s activity as it happens, through the `tool.hosted_call` event, with a short detail: the search query, the first line of code, the shell commands, the file search query, or the MCP server and tool. It is not an Everruns tool call: nothing is dispatched and no tool result is stored. OpenAI bills hosted tool calls per call on top of tokens. Session usage adds them to the estimated cost at OpenAI’s list price: $10 per 1,000 web searches on GPT-5 and newer reasoning models, $25 per 1,000 on GPT-4o and GPT-4.1, and $2.50 per 1,000 file searches. Code interpreter and shell are billed by OpenAI per container session rather than per call, so they are not in the estimate; check OpenAI’s usage dashboard for them. File search also bills vector store storage. ## See Also * [OpenAI provider](https://everruns.com/docs/providers/openai/) * [OpenRouter Server Tools](https://everruns.com/docs/capabilities/openrouter-server-tools/), the OpenRouter counterpart * [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/), the client-executed equivalent * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# OpenRouter Server Tools
> Enable OpenRouter's server tools (web search, web fetch, datetime, image generation and more), which OpenRouter runs before it returns the final answer.
Source:
| | | | ---------------- | ----------------------------------------- | | **ID** | `openrouter_server_tools` | | **Category** | Tools | | **Features** | None | | **Dependencies** | None | | **Risk** | High (grants provider-executed web reach) | Enables [OpenRouter’s provider-executed “server tools”](https://openrouter.ai/docs/guides/features/server-tools) (beta). Unlike normal [function tools](https://everruns.com/docs/features/capabilities/), these run **server-side by OpenRouter**: it loops internally and returns the final answer, so the agent loop never dispatches them. This capability contributes *request intent*, not executable tools, the selected tools are compiled into the OpenRouter request’s `tools` array as provider-executed entries. The concrete implementation lives in the focused `openrouter` feature of `everruns-integrations` crate; core carries only the provider-neutral routing contract. This is the OpenRouter counterpart to client-executed web access like [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/): the difference is *who runs the tool*. With server tools, OpenRouter performs the search or fetch and folds the results into the same generation, no extra round-trip through Everruns. Use it when your agents run on the [OpenRouter provider](https://everruns.com/docs/providers/openrouter/) and you want built-in web reach without wiring up a separate search [integration](https://everruns.com/docs/integrations/). ## Tools None, this capability configures the OpenRouter request, it does not provide client-side tools. The model invokes server tools during the generation and OpenRouter executes them; the only client-visible artifact is the final answer. ## Available server tools OpenRouter exposes these server tools. Enable any subset: | Tool | Name | What it does | | ---------------- | ------------------ | ------------------------------------------------------------------------------------------ | | Web Search | `web_search` | Searches the web and grounds the answer in results. Accepts an optional `max_results` cap. | | Web Fetch | `web_fetch` | Fetches and reads a URL the model chooses. | | Date & Time | `datetime` | Gives the model the current date and time. | | Image Generation | `image_generation` | Generates images inline. | | Apply Patch | `apply_patch` | Applies code patches. | | Fusion | `fusion` | OpenRouter’s Fusion tool. | | Advisor | `advisor` | OpenRouter’s Advisor tool. | | Subagent | `subagent` | Delegates to an OpenRouter-run subagent. | `web_search` is the only server tool that takes parameters today (`web_search_max_results`). Availability of each tool depends on the upstream model and OpenRouter’s beta rollout, see [OpenRouter’s server-tools docs](https://openrouter.ai/docs/guides/features/server-tools) for the current list. ## How it works 1. **Capability config → request intent**: the tools you enable are compiled into the OpenRouter routing config and serialized by the OpenRouter driver into the request’s `tools` array as `{"type":"openrouter:…"}` entries. 2. **OpenRouter executes server-side**: when the model decides to call a server tool, OpenRouter runs it, loops internally, and returns the final answer. The agent loop never sees an intermediate tool call. 3. **No-op off OpenRouter**: non-OpenRouter providers ignore the routing config entirely. Enabling this capability on a non-OpenRouter agent is a harmless no-op, so it is safe to leave on for agents that may switch providers. ## Configuration ### Enable web search
```json
{
"capabilities": [
{
"ref": "openrouter_server_tools",
"config": { "tools": ["web_search"] }
}
]
}
```
### Enable several tools and cap web-search results
```json
{
"capabilities": [
{
"ref": "openrouter_server_tools",
"config": {
"tools": ["web_search", "web_fetch", "datetime"],
"web_search_max_results": 5
}
}
]
}
```
Config rules: * `tools`, array of server-tool names from the table above. Unknown names are rejected on write. Duplicates are de-duplicated. * `web_search_max_results`, positive integer; only decorates `web_search`. It is ignored for every other tool and rejected when `< 1`. ## Security Enabling server tools grants the model **provider-executed web reach** (`web_search` / `web_fetch`). OpenRouter performs these requests, so Everruns’ own egress controls do not apply, the same data-exfiltration class as client-side [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/). The capability is therefore rated **High risk** and gated behind the same admin-only trust check as other outbound-web capabilities. Grant it only to agents you trust with outbound web access. ## Limitations * **OpenRouter only**: this is an OpenRouter request extension. Other providers ignore it (no error, no behavior change). * **Beta**: server tools are an OpenRouter beta; tool availability varies by upstream model and may change. * **Provider-side execution**: because OpenRouter runs the tools, their activity does not appear as Everruns tool calls. Inspect them in OpenRouter’s [dashboard logs](https://everruns.com/docs/providers/openrouter/#logs-traces-and-observability) instead. ## See Also * [OpenRouter provider](https://everruns.com/docs/providers/openrouter/), configure the provider these tools run on, plus OAuth, actual-cost reporting, and logs * [OpenRouter server-tools docs](https://openrouter.ai/docs/guides/features/server-tools), official OpenRouter guide * [Web Fetch](https://everruns.com/docs/capabilities/web-fetch/), the client-executed equivalent * [Integrations overview](https://everruns.com/docs/integrations/), search and web integrations as an alternative * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Output Truncation
> Chooses what a turn does when a model response hits the output token limit in the middle of a tool call, retry with a notice, fail, or carry on.
Source:
| | | | ---------------- | ------------------- | | **ID** | `output_truncation` | | **Category** | Safety | | **Features** | None | | **Dependencies** | None | | **Risk** | Low | A model response that reaches its output token limit (finish reason `length`) can stop in the middle of a tool call. Everruns never runs such a call, and never runs it with empty (`{}`) arguments in place of the ones the model did not finish. This capability chooses what the turn does next. On OpenAI Responses and Bedrock it also applies when a finished call arrives with arguments that are not valid JSON. Every agent gets the default policy, `continue`, without adding the capability. Add it only to change the policy or the retry limit. ## Tools None, this capability only configures the turn loop. ## How It Works When a response loses tool calls this way: * Calls in the same response whose arguments arrived complete still run. * The cut-off calls do not run. Every provider drops them: Anthropic, OpenAI (Chat Completions and Responses), Gemini, and Bedrock. * The policy decides the turn’s next step: | Policy | What happens | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `continue` (default) | The model gets a short notice that its output hit the limit and the call was not run, and the turn runs another model call so it can retry with less output. After `max_retries` cut-off responses in a row, the turn fails with an error. | | `fail` | The turn ends with an error. | | `off` | The turn carries on as if the model had not asked for the cut-off calls: it ends on the partial answer, with stop reason `max_tokens`. | The `continue` notice appears in the conversation the model sees, right after the cut-off response and any results of the calls that did run. It is not stored as a message and is not shown in the chat. A clean model response, or a new user message, resets the count of consecutive cut-off responses. Responses that are refused or filtered (`content_filter`, `refusal`) are not retried: retrying does not fix them. ## Config
```json
{
"capabilities": [
{
"ref": "output_truncation",
"config": { "policy": "continue", "max_retries": 2 }
}
]
}
```
| Field | Type | Default | Description | | ------------- | ----------------------------- | ---------- | ------------------------------------------------------------------- | | `policy` | `continue` \| `fail` \| `off` | `continue` | What the turn does when a response loses tool calls | | `max_retries` | integer, 0 to 10 | `2` | Cut-off responses in a row `continue` retries before the turn fails | When the capability is set on both the harness and the agent, the agent’s config wins. ## Observability Each `llm.generation` event records how the response ended: * `finish_reasons`; * `tool_calls_dropped`; * `truncation_gate`, set to `retried` or `failed` when the policy acted. The same value is exported as the `everruns.llm.truncation_gate` span attribute and counted in the `everruns_llm_truncation_gate_total` metric. See the [event reference](https://everruns.com/docs/event-reference/#llmgeneration). ## Related * [Tool Call Repair](https://everruns.com/docs/capabilities/tool-call-repair/), recovery for tool-call arguments that are almost valid JSON * [Tool Loop Detection](https://everruns.com/docs/capabilities/loop-detection/)
---
# Parallel Tool Calls
> Controls whether the agent requests multiple tool calls per turn and runs them concurrently, prefer parallel, avoid (serialize), or leave the provider default.
Source:
| | | | ---------------- | --------------------- | | **ID** | `parallel_tool_calls` | | **Category** | Optimization | | **Features** | None | | **Dependencies** | None | | **Risk** | Low | Controls the agent’s request-level preference for parallel (multiple per turn) tool calls, and whether the local tool scheduler runs a batch concurrently. Most providers emit several tool calls in a single turn by default, and Everruns runs independent tool calls concurrently. This capability makes that behavior explicit and configurable: turn it up to actively request batching of independent reads and searches, or turn it down to force strictly one tool call at a time. ## Tools None, this capability only configures the outbound LLM request and the local tool scheduler. ## How It Works The capability resolves a `mode` into a request-level preference that threads through two places: 1. **The LLM request.** On providers that expose a wire control, the preference is sent on the request: * **OpenAI** (Chat Completions and Responses), and the OpenAI-compatible **MAI** and **Fireworks** providers, the top-level `parallel_tool_calls` boolean. * **OpenRouter**: forwarded on the Responses body; ignored by routed providers that do not support it. * **Anthropic**: `tool_choice.disable_parallel_tool_use` (sent only when the request carries tools). * **Gemini** and **Bedrock** have no equivalent request control, so nothing is sent. The local scheduler (below) still honors the preference. 2. **The local tool scheduler.** `avoid` forces the scheduler to run the turn’s tool calls strictly sequentially. This applies to **every** provider, so `avoid` is honored even where there is no wire control. Whether the preference is sent on the wire is gated per provider/model: a driver that cannot express it omits the field rather than risking an API error. ## Config
```json
{
"capabilities": [
{
"ref": "parallel_tool_calls",
"config": { "mode": "prefer" }
}
]
}
```
### Modes | Mode | Provider request | Local scheduler | | ------------------ | ---------------------------------------------- | ------------------------------------- | | `prefer` (default) | Request parallel tool calls where supported | Concurrent (class-aware, the default) | | `avoid` | Ask for one tool call per turn where supported | Serialized | | `none` | Omit, provider default | Concurrent (class-aware, the default) | When the capability is enabled without an explicit `mode`, the default is `prefer`. `none` is equivalent to not enabling the capability; it is useful to neutralize a preference inherited from a parent harness. **Base** and every harness built on it, plus the deprecated **Generic** and **Worker Base**, enable this capability with `mode: "prefer"` by default. ## Precedence An explicit `parallel_tool_calls` field set directly on a harness, agent, or session is a lower-level escape hatch and takes precedence over this capability. ## When To Use * **`prefer`**: workloads that issue many independent reads or searches per turn benefit from batching (faster turns, fewer round-trips). * **`avoid`**: when tool calls must be observed and applied one at a time, or when a model produces lower-quality parallel batches for your workload. ## Limitations * **Provider gating.** `prefer` only changes the wire request on providers with a control for it (OpenAI/Anthropic families). Elsewhere providers already parallelize by default, so `prefer` is a no-op on the wire. * **Durable mode.** A harness/agent-level `mode` other than the default (`prefer`) is applied with full fidelity in the in-process runtime; in durable worker mode, harness/agent capability config falls back to the default, set the mode at the session level, or use the explicit `parallel_tool_calls` field, to override durably. (This matches other config-bearing capabilities.) ## See Also * [Capabilities](https://everruns.com/docs/features/capabilities/), the extension model this capability plugs into * [Agentic Loop](https://everruns.com/docs/explanation/agentic-loop/), how the runtime schedules a batch of tool calls
---
# Platform
> Discover, inspect, and manage Everruns resources through the command catalog.
Source:
| | | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ID** | `platform` | | **Category** | Platform | | **Risk** | High | | **Tools** | `discover`, `query`, `execute` by default; `platform_` functions with `surface: native`; `everruns` in the session shell with `surface: shell` | | **Dependencies** | `skills`; `session_file_system` when embedded docs are enabled | | **Mounts** | `/workspace/docs`, the Everruns documentation, read-only, when embedded docs are enabled | The Platform capability gives an agent the same catalog-backed command surface as Everruns’ `/mcp` endpoint. Operations come from the server’s registered command inventory, so models can discover current names and schemas instead of guessing them or relying on a separate handwritten API. Platform Chat includes this capability by default. Other agents and harnesses must be assigned it explicitly. Because `execute` can mutate platform resources, the capability is high-risk and follows the normal admin-only assignment rule. ## Interfaces and built-in skills Platform Chat uses `{"ref":"platform","config":{"surface":"native"}}`. This registers all 350 public, nondurable, noninternal inventory operations as individual `platform_` functions. The schema wraps the canonical typed payload in `params`; `reason` and `context_revision` remain separate metadata for change history. Names use the `platform_` prefix to avoid clashes with other tools. An omitted `surface` keeps the legacy `discover`, `query`, and `execute` tools; `{"surface":"shell"}` exposes the existing `everruns` command interface instead. Native calls use the same authorized platform dispatch as the CLI. The static `operations.json` catalog is generated from the server inventory, and workers do not link the server crate. Feature flags and permissions are checked again when a call runs. Like the local CLI grammar, this catalog spans public operations across feature flags; disabled operations remain discoverable but cannot execute. Platform Chat also uses bounded `tool_search` with a threshold of 1, so only selected operation schemas join the active tool list. Search results contain operation summaries; the complete schemas arrive as native functions on the next step without a duplicate copy in search history. Search can match native operation names and descriptions, plus declared capability names and descriptions. Its defaults are 32 optional schemas, 64 KiB of active schemas, and 32 KiB of search results. Bashkit Worker and the `everruns` shell remain available for loops, filtering, and aggregation across many operations; use native functions for individual operations and the shell for composition. For example, search for `platform_list_agents`, then call that function on the next step with:
```json
{
"params": {
"limit": 5
}
}
```
For a change, put `reason` and the manager-context `context_revision` beside `params`, rather than inside the entity payload. Workspace builds also ship the read-only `everruns` skill with this capability: product concepts and documentation links in `SKILL.md`, with task guides beside it, such as `references/cli.md` (command usage, scripting, and how the CLI, session shell, and MCP differ) and `references/agent-authoring.md` (agent design, configuration, dependencies, and behavioral verification). The capability enables [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/) for discovery and activation. Use `list_skills` and `activate_skill`; full instructions load on demand from `/workspace/.agents/skills//SKILL.md`. Follow the current session interface when a skill shows an external MCP example. Adding skills grants no additional command permissions. Like embedded docs, these product files are included from the repository at build time; standalone crate builds without the repository skills tree omit them. The external [MCP endpoint](https://everruns.com/docs/features/mcp/#skills-for-mcp-clients) serves the same skill. ## Tools ### `discover` Search for operations by name, category, description, or schema terms. Results include command metadata, read-only decision, and output-shape hints. Searches with multiple matches omit schemas and return a refinement hint to keep the result compact. A query that exactly matches a command name returns only that command with its schemas and `bash_usage`, a copyable invocation with the exact supported flags. It also includes bounded `output_fields` paths for building `jq` filters without guessing field names. If expanded schemas would make the result too large, the response omits them with a notice while retaining the authoritative scripting summaries. Use `all: true` only when you truly need to list the entire scriptable catalog, not for a task-specific lookup.
```json
{ "query": "models" }
```
Once you find a command, discover its exact name before invoking it:
```json
{ "query": "create_agent" }
```
For commands with a `cli` spelling, use command-tree `--help` as directed by discovery. Flat-only builtins have no `--help`; use their `bash_usage` and returned schema. Pass array and object values as JSON text, for example `--capabilities '[{"ref":"mcp:..."}]'`. Unknown flags are rejected before a command runs. This prevents misspelled security-sensitive options, such as an authentication flag, from being silently ignored during a mutation. ### `query` Run a bounded Bashkit script with only read-only Everruns commands available as builtins. It supports pipes, variables, loops, conditionals, and `jq`.
```json
{ "commands": "list_models | jq '.data[] | {id, model_id, display_name}'" }
```
Commands with mutations or open-world side effects are not available in `query`. Use it to inspect current state and validate changes. ### `execute` Run a bounded Bashkit script with the full scriptable command catalog. Use it for requested create, update, delete, and other mutating operations.
```json
{
"commands": "create_agent --name 'support-agent' --system_prompt 'Help users.' --default_model_id 'model_...'"
}
```
`execute` is not transactional. If a later command in a script fails, earlier commands may already have succeeded. Inspect the resulting state with `query` before retrying. MCP server command results include both their public resource `id` and a derived `capability_ref` in the `mcp:` form accepted by Agent capability configuration. Capture JSON results and use `jq` to pass dependent IDs or capability references to later commands in the same script. No separate MCP attachment operation is needed. ## Scope and authorization Platform tools are always bound to the current session’s organization. Their schemas do not accept `organization_id`, and an injected override is rejected. The server resolves the session’s human owner for every distributed call and applies that caller’s normal command permissions. Attaching this capability does not grant authority the owner does not already have. ## Autonomous workflows For recurring autonomous work, create an Agent and an Agent Trigger. Do not use a schedule on the Platform Chat session: that would wake the management chat, not provision an independently owned worker workflow. Credentials are not transferred from Platform Chat session secrets into a new Agent. Configure integrations through their supported Agent-scoped credential or connection flow; do not paste credentials into command scripts. ## Platform documentation When the build embeds the product documentation, this capability mounts it at `/workspace/docs` as a read-only virtual filesystem, served from memory with no database writes per session. Agents browse it with the standard file tools (`read_file`, `list_directory`, `grep`) or with `cat`, `ls`, and `grep` through Bashkit Shell. Key sections: * `/workspace/docs/getting-started/`, introduction, concepts, architecture * `/workspace/docs/features/`, SDK, CLI, UI, events, harnesses, capabilities * `/workspace/docs/capabilities/`, per-capability reference * `/workspace/docs/integrations/`, external integrations (Slack, Daytona, etc.) * `/workspace/docs/advanced/`, budgets, compaction, embedding, network access * `/workspace/docs/sre/`, environment variables, runbooks ## See also * [Platform Chat harness](https://everruns.com/docs/built-ins/harnesses/platform-chat/) * [MCP](https://everruns.com/docs/features/mcp/) * [Agent Triggers](https://everruns.com/docs/features/agent-triggers/) * [Platform Management](https://everruns.com/docs/capabilities/platform-management/), the removed predecessor
---
# Platform Management (removed)
> Removed capability. Its management tools are superseded by the catalog-backed Platform capability.
Source:
> **This capability has been removed.** Use the [Platform capability](https://everruns.com/docs/capabilities/platform/) instead. Agents and harnesses that still reference `platform_management` keep running, but the capability contributes no tools and no system prompt. | | | | --------------- | -------------------------------------------------------------- | | **ID** | `platform_management` | | **Category** | Platform | | **Status** | Retired | | **Tools** | None | | **Replacement** | [`platform`](https://everruns.com/docs/capabilities/platform/) | ## Why it was removed Its tools were hand-written alongside the API rather than derived from it, so they covered only harnesses, agents, apps, and sessions, and their schemas drifted as the platform grew. The `platform` capability exposes the same surface through `discover`, `query`, and `execute` over the server’s registered command catalog, which is the same inventory behind Everruns MCP, so it cannot drift. ## What to do Replace the capability on any agent or harness that still lists it: 1. Open the agent or harness. A removed capability is flagged in its capability list. 2. Remove `platform_management` and add `platform`. Both are high-risk, so an admin performs the change. 3. Prompts that named the old tools should name the new flow instead: find the command with `discover`, read state with `query`, mutate with `execute`. ## Tool mapping | Removed tool | Replacement | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `read_capabilities` | `list_capabilities` / `get_capability` | | `read_harnesses` | `list_harnesses` / `get_harness` | | `manage_harnesses` | `create_harness`, `update_harness`, `delete_harness`, `copy_harness` | | `read_agents` | `list_agents` / `get_agent` | | `manage_agents` | `create_agent`, `update_agent`, `delete_agent` | | `read_apps` | `list_apps` / `get_app` (read-only archive); `list_agent_channels` / `get_agent_channel` for live endpoints | | `manage_apps` | No equivalent. Apps are retired; endpoints belong to an agent. | | `manage_app_channels` | `create_agent_channel`, `update_agent_channel`, `delete_agent_channel`, `publish_agent_channel`, `unpublish_agent_channel` | | `read_sessions` | `list_sessions` / `get_session` | | `manage_sessions` | `create_session`, `delete_session` | | `session_send_message` | `create_message` | | `session_read_messages` | `list_messages` | | `session_context_report` | `get_session_context_report` | | `session_read_response` | No equivalent. It blocked until the turn finished; poll `list_messages` instead. | Run `discover` for the exact current schema of any command in that table rather than assuming the flags. ## Platform documentation The embedded documentation mount at `/workspace/docs` moved to the [Platform capability](https://everruns.com/docs/capabilities/platform/) unchanged. ## See also * [Platform](https://everruns.com/docs/capabilities/platform/), the replacement * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Poppy Personal Agent
> Let an agent talk to companies' agents for the person it works for, over the Personal Agent Protocol (Poppy).
Source:
| | | | ---------------- | -------------- | | **ID** | `poppy_client` | | **Category** | Integrations | | **Features** | None | | **Dependencies** | None | | **Risk** | Medium | The [Personal Agent Protocol](https://personalagentprotocol.org) (“Poppy”, draft 0.1) lets a person’s own agent do business with a company: find it, start a conversation with its agent, and hand off to a person there. With this capability an Everruns agent is that personal agent. Any company that publishes `/.well-known/poppy.json` on its domain works, with nothing to register. This page covers the personal side. To make an Everruns agent the company that personal agents talk to, and for how both ends are tested, see [Personal Agent Protocol (Poppy)](https://everruns.com/docs/features/poppy/). ## When to enable * A personal assistant such as Platform Chat, where people ask the agent to check on an order, a booking or a support case with a company. Leave it off for agents that should not contact outside companies. ## Configuration None.
```json
{ "ref": "poppy_client", "config": {} }
```
## Tools | Tool | What it does | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `poppy_discover` | Looks up a company by domain and says what it offers | | `poppy_send` | Sends a message to the company’s agent and waits briefly for the reply. The first message starts the conversation; `new_conversation` starts another | | `poppy_read` | Reads replies that arrived since the last answer | | `poppy_handoff` | Asks the company for a person | | `poppy_close` | Ends the conversation | ## Identity and privacy Every company sees the deployment as one personal agent named “Everruns”. Its client metadata is published at `/v1/poppy/agent.json` and its public key at `/v1/poppy/jwks.json`, under the API base URL. Each person gets a different random User ID at each company, so two companies cannot tell they talk to the same person. Nothing else about the person, the organization or the conversation is sent, beyond the messages themselves. Keys and Session Tokens stay on the server, encrypted at rest. The agent’s tools only see what the company answered. Requests go through the organization’s egress allowlist. ## In the Framework A Framework app is its own personal agent. Turn on the `poppy` feature, give the agent `PoppyPersonalAgent`, and serve its two documents at the HTTPS address you named:
```rust
use everruns::poppy::{PoppyKey, PoppyPersonalAgent};
let poppy = PoppyPersonalAgent::new("https://agent.example.com", PoppyKey::generate()?);
let metadata = poppy.metadata("My assistant"); // serve at /v1/poppy/agent.json
let jwks = poppy.jwks(); // serve at /v1/poppy/jwks.json
let agent = Agent::builder()
.name("personal-agent")
.model(model)
.capability(poppy)
.build()?;
```
The tools are the same. The app keeps the person’s User IDs, keys and Session Tokens in memory, so a restart is a new person to every company. See [the example](https://github.com/everruns/everruns/tree/main/examples/poppy-personal-agent). ## Limits * Sessions are signed out: the person does not sign in to the company yet, so a company that needs an account says so, and the agent tells the person. * Company APIs and operations are not used; only the conversation.
---
# Prompt Caching
> Turns on provider prompt caching for Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, and Mistral requests, and records the cache mode on each llm.generation event.
Source:
| | | | ---------------- | ---------------- | | **ID** | `prompt_caching` | | **Category** | Optimization | | **Tools** | None | | **Features** | None | | **Dependencies** | None | Prompt caching lets a provider reuse the unchanged start of a request (system prompt, tool definitions, earlier conversation) instead of processing it again on every model call. Cached input is usually cheaper and faster. This capability sets the request options each driver needs. It adds no tools and no prompt text. Drivers that support caching translate the setting into their provider’s request fields. A driver or model without support ignores it, and the request proceeds unchanged. The [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) harness includes it. ## What each provider gets | Provider | With `strategy: auto` (default) | With `strategy: explicit` | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Anthropic | `cache_control` breakpoints on the system prompt, the last tool definition, and the two most recent stable conversation messages, four in total | Breakpoints on the system prompt and the last tool definition only, so the conversation is never written to cache | | OpenAI | A `prompt_cache_key` derived from the session (or agent, harness, or organization) and model, so a tool or instructions change keeps the session on the same cache. On models whose profile supports cache options, also `prompt_cache_options` with mode `implicit` and the selected TTL (12 hours by default at `api.openai.com`) | `prompt_cache_key`, and on supporting models `prompt_cache_options` with mode `explicit`: the instructions move into a developer message marked as the cache breakpoint, so only that prefix is written to cache | | Gemini | The provider’s default behavior, such as implicit caching on supported models | Same as `auto` | | Bedrock (Claude, Nova) | `cachePoint` blocks after the system prompt, after the tool definitions (Claude only; Nova does not cache tools), and on the two most recent messages | `cachePoint` blocks after the system prompt and tools only | | OpenRouter, Claude models | A top-level `cache_control`, which turns on Anthropic’s automatic caching through OpenRouter. Other OpenRouter models keep their vendor’s implicit caching | Nothing extra: automatic caching cannot exclude the conversation | | Mistral | A `prompt_cache_key` derived from the session (or agent, harness, or organization) and model, so requests sharing a prefix reach the same cache | Same as `auto` | Requests through the OpenAI Responses protocol (OpenAI, OpenRouter, Meta, Vercel AI Gateway) carry that `prompt_cache_key` even when an agent does not use this capability, because those providers cache on their own and the key is what sends a session’s calls to the same cache. Without it, Muse Spark misses the cache on every prompt above roughly 100k tokens. Setting `enabled: false` removes the key. On qualified OpenAI Responses models at `api.openai.com`, Everruns also sends a 12-hour implicit cache lifetime by default, even without this capability. Add the capability to choose a shorter lifetime, explicit strategy, or disable Everruns-managed controls. On Gemini, setting `gemini_cached_content` sends that existing cached content resource in the request’s `cachedContent` field. On OpenAI with the explicit mode, the driver replays the full transcript instead of chaining with `previous_response_id`, so the developer prefix is not appended again on each continuation. Use `explicit` when many short, unrelated sessions share long instructions or tools, such as a support agent: caching every conversation would cost more in cache writes than it saves in reads. ## Tool changes during a session Tool definitions sit at the front of the cached prompt, so a tool list that changes mid-session (a tool revealed by [Tool Search](https://everruns.com/docs/capabilities/tool-search/), for example) used to throw the whole cache away. Sessions now record their tool list on the first model call and each later change in the conversation. On Claude Opus 5.5, Opus 5, Opus 4.8, Sonnet 5.5, Haiku 5.5 and Fable 5.1 through the Claude API, and on GPT-6 Astra, Sol, Luna and 6.1 Sol and GPT-5.6 Sol, Terra and Luna through the OpenAI API, the request keeps the first tool list and sends each change in the conversation, so the cache survives it. GPT-5.5 and GPT-5.4 keep the cache when tools are added; a revealed tool there still costs one cache write. Instructions a capability adds when it is switched on mid-session travel the same way on those models: the request keeps the first system prompt and sends the new instructions in the conversation. Other models and endpoints receive the current tool list. Tools already sent keep their places and a revealed tool goes at the end, so a change costs a cache write only from that point on. A tool that goes away there (a capability switched off, for example) stays in the list while the cache is warm and nothing else changes, and a call to it is refused; it leaves with the next change, or once the session has been idle longer than the cache retention. ## Retention `retention` sets how long the provider keeps a cached prefix after its last use. Drivers snap down to a supported tier, or up to the shortest tier when none is shorter. Retention is a minimum reuse lifetime, not a deletion deadline. | Provider | `default` | `5m` | `30m` | `1h` | `12h` | | -------------------------------------------------------- | ---------------- | ---------------- | ---------------- | ---------------- | ---------------- | | Anthropic | 5 minutes | 5 minutes | 5 minutes | 1 hour | 1 hour | | Bedrock, Claude models with 1-hour TTL support | 5 minutes | 5 minutes | 5 minutes | 1 hour | 1 hour | | OpenRouter, Claude models | 5 minutes | 5 minutes | 5 minutes | 1 hour | 1 hour | | OpenAI Responses with cache options, at `api.openai.com` | 12 hours | 30 minutes | 30 minutes | 30 minutes | 12 hours | | Azure or custom Responses endpoints with cache options | 30 minutes | 30 minutes | 30 minutes | 30 minutes | 30 minutes | | Others | Provider default | Provider default | Provider default | Provider default | Provider default | The 12-hour default applies to direct Responses calls on models whose Everruns profile supports cache options (GPT-5.6 and later). Omitting retention or using `default` selects twelve hours; explicit shorter values retain thirty minutes. This is an Everruns default; OpenAI itself defaults to thirty minutes. It is not sent to Chat Completions, older OpenAI models, ChatGPT subscription endpoints, or compatible gateways. Native batch request encoding does not apply these cache controls. Bedrock TTL availability is model-specific. Models outside the documented one-hour allowlist, including unknown models and Nova, use five minutes. A longer retention costs more per write: Anthropic bills a 1 hour cache write at 2x the input rate instead of 1.25x, and cost estimates include that. Choose `1h` for agents whose turns are often more than five minutes apart, such as agents that wait on a person or run on a schedule, where a 5 minute cache would have expired before the next turn. OpenAI’s 12-hour writes cost 2.5x the uncached input rate, versus 1.25x for 30-minute writes; reads use the same discounted rate. A prefix needs at least two full reads per 12-hour write to beat uncached input. Upgrading a warm 30-minute prefix to 12 hours can charge a new write. Cost estimates use the provider-reported 12-hour subset, including mixed lifetimes, and the served service tier; the requested retention alone is not proof of a write or hit. See [OpenAI prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching) for minimum prefix lengths, billing and data retention. OpenAI documents all prompt caching as Zero Data Retention compatible. It may retain encrypted key/value tensors as application state for up to 24 hours; the twelve-hour TTL is a minimum reuse lifetime, not a deletion deadline. It does not change the Responses `store` setting or the organization’s data controls. See [OpenAI data controls](https://developers.openai.com/api/docs/guides/your-data). ## Configuration
```json
{
"ref": "prompt_caching",
"config": { "strategy": "auto", "retention": "1h" }
}
```
| Field | Default | Description | | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `true` | `false` disables Everruns-managed controls and routing hints. It cannot disable provider implicit caching or erase existing caches. | | `strategy` | `auto` | `auto` lets each driver pick its provider behavior. `explicit` caches only the stable prefix (instructions, and tools on Anthropic) on providers that support it. | | `retention` | `default` | `default`, `5m`, `30m`, `1h`, or `12h`. `default` means twelve hours for qualified OpenAI Responses calls; other providers keep their existing defaults. Explicit values snap to supported tiers. | | `gemini_cached_content` | none | An existing Gemini cached content resource name, `cachedContents/{id}` | To keep the lower 30-minute write rate on OpenAI Responses:
```json
{
"ref": "prompt_caching",
"config": { "retention": "30m" }
}
```
To remove Everruns-managed cache options and routing hints:
```json
{ "ref": "prompt_caching", "config": { "enabled": false } }
```
The provider may still cache implicitly. To cache only the stable instructions prefix, set `strategy: "explicit"`; its OpenAI retention defaults to twelve hours. ## Observability Each `llm.generation` event records the request in `request_options.prompt_cache`: whether caching was enabled, the strategy, and a `provider_mode` naming what the driver did, and the `retention` it requested after endpoint translation when a completed call captures its request. Pre-call or failed-call metadata can only describe intent. The modes are `cache_control` (Anthropic), `implicit`, `explicit`, or `prompt_cache_key` (OpenAI), and `implicit` or `cached_content` (Gemini). Cache read and write token counts, when the provider reports them, appear in the event’s token usage. In a session’s Trace view, each model call shows its prompt split into cache read, cache write and uncached tokens. When a call reuses less than half of what the previous call left cached, the trace marks a cache reset and names the likely cause: the model, the tool definitions, the system prompt or earlier messages changed, or the session sat idle longer than the cache retention. A long prompt sent with caching off is marked as one that caching would help. A call that changed the tool list lists the tools added, updated or removed. ## See also * [Platform Chat harness](https://everruns.com/docs/built-ins/harnesses/platform-chat/) * [OpenTelemetry](https://everruns.com/docs/observability/opentelemetry/), which exports prompt-cache token counts per call * [Tool Search](https://everruns.com/docs/capabilities/tool-search/), another request-level optimization
---
# Prompt Canary Guardrail
> Streaming output guardrail that withholds the assistant message when the model echoes the first sentence of its system prompt back to the user.
Source:
| | | | ---------------- | ------------------------- | | **ID** | `prompt_canary_guardrail` | | **Category** | Safety | | **Features** | None | | **Dependencies** | None | | **Risk** | Low | Detects naive system-prompt leakage during streaming. At the start of each assistant message, the capability extracts the first qualifying sentence of the assembled system prompt and uses it as a canary needle. If the model’s accumulated output ever contains that needle, streaming aborts, the client is told to discard everything it accumulated, and a canned refusal becomes the persisted assistant message. The original tokens are never stored or replayed on subsequent turns. This is intentionally narrow: a single substring match against one normalized needle. It catches obvious prompt-extraction attempts (“repeat your instructions”, “what are you told to do?”) without trying to be a general-purpose data-loss-prevention layer. ## Tools None, this capability hooks the streaming output via the capability framework’s output-guardrail extension point. ## How It Works 1. **Arming**: At the start of each assistant message stream, the capability walks sentence boundaries in the assembled system prompt and picks the first sentence whose normalized form is **≥ 30 characters**. This skips short generic openers like “You are a helpful assistant.” in favor of an agent-specific identifying sentence 2. **Normalization**: Both sides of the comparison are lowercased, and runs of whitespace are collapsed to a single space, so the canary survives reformatting (extra spaces, capitalization drift, line wrapping) 3. **Streaming check**: After every text delta, the canary runs a substring scan over the accumulated assistant text. The check is synchronous and cheap, no I/O, no allocations beyond the normalized buffer 4. **Block on match**: When the needle appears in the accumulated output, the stream is aborted, the offending pending delta is suppressed, and `output.message.replaced` is emitted with `reason_code: "system_prompt_leak"`. The replacement text becomes the persisted assistant message When the system prompt is too short or too generic to produce a needle ≥ 30 characters, the capability declines to arm for that stream and is a no-op. ## Streaming Timeline With a Trip
```plaintext
output.message.started
│
▼
output.message.delta ← model text accumulating ("Sure, my instructions are: …")
│
▼ (canary trips on the next delta — pending text is suppressed)
output.message.replaced
│ (UI discards what it accumulated, shows replacement)
▼
output.message.completed ← persisted message body = replacement
```
## Configuration ### Default
```json
{
"capabilities": ["prompt_canary_guardrail"]
}
```
Replacement text defaults to: > \[Response withheld: the model attempted to reveal protected instructions.] ### Custom replacement
```json
{
"capabilities": [
{
"ref": "prompt_canary_guardrail",
"config": { "replacement": "I can't share my system instructions." }
}
]
}
```
## When To Enable Use this capability when: * You ship agents with proprietary, brand-specific, or compliance-relevant system prompts that should not be revealed verbatim to end users * You want a cheap, deterministic defense against the most common prompt-extraction prompts * You can tolerate a generic refusal in place of the model’s response when the canary trips Do **not** rely on this for: * General-purpose data-loss prevention (PII, secrets in tool output, etc.), those need their own surfaces * Defense against paraphrased or summarized prompt leaks, the canary only catches verbatim or near-verbatim copies of the first sentence * Tool output or extended-thinking surfaces, the canary only inspects assistant text ## Limitations * **Verbatim-only**: a model that paraphrases (“My role is to act as an internal pricing oracle…”) will not trip the canary * **First-sentence-only**: if the model leaks a *later* sentence of the system prompt, the canary won’t catch it. Consider rewriting prompts so the most identifying claim is the opening sentence * **No partial matching**: the substring must appear in full. Truncated leaks (cut off mid-sentence) pass through ## See Also * [Events](https://everruns.com/docs/features/events/), the streaming event protocol that carries `output.message.replaced` * [Capabilities](https://everruns.com/docs/features/capabilities/), the extension model these guardrails plug into
---
# Repositories
> Work on several GitHub repositories in one sandbox, with one work branch per session and no GitHub credential kept in the sandbox.
Source:
| | | | ---------------- | ---------------------------------------- | | **ID** | `repositories` | | **Category** | Integrations | | **Features** | `repositories` (enables the Changes tab) | | **Dependencies** | None | The Repositories capability gives a session a set of GitHub repositories to work on. Each one is checked out in its own directory under `/workspace`, so a change that touches a service and the library it uses is one session, not two. One repository is just a set with one entry. It needs a full sandbox (a [Sandbox Worker](https://everruns.com/docs/built-ins/harnesses/sandbox-worker/) agent). The [Coding](https://everruns.com/docs/built-ins/) harness example includes it. ## Tools | Tool | What it does | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repo_status` | Checks out the session’s repositories that are not in `/workspace` yet, then reports every repository there: path, access, branch, uncommitted files, commits ahead of the base branch and commits not pushed. | | `repo_add` | Checks out another repository next to the ones already there. Not offered when `add_repositories` is `off`. | | `repo_sync` | Fetches a branch (the base branch by default) into `origin/` and reports how far the checkout is ahead and behind. It merges nothing. | | `repo_push` | Pushes the session’s work branch of one writable repository. Never forces. Only offered when something is writable. | Commits, diffs, merges and rebases are ordinary git in the shell. Open the pull request with `create_github_pull_request` from the [GitHub](https://everruns.com/docs/capabilities/github/) capability. ## Configuration
```json
{
"repositories": [
{ "repo": "acme/app", "access": "write" },
{ "repo": "acme/lib", "ref": "release/2.x" }
],
"add_repositories": "read"
}
```
| Setting | Default | Meaning | | ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repositories` | none | The repositories to check out. `access` is `read` (default) or `write`; `ref` is the branch to start from, the default branch when omitted. Up to 20. | | `add_repositories` | `read` | What the agent may do with a repository it adds itself: `off` (it cannot add any), `read`, or `write`. | | `branch_prefix` | `everruns/` | Start of the work branch name. The session’s short id is appended. | | `depth` | `200` | Commits of history to fetch. `repo_sync` can fetch more later. | | `commit_name`, `commit_email` | `Everruns Agent`, `agent@everruns.invalid` | Author of the agent’s commits when the sandbox has no git identity. Set the email to your GitHub App’s `+[bot]@users.noreply.github.com` address to show the bot as author. | | `acts_as` | `agent` | Whose GitHub identity clones and pushes. See [Authentication](#authentication). | Set an agent’s usual repositories on the agent. To start one session on a different set, pass the capability with its own config when you create the session:
```json
{
"agent_id": "agent_...",
"capabilities": [
{
"ref": "repositories",
"config": { "repositories": [{ "repo": "acme/docs", "access": "write" }] }
}
]
}
```
A session’s config replaces the agent’s for that session. ## In the console An agent’s **Repositories** settings list its usual repositories with read or write access each, choose what the agent may add on its own, and set the work branch prefix. The repositories offered are the ones the agent’s GitHub App installation can reach. Starting a chat with such an agent shows the same list. Remove a repository, turn write access down to read, or add another one for that chat alone. The form offers no more than the agent’s settings allow: a repository the agent only reads stays read-only, and nothing can be added when `add_repositories` is `off`. A session’s **Changes** tab shows each repository as the sandbox has it right now: its branch, commits ahead of the base branch, files not committed, whether the work is pushed, the changed files and the diff against the base branch, and a link to the pull request once the agent opened one. It reads from the running sandbox and never starts one; when the sandbox is stopped, pushed work is still on GitHub. The same data is at `GET /v1/sessions/{session_id}/repositories`. The tab has no merge, push or discard buttons: the agent acts, you review. ## Layout and branches A repository is checked out at `/workspace/`. When two repositories share a name, the second goes to `/workspace/-`. `/workspace` itself is not a repository. Writable repositories start on the session’s work branch, `everruns/` by default, with the same name in every repository. Read-only repositories stay on their starting branch. `repo_push` pushes the work branch and nothing else, so a change across repositories ends as one pull request per repository, all from branches with the same name. The first time a repository is checked out, its `AGENTS.md` comes back with the result, so the agent reads each repository’s own rules before changing it. ## Authentication The sandbox never keeps a GitHub credential. Each checkout, fetch and push gets its own short-lived token from the agent’s GitHub App installation: * checkout and fetch: **Contents: read**, limited to the repositories being fetched; * push: **Contents: write**, limited to the one repository being pushed. The token is handed to the sandbox for that one git command and removed when it ends. `git push` or `git fetch` typed into the shell has nothing to authenticate with, so private code only moves through these tools, and only to the repositories the configuration allows. This works with a GitHub App: the agent’s own, or the shared Everruns app an org admin linked. A person’s own GitHub sign-in cannot be narrowed to a repository set, so it is never handed to a sandbox; with `acts_as: person` the tools report that an App installation is needed. Pushing needs the App’s **Contents: write** permission. An agent’s own App asks for it when the agent is connected to GitHub after `repositories` was given a writable repository (or `add_repositories: write`); every other agent’s App stays read-only. An App created earlier keeps its old permissions: the agent’s GitHub page lists `contents:write` as missing until the App’s owner raises it on GitHub and the installation accepts. Access is decided by the configuration, by repository name. Pointing a checkout’s `origin` somewhere else does not change where `repo_push` pushes or which repository its token is for. While a git command runs, other code in the same sandbox can read that command’s token. For a push that is a token that can write to one repository’s contents for up to an hour. Give `write` access only to repositories where a pushed branch is reviewed before it merges.
---
# Sandbox Fleet
> Create and operate multiple explicitly addressed resource Sandboxes without changing a session's primary Sandbox.
Source:
| | | | -------------- | ---------------------------------------------------------------------------- | | **ID** | `sandbox_fleet` | | **Category** | Sandboxes | | **Tools** | 8 | | **Dependency** | [`session_storage`](https://everruns.com/docs/capabilities/session-storage/) | Sandbox Fleet gives an Agent provider-neutral tools for parallel or isolated compute. Daytona backs the capability today, but the model sees only Everruns logical Sandbox IDs. Provider resource IDs, credentials, and translation stay in the trusted control plane. These are **resource Sandboxes**. They never replace the session’s primary Sandbox: ordinary shell and file tools continue to use the primary Sandbox configured by the Harness and Agent. | Tool | Purpose | | -------------------- | ------------------------------------------------------------------ | | `sandbox_create` | Create a resource Sandbox and return its session-scoped logical ID | | `sandbox_exec` | Run a command in an explicitly named Sandbox | | `sandbox_read_file` | Read a file from an explicitly named Sandbox | | `sandbox_write_file` | Write a file in an explicitly named Sandbox | | `sandbox_list` | List the current session’s resource Sandboxes | | `sandbox_inspect` | Inspect one resource Sandbox without exposing provider bindings | | `sandbox_checkpoint` | Copy its workspace into durable session file storage | | `sandbox_manage` | Stop or delete it | Every operation after creation requires `sandbox_id`. An ID from another session is rejected. Delete resource Sandboxes when the work is complete. The older [`daytona`](https://everruns.com/docs/capabilities/daytona/) capability remains available for existing Agents and provider-specific operations. New provider-neutral fleet workflows should use `sandbox_fleet`.
---
# Self-Budget
> Prompt-only guidance for agents to reason about a user-requested indicative budget using session usage data. Distinct from the platform-enforced `budgeting` capability.
Source:
| | | | ---------------- | -------------- | | **ID** | `self_budget` | | **Category** | System | | **Features** | *(none)* | | **Tools** | *(none)* | | **Included in** | Worker harness | | **Dependencies** | None | Teaches the agent how to self-manage an **indicative** budget that the user mentions in conversation, for example, “you have $7” or “keep this under 20k tokens”. The capability contributes prompt text only; it adds no tools and performs no enforcement. For platform-enforced budgets (authoritative limits that pause or stop sessions automatically), use the separate [`budgeting`](https://everruns.com/docs/capabilities/budgeting/) capability. ## How It Works `self_budget` is prompt-only. When the capability is enabled the agent’s system prompt gets a “Self-Managed Budget” section that explains: * The self-budget is an **agent-managed soft target**, not a hard limit. * The session’s spend in USD (`spend` from `get_session_info`) is the source of truth for current spend. * The agent decides when to start tracking, when to re-check, and when to stop. * As the target tightens, the agent should adapt, shorter outputs, fewer retries, narrower exploration, fewer redundant tool calls. * The agent qualifies figures that are estimates (`basis`) or incomplete (`partial`). * The agent distinguishes between platform-enforced budgets and user-requested indicative budgets when reporting progress. There is no `self_budget` tool. Usage data comes from `get_session_info`, which is provided by the [`session`](https://everruns.com/docs/capabilities/session/) capability (bundled by default in the Worker harness). ## Self-Budget vs Budgeting | Aspect | `self_budget` | `budgeting` | | ----------- | ------------------------------- | --------------------------------------------------- | | What it is | Agent-managed soft target | Platform-enforced limit | | Tools | None | `check_budget` | | Enforcement | None (prompt guidance only) | Session is paused/stopped automatically | | Data source | `get_session_info` spend | Budgets table / ledger | | Use case | User says “you have $7” in chat | Org/session has a configured budget in the platform | The two capabilities are non-conflicting and can run together. The Worker harness includes both. ## Related * [Budgeting](https://everruns.com/docs/capabilities/budgeting/), platform-enforced budgets with the `check_budget` tool * [Session](https://everruns.com/docs/capabilities/session/), provides `get_session_info`, the usage data source * [Budgets](https://everruns.com/docs/advanced/budgets/), full budgeting system documentation
---
# Session
> Inspect and update the current session's metadata, including its ID, title, agent name, locale, and usage.
Source:
| | | | ---------------- | --------- | | **ID** | `session` | | **Category** | Session | | **Features** | None | | **Dependencies** | None | Tools to read and update session metadata like title and agent information. ## Automatic titles For naming outside the agent loop, enable [Automatic session titles](https://everruns.com/docs/capabilities/automatic-session-titles/) and leave `auto_title` off. Explicit tool writes take priority over automatic titles, including same-text writes. Agent-directed title maintenance is opt-in. Set `auto_title` to `true` in the capability configuration to have the agent create a concise 3–7 word title before handling the first substantive request. The title is a required pre-work update. The agent updates it later, also before other work or a response, only when the conversation’s primary theme materially changes, not for minor follow-ups or subtopics. Title writes update session metadata and do not count as project or workspace file changes. Title changes emit `session.title.updated` with the previous and new title. A repeated write of the current title is a no-op and emits no event. ## Tools ### `get_session_info` Get current session metadata. Returns: session ID, title, locale, agent name, token usage (input, output, cache read, cache creation, and total tokens) when available, and `spend`: what this session has spent so far in USD. `spend` adds up: * **Model calls** in turns, with a split by input, cached input, cache writes and output, and per model. A cost the provider reports (OpenRouter) is used as is; other calls are priced from the model’s price table. * **Background calls** the platform made for the session, such as titles and compaction. * **Images** from `generate_image` and `edit_image`, priced from their usage. * **Sandboxes**: running and stopped time, priced by your organization’s price list when it has a `sandbox.time` rate, otherwise by the provider’s published rate for the sandbox’s size (Daytona, E2B, Modal). * **Subagents** the session started, each with its own whole spend. It also returns `current_turn_usd` (this turn so far), `wasted_usd` (calls in turns that failed), `basis` (`provider_reported`, `price_list` or `list_price`; the weakest part wins) and `partial` when something had no price. Paid tools on your own keys (search, browser), knowledge indexing and evaluations are not included. The figure covers only this session and its subagents. It never includes organization totals, budgets, credits or your price list, so an agent can quote it, for example in a pull request comment. `spend` is `null` on hosts that cannot price it, such as the embedded framework. ### `write_session_title` Update the session title. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------- | | `title` | string | yes | New session title | ## See Also * [Storage](https://everruns.com/docs/capabilities/session-storage/), persist data within the session * [Schedules](https://everruns.com/docs/capabilities/session-schedules/), schedule future tasks * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Schedules
> Schedule one-shot and recurring cron-based tasks within a session.
Source:
| | | | ---------------- | ---------------------------------------------------------------------------------- | | **ID** | `session_schedule` | | **Category** | Core | | **Features** | `schedules` (Files and Work tabs list registered, canceled, and deleted schedules) | | **Dependencies** | None | Schedule future tasks within the current session. Supports one-shot (run once at a specific time) and recurring (cron expression) schedules. Recurring cron is interpreted in the schedule’s IANA timezone. The next trigger must be in the future in UTC, including when daylight-saving time repeats a local hour; an already-past occurrence cannot make the schedule immediately due again. ## Tools ### `create_schedule` Create a new scheduled task. | Parameter | Type | Required | Description | | ----------------- | ------- | ----------- | ------------------------------------------------------------------ | | `description` | string | yes | The message/task to execute | | `scheduled_at` | string | conditional | ISO 8601 datetime for one-shot schedules | | `cron_expression` | string | conditional | Cron expression for recurring schedules | | `timezone` | string | no | IANA timezone the cron is read in. Default UTC | | `ends_at` | string | recurring | RFC 3339 time after which the schedule stops, at most 7 days ahead | | `max_runs` | integer | recurring | Most times the schedule fires, at most 96 | | `stop_when` | string | recurring | One sentence on when the work is done | | `budget_usd` | number | no | Spend cap for the schedule’s runs. Default $2, at most $10 | Provide either `scheduled_at` or `cron_expression`, not both. A recurring schedule needs `stop_when` and at least one of `ends_at` and `max_runs`; whichever end comes first stops it. ### `cancel_schedule` Cancel an active schedule. | Parameter | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------- | | `schedule_id` | string | yes | ID of the schedule to cancel | ### `list_schedules` List all schedules for the current session. ## Recurring background tasks Recurrence is built on schedules, there is no separate “recurring task” object to configure. A recurring (`cron_expression`) schedule either delivers a scheduled turn to the session, or, when paired with a background **monitor** task, runs a probe on each fire and records the result on the task’s thread. This composition (recurring schedule + monitor) is the supported way to run periodic background work, there is no separate recurring-task primitive to configure. To poll a URL without spending model tokens, an agent calls `spawn_background` with `web_fetch`, a `schedule` and a `schedule.wake_when` condition. Each fire fetches the URL with the session’s network rules and starts no turn; the agent gets one turn, with the response, when the condition becomes true. The condition reads the result, with a JSON body parsed under `/json`:
```json
{
"tool": "web_fetch",
"args": {
"url": "https://claims.example/token",
"method": "POST",
"json": {
"claim": "clm_1"
}
},
"schedule": {
"cron_expression": "*/5 * * * *",
"max_runs": 96,
"stop_when": "the claim is approved or has expired",
"wake_when": {
"path": "/json/error",
"not_equals": "authorization_pending"
}
}
}
```
Use `equals` to wait for a value, `not_equals` to wait for one to end, or `"changed": true` to hear about every new value. ## Limits on unattended runs A schedule runs with no person watching, so it always has an end and a budget: * An agent’s recurring schedule lasts at most 7 days and 96 runs. At the 5 minute minimum interval 96 runs is 8 hours, so a longer wait needs a longer interval. When it reaches its end it stops, with the reason `ended`. * Each schedule’s runs may spend $2 unless the agent passes `budget_usd`, up to $10. When that is spent the schedule stops, with the reason `budget_exhausted`. Turns a person starts in the same session do not count. * All unattended work in an organization, schedule runs and sessions an [agent trigger](https://everruns.com/docs/features/agent-triggers/) started, may spend $20 per day. When that is spent, schedules skip their runs until the next day. * A recurring schedule’s run shows the model a short history: the latest conversation summary, the last 10 messages of the schedule’s earlier runs, and the run itself. The rest of the session stays stored but is not sent, so a long session does not make every run expensive. Write the schedule’s description as a complete instruction. One-shot schedules see the full history. * Every run’s message tells the agent which run it is, when the schedule ends, its stop condition and what it has spent, so it can cancel the schedule once the work is done. * A schedule whose runs keep ending with the same answer is achieving nothing. After 24 identical runs in a row, each run’s message warns the agent; after 48 the schedule stops, with the reason `runaway`. Resuming it starts the count over. * **Settings → Health** reports schedules that repeat or hit their budget, the organization’s daily cap, a jump in an agent’s unattended spend, and sessions that send a large, mostly uncached history. The schedule’s owner and the agent’s authors are notified; organization owners hear about the daily cap. * Organization admins change these limits in **Settings → Limits**. A person can extend one schedule’s end, runs or budget, or resume it, from the session’s schedules, without the agent limits. ## Notes * Maximum 5 active schedules per session * Cron uses standard 5-field format (minute, hour, day, month, weekday), with weekdays counted 0-6 from Sunday (7 is also Sunday, so `5-7` is Friday through Sunday and `0 18 * * 0` is Sundays at 18:00), read in the schedule’s timezone * A recurring schedule fires at most once every 5 minutes by default. Admission rejects invalid cron and expressions with fewer than two future occurrences, because their minimum interval cannot be verified. Use a one-shot schedule for a single future run * An invalid cron expression or timezone, or a schedule over a limit, fails the tool call with the reason, so the agent can correct it * Scheduled messages are sent to the session as if the user sent them * Deleting a schedule keeps it on the session. The Files and Work tabs show it as deleted, with when it was registered and when it was removed. It does not fire again, and `list_schedules` omits it. `cancel_schedule` disables a schedule without deleting it * Use [Current Time](https://everruns.com/docs/capabilities/current-time/) to determine “now” before scheduling ## See Also * [Current Time](https://everruns.com/docs/capabilities/current-time/), get current time for scheduling context * [Session](https://everruns.com/docs/capabilities/session/), session metadata * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Session Storage
> Session-scoped key/value storage and encrypted secret storage.
Source:
| | | | ---------------- | ------------------------------------------------------------ | | **ID** | `session_storage` | | **Category** | Storage | | **Features** | `secrets`, `key_value` (Key values on the session Files tab) | | **Dependencies** | None | Two storage mechanisms scoped to the current session: * **Key/Value store**: plain-text storage for general data * **Secret store**: AES-256-GCM encrypted storage for sensitive data ## Tools ### `kv_store` Manage plain-text key/value pairs. | Parameter | Type | Required | Description | | ----------- | ------ | ----------- | ----------------------------------- | | `operation` | enum | yes | `set`, `get`, `delete`, or `list` | | `key` | string | conditional | Required for `set`, `get`, `delete` | | `value` | string | conditional | Required for `set` | ### `secret_store` Manage encrypted secrets. Values are encrypted at rest and write-only: an agent can store, list and delete secrets, but no tool reads a value back. | Parameter | Type | Required | Description | | ----------- | ------ | ----------- | ------------------------------- | | `operation` | enum | yes | `set`, `delete`, or `list` | | `name` | string | conditional | Required for `set` and `delete` | | `value` | string | conditional | Required for `set` | ## Notes * Data is session-scoped, no cross-session access * `set` uses upsert semantics (overwrites existing keys) * Secret operations require `SECRETS_ENCRYPTION_KEY` to be configured * `list` returns keys/names only (not values) for secrets * The session Files tab lists key values and secret names. It does not write them, and it never shows a secret’s value * A session secret is available only to that session. It does not follow an Agent Trigger that creates a session per invocation. * No secret value ever reaches the model. `secret_store get` answers the same refusal for every name. Capabilities that need a key (GitHub, Brave Search, sandboxes and others) read their own secret on the server. A key the agent’s shell sends to an HTTP API is a bound secret, described next; an MCP tool-parameter credential goes on the Agent’s **Credentials** tab. * A **bound secret** (stored with a URL to send it to) is write-only: `secret_store list` shows its name, URL and how to use it, while `get`, `set` and `delete` refuse it. The Bashkit shell uses it as `$NAME` in HTTP requests to that URL; see [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/#api-keys-the-agent-never-sees). To give every session and trigger of an agent the same key, add it as an **HTTP API** credential on the Agent’s **Credentials** tab. ## See Also * [Session](https://everruns.com/docs/capabilities/session/), session metadata * [File System](https://everruns.com/docs/capabilities/file-system/), file-based storage alternative * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Shell Code Mode
> Call an agent's tools, MCP servers included, from the Bashkit shell with one tools command, so one script can chain several calls and return only what matters.
Source:
| | | | -------------- | ---------------------------------------------------------------------- | | **ID** | `shell_code_mode` | | **Category** | Execution | | **Risk** | High, assignment requires an org **Admin** | | **Depends on** | [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/) | | **Rollout** | Experimental; adding the capability is the opt-in | | **Former ID** | `tools_in_shell`, still accepted | Shell Code Mode, also called code mode, was named Tools in Shell before. Agents saved with the old `tools_in_shell` ID keep working without any change. Shell Code Mode adds a `tools` command inside the [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/). In the default `cli` mode, eligible operations move out of the model’s direct tool list. `hybrid` mode keeps those operations available both through the shell and as native tools, with native schemas eager by default. To defer optional native schemas, also enable bounded `tool_search`. One script can call several tools, filter results with `jq`, and print only what the model needs:
```bash
tools github list-pulls '{"repo":"acme/api","state":"open"}' \
| jq -r '.[] | select(.draft | not) | .number' \
| while read n; do
tools github get-pull "repo=acme/api" "number=$n" | jq -c '{number, title, mergeable}'
done
```
## The `tools` command | Command | What it does | | ----------------------------------------------------- | -------------------------------------------------------------- | | `tools --help` | Lists MCP servers (with their tool counts) and the other tools | | `tools --help` | Lists one MCP server’s tools | | `tools --help`, `tools --help` | Shows the tool’s input schema | | `tools search ` | Finds tools by name and description | | `tools '{...}'` | Calls an MCP tool | | `tools '{...}'` | Calls any other tool | ### Surface mode The default `mode: "cli"` routes eligible operations through the shell. Set `mode: "hybrid"` to keep the CLI route while allowing native discovery and calls. Hybrid mode alone keeps native schemas eager. If `tool_search` is also configured with `bounded: true`, it can reveal optional native schemas within its configured limits; eager owner-required schemas remain visible. The shell source inventory is available from `tools --help` and does not change the static Bash tool description.
```json
{
"ref": "shell_code_mode",
"config": { "mode": "hybrid" }
}
```
The CLI and bounded native search use the same authorized, server-aware index. Legacy native `tool_search` remains unchanged unless configured with `bounded: true`. See [Large MCP catalogs](https://everruns.com/docs/features/large-mcp-catalogs/) for discovery bounds, search configuration, and cache and authorization behavior. MCP tools are grouped by server (`mcp_github__list_pulls` is `tools github list-pulls`); every other tool is a top-level command (`web_fetch` is `tools web-fetch`). Hyphens and underscores are interchangeable. The list is rebuilt on every shell call, so an MCP server added during a session shows up on the next one. **Input** is the same JSON object the tool takes as a direct call. It can come from stdin (`jq -n '{repo: "a/b"}' | tools github list-pulls`, or `-`), from a JSON argument, or from `key=value` and `--key value` pairs, which merge over the JSON. `--flag` alone is `true`. A value is read as JSON unless the tool’s schema says the key is a string, so `number=7` is a number and `repo=42` stays text. **Output** is the tool’s result on stdout: a text result as is, anything else as JSON. An MCP server’s text reply is printed as that text, so a server that answers in JSON pipes straight into `jq`. Images a tool returns are saved under `tool-images/` in the working directory, and stderr names the files. **Errors** are one JSON line on stderr with exit code 1, so a script can branch on them:
```json
{"error":{"code":"needs_approval","message":"...","retryable":false}}
```
| Code | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------- | | `unknown_command` | No such server or tool | | `invalid_input` | The input is not a JSON object or does not match the tool’s schema | | `tool_error` | The tool ran and failed | | `denied` | A guardrail or hook blocked the call | | `needs_approval` | The call needs a person’s approval; the script stops here (see [Approvals](#approvals)) | | `stopped` | An earlier call stopped the script, so this one did not run | | `connection_required` | The tool or its MCP server needs a connection the person has not made | | `call_limit` | More than 50 tool calls in one shell call | | `unavailable` | The command cannot run here, or a server could not load yet (`retryable` says whether a later step can) | ## Which tools move into the shell A tool moves behind `tools` when calling it only does something and returns data: MCP tools, integration tools, search and fetch, platform and data tools. These stay direct tool calls: * the `bash` and `lua` tools themselves; * tools that pause or shape the turn: `ask_user`, approvals, `spawn_agent`, session tasks, `write_todos`, and client-side tools; * tools whose result the model must see as an image, such as screenshots, `read_file`, `computer` and `browser`; * structured file editing (`write_file`, `edit_file`); * tools listed in the `keep_visible` config. MCP servers set to “Load tools on demand” move behind `tools` too. `tools --help` lists them as `(not loaded)`; the first command that names one, such as `tools docs --help` or `tools docs search-docs q=refunds`, or a `tools search` that matches deferred server descriptions, loads its tools inside the same shell call. One `tools search` loads at most eight matching deferred servers; the others stay `(not loaded)` for a later search. A load adds that server’s tools atomically and respects the combined 10,000-tool/32 MiB shell catalog limit. Search, help and calls use only tools in the current turn’s visible scope, and loaded child tools retain the scope of their server placeholder. From the next step on a loaded server is listed like any other. Every call from a script goes through the same checks as a direct call: the turn’s guardrails and hooks run before it, the tool’s schema is checked, and the post-tool hooks see the result before the script does. ## Approvals Approval-gated and destructive tools are reachable from the shell too, and [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) judges each call from a script the same way it judges a direct call. Most scripts never ask: reads, searches, and tools a person already allowed “always” just run. Many MCP tools say nothing about whether they change anything. When the deployment has a decision service configured, such a tool is rated once the first time a script calls it: if it looks like it changes or deletes something outside the session, Tool Approval treats it as destructive and asks before it runs. The approval card then says the tool declares nothing about its risk and only looks like it changes things. A rating only ever adds a question; it never removes one, and tools that declare their own risk are not rated. An agent can turn ratings off with the `rate_unlabeled_tools` setting; such tools are then judged by what they declare, which is nothing, so in Tool Approval’s `normal` mode they run without asking. When a call written out in full in the script, such as `tools github delete-branch branch=fix-x`, needs a person’s answer, the script does not start at all: the `bash` result says so (`"before_start": true` under `stopped`, `done` is empty), the person is asked about that call, and after they answer the agent can run the same script again. Calls whose input is built while the script runs, or that read their input from stdin, are checked as they run instead. To see what a script would do before running it, pass it to `tools plan`. It runs nothing and prints each `tools` call it can see, with its input and risk:
```bash
tools plan <<'EOF'
tools github list-pulls state=open
tools github delete-branch branch=fix-x
EOF
```
```json
{
"calls": [
{"tool": "tools github list-pulls", "input": {"state": "open"}, "risk": "read_only", "where": "script"},
{"tool": "tools github delete-branch", "input": {"branch": "fix-x"}, "risk": "needs_approval", "why": "destructive", "where": "script"}
],
"complete": true
}
```
`risk` is `read_only`, `changes` (runs without asking), `needs_approval`, `blocked`, or `checked_at_run_time` when the input is built while the script runs. A `needs_approval` call carries `why`, the reason the approval card will give: `destructive`, `open_world`, `mutating`, `policy`, or `rated_changes` when the tool declares nothing and was rated as changing things. `complete` is `false` when the script hides calls from reading, for example with `eval`. The agent uses it to describe a script accurately before asking a person about it. When a call needs a person’s answer while the script runs, it is not made and the script stops there. Nothing after it runs, and the script is never resumed or run again, because part of its work is already done and may not be safe to repeat. The `bash` result reports what happened, and the person is asked about the stopped call in the same step:
```json
{
"exit_code": 1,
"success": false,
"tools": {
"done": [
{"tool": "tools linear create-issue", "input": {"title": "Flaky test"},
"ok": true, "result": {"id": "EVE-1201"}}
],
"read_only_calls": 3,
"stopped": {
"reason": "needs_approval",
"approval": "requested",
"call": {"tool": "tools github delete-branch", "input": {"branch": "fix-x"}}
},
"not_reached": "the stopped call and everything after it; write a new script for the rest"
}
}
```
`done` lists every call that may have changed something; read-only calls are counted. After the person answers, the agent writes a new script for what is left. A one-off approval covers that exact call (the tool and its input) once, so the new script can make it. The same report appears when a script stops at the call limit, or exits with an error after changing something. ## In the session timeline The model sees one `bash` call. Each tool the script called through `tools` is also recorded in the session as a [`tool.nested_call`](https://everruns.com/docs/event-reference/) event under that `bash` call, with its command, a short preview of its input, whether it completed, failed, was refused or stopped the script for approval, and how long it ran. The chat shows these as rows under the shell call. They never reach the model. ## Saved scripts An agent can keep a script it wrote and run it again later as one command:
```bash
cat <<'EOF' | tools scripts save triage-prs --description 'Label new pull requests.' \
--input-schema '{"type":"object","properties":{"repo":{"type":"string"}},"required":["repo"]}'
repo=$(jq -r .repo)
tools github list-pulls repo="$repo" state=open | jq -r '.[].number' | while read -r n; do
tools github add-labels repo="$repo" number="$n" labels='["triage"]'
done
EOF
tools scripts # list the agent's saved scripts
tools scripts triage-prs repo=a/b # run one
```
* The input is checked against the script’s schema and arrives on stdin as JSON; what the script prints is its result. * A saved script runs with the tools and identity of the agent turn that runs it, and its `tools` calls follow the same rules: approvals, guardrails, and the 50-call limit of the shell call it runs in. A call that needs approval stops the caller’s script too. * Its shell has the shell builtins and `tools`; `curl` and the `everruns` command are not available inside it. * Saved scripts can call each other, up to four deep. * Saving needs the `manage_scripts` setting. Every agent with the capability can run its saved scripts. Scripts are also managed through the `/v1/agents/{agent_id}/scripts` API and the `everruns agents scripts` command. * A schedule or webhook [trigger](https://everruns.com/docs/features/agent-triggers/#run-a-saved-script) can run a saved script without a model call. ## Tool search In the default `cli` mode, Shell Code Mode replaces tool search. When both are enabled, the tool search capabilities (`tool_search`, `auto_tool_search`, `openai_tool_search`, `claude_tool_search`) contribute nothing. In `hybrid` mode, bounded `tool_search` can reveal native schemas while Shell Code Mode provides the same operations through `tools`. See [Large MCP catalogs and tool surfaces](https://everruns.com/docs/features/large-mcp-catalogs/) for the shared registry model. [Agent Checks](https://everruns.com/docs/features/agent-checks/) report a redundant capability as a `capabilities.superseded` suggestion when it is not active for the selected mode. ## Configuration
```json
{
"capabilities": [
{ "ref": "shell_code_mode", "config": { "mode": "cli", "keep_visible": ["web_fetch"] } }
]
}
```
| Field | Type | Default | Meaning | | ---------------------- | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | string | `cli` | `cli` routes eligible tools through the `tools` command; `hybrid` also retains native tool discovery where configured. | | `keep_visible` | string array | `[]` | Tools the model can still call directly. They stay callable from the shell too. | | `manage_scripts` | boolean | `false` | Let the agent save scripts with `tools scripts save`. | | `rate_unlabeled_tools` | boolean | `true` | Ask the decision service whether a tool that declares nothing about its risk changes things, and ask for approval before it if so. Off: such tools run without asking in Tool Approval’s `normal` mode. | ## In the Framework A Rust host turns the capability on with the agent builder, next to `bashkit_shell` (the `bashkit` feature) and its MCP servers:
```rust
let agent = Agent::builder()
.capability("bashkit_shell")
.capability(CapabilityRef::new("shell_code_mode").config(json!({"mode": "cli"})))
.mcp_server(McpServer::stdio("acme", "acme-mcp-server"))
// provider, model, instructions...
.build()?;
```
[Code Mode with MCP](https://everruns.com/docs/framework/code-mode/) walks through a Framework agent that answers a question over a 1,000-tool MCP server this way, with a recorded demo of the scripts it wrote and the tools they called.
---
# Slack
> Deploy an Everruns agent as a Slack bot through an Agent-owned channel, and let it react, update messages, upload files, and look up users with the slack capability.
Source:
## Framework Enable the `slack-actions` Cargo feature and bind application-owned services with `.slack_actions(actions)`. See [Framework services](https://everruns.com/docs/framework/slack-services/) for credentials, persistence and a complete real-model example. The remaining setup sections describe the hosted Platform. Start with [Build Agents for Slack](https://everruns.com/docs/integrations/slack/) for examples, a walkthrough, and setup. This page covers configuration and the Slack actions reference. Everruns connects an Agent to Slack in two parts: * A **Slack channel** owned by the Agent receives Slack Events API requests, routes each conversation to a session, and posts the Agent’s responses back to Slack. This is how users talk to the Agent in Slack. * The **`slack` capability** lets the Agent act in that conversation beyond replying: reactions, message updates, file uploads, and user lookups. See [Slack actions](#slack-actions). ## What You Get * **Conversational agents in Slack**: Users interact with the Agent in channels, threads, direct messages, or Slack’s agent pane. * **Session routing**: Conversations map to sessions by thread, channel, or user. * **No public address needed**: with Socket Mode, Everruns connects out to Slack; with a Request URL, it verifies each request with Slack’s signing secret. * **Async responses**: Everruns acknowledges Slack immediately and posts the Agent’s response when it is ready. * **Per-channel Slack bots**: Each Slack channel has its own Slack app, credentials, identity, and lifecycle. ## Before You Start * Create an active Agent. * Decide how Slack reaches Everruns; see [Socket Mode or Request URL](#socket-mode-or-request-url). * Ask a Slack workspace administrator for permission to install an app. * An organization administrator connects your Slack workspace once; see [Connect a Slack Workspace](#connect-a-slack-workspace). ## Socket Mode or Request URL Each Slack channel picks how Slack delivers messages, under **How Slack reaches Everruns** in the channel editor: * **Socket Mode**: Everruns opens a connection out to Slack and receives messages over it. It needs no public address, so it works on your own computer behind a home router or a firewall. The channel needs an app-level token (`xapp-...`) in addition to the bot token. New channels default to Socket Mode when the Everruns page is not served over public HTTPS. * **Request URL**: Slack sends each message to Everruns over HTTPS. Set `PUBLIC_APP_URL` to a public HTTPS origin and restart Everruns. On your own computer, `everruns docker up --tunnel tailscale` gives the instance a stable public address and sets `PUBLIC_APP_URL` for you; see [Give it a public address](https://everruns.com/docs/getting-started/run-locally/#give-it-a-public-address). Slack offers no API to create an app-level token, so Socket Mode always takes one paste per agent: 1. Open the channel’s Slack app in [Slack API Apps](https://api.slack.com/apps). The channel editor links to it once the app exists. 2. Under **Basic Information** > **App-Level Tokens**, select **Generate Token and Scopes**, add the `connections:write` scope, and generate it. 3. Paste the token into the channel’s **App-level token** field and save. The channel shows **Connected** once Slack accepts the connection. Each API server keeps one connection per channel (Slack hands each message to one of them) and reconnects on its own after a restart or a network drop. On a public HTTPS address, **Add to Slack** fills in the bot token through Slack’s approval screen. Without one, Slack cannot send you back (it accepts only HTTPS redirect URLs, `http://localhost` included), so **Add to Slack** creates the app and the channel shows **Finish in Slack**: 1. Select **Install the app to your workspace**, approve it in Slack, and copy the **Bot User OAuth Token** (`xoxb-...`). 2. Generate the app-level token as above. 3. Select **Paste tokens**, paste both, and save. ## Connect a Slack Workspace Every Agent you put in Slack gets its own Slack app, with its own name and its own entry in Slack’s Agents menu. Everruns creates those apps for you in your workspace. To do that it needs a Slack configuration token for the workspace, which an organization administrator adds once: 1. Open **Settings** > **Slack workspaces**. 2. Select **Open api.slack.com/apps**, signed in to the workspace you want your Agents in. 3. Scroll to **Your App Configuration Tokens**, select **Generate Token**, and pick the workspace. 4. Copy the **Refresh Token** (it starts `xoxe-1-`) and paste it into Everruns. Do not copy the access token above it. Everruns connects the workspace as soon as you paste the token, rotates it immediately, and stores only the encrypted replacement. You do not need to repeat this for each Agent. The token can create and change any Slack app in that workspace, and your Slack workspace may require an administrator to generate it. An organization can connect more than one workspace. If your deployment has a Slack manager app (see [Slack Manager App](https://everruns.com/docs/sre/environment-variables/#slack-manager-app)), **Settings** > **Slack workspaces** shows **Connect with Slack** instead: approve Everruns in Slack, pick the workspace, and nothing is copied or pasted. **Use a configuration token instead** keeps the steps above available. Each Agent’s app still asks for its own Slack approval when you add it. **Disconnecting a workspace** does not affect Agents already in it: each has its own Slack app and keeps working. Until you connect the workspace again, you cannot add Agents to it or update their Slack apps. ## Connect an Agent to Slack ### 1. Create a Slack Channel 1. Open the Agent. 2. Select **Channels and triggers**. 3. Select **Add channel**. 4. Select **Slack**. 5. If your organization has connected more than one Slack workspace, choose one. 6. Choose the session strategy. Leave the Slack credentials empty. 7. Select **Create channel**. Everruns opens the channel editor after it saves the channel. ### 2. Publish the Channel Select **Publish** in the channel editor. Publishing makes only this channel live. Publish before you create the Slack app. The generated Slack manifest contains the channel’s Request URL, and Slack verifies that URL when it creates the app. ### 3. Add the Agent to Slack Select **Add to Slack** in the channel editor. Everruns creates the Agent’s Slack app in the chosen workspace and opens Slack’s consent screen with that workspace selected. Approve it, and Everruns stores the app’s signing secret, bot token, and workspace ID on this channel. The channel then shows **Live in Slack** with an **Open in Slack** link. If your Slack workspace requires administrators to approve apps, Slack sends an approval request instead of installing straight away. Deployments without `SECRETS_ENCRYPTION_KEY` do not create Slack apps. If Everruns reports that one-click setup is unavailable: 1. Return to the Agent’s **Channels and triggers** tab. 2. Expand the live Slack channel. 3. Select **Create Slack app**. 4. Review Slack’s pre-filled manifest and select **Create**. 5. Install the app to your workspace. 6. Copy the **Signing Secret** from **Basic Information**. 7. Copy the **Bot User OAuth Token** (`xoxb-...`) from **OAuth & Permissions**. 8. Select **Configure** on the channel, enter both values, and select **Save**. The manifest already contains the bot scopes, event subscriptions, interactivity URL, and canonical channel Request URL:
```text
https://your-everruns-host/api/v1/channels/{channel_id}/slack/events
```
Do not replace `{channel_id}` with an Agent ID or an App ID. ### 4. Invite and Test 1. In Slack, enter `/invite @botname` in a channel. 2. Mention the bot or send it a direct message. 3. Return to the Agent’s **Channels and triggers** tab and expand the Slack channel. 4. Confirm that the setup checklist records the first message. ## Configure a Slack App Manually Use this flow only when you cannot use **Add to Slack** or **Create Slack app**. 1. Create and publish a Slack channel from the Agent’s **Channels and triggers** tab. 2. Copy its Request URL from the expanded channel row. 3. In [Slack API Apps](https://api.slack.com/apps), select **Create New App** > **From scratch**. 4. Add these bot token scopes under **OAuth & Permissions**: * `chat:write` * `channels:history` * `groups:history` * `im:history` * `mpim:history` * `app_mentions:read` * `users:read` 5. Add these bot events under **Event Subscriptions**: * `message.channels` * `message.groups` * `message.im` * `message.mpim` * `app_mention` 6. Paste the channel Request URL into Slack’s **Request URL** field. 7. Install the Slack app to your workspace. 8. Copy the signing secret and bot token into the channel’s **Configure manually** fields. For Socket Mode, skip step 6: turn on **Socket Mode** under **Settings** instead, and copy an app-level token in place of the signing secret. 9. Save the channel. ## Existing Installs Existing Slack installs that use `/v1/apps/{app_id}/…` URLs continue to work. Everruns keeps those routes as permanent compatibility aliases. New installs use `/v1/channels/{channel_id}/…`, which is the canonical channel-owned form. ## Channel Configuration | Field | Required | Description | | ----------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connection` | No | `request_url` by default, or `socket_mode`. See [Socket Mode or Request URL](#socket-mode-or-request-url). | | `app_token` | For Socket Mode | App-level token (`xapp-...`) with the `connections:write` scope. Write-only: reads report `app_token_configured`. | | `signing_secret` | Before use | For Request URL. Slack app signing secret for HMAC-SHA256 verification. It can be empty while you create the channel, but the channel rejects all Slack requests until it is set. | | `bot_token` | Before use | Bot User OAuth Token (`xoxb-...`) for sending responses. It can be empty while you create the channel. | | `channel_id` | No | Restrict the channel to one channel, such as `C0123456789`. | | `team_id` | No | Slack workspace ID. | | `session_strategy` | No | `per_channel` for new channels, `per_thread`, or `per_user`. A stored channel that never set it reads as `per_thread`. | | `response_policy` | No | `relevant_messages` for new channels, `mentions_only`, or `all_messages`. A stored channel that never set it reads as `all_messages`. | | `agent_surface_enabled` | No | `false` by default. Also serve Slack’s agent pane; see [Agent Surface](#agent-surface). | ## Agent Surface Slack apps can also appear as an **agent**, a dedicated assistant pane separate from channel conversations. Enabling `agent_surface_enabled` adds this pane without changing channel replies. The generated manifest adds: * the `features.agent_view` block with an `agent_description` derived from the Agent; * the `assistant:write` bot scope; and * the `app_home_opened`, `app_context_changed`, `agent_session_stopped`, and `agent_session_title_changed` bot events. Enabling the pane on an existing Slack app requires a reinstall because a configuration change cannot grant the new `assistant:write` OAuth scope. Generate a fresh manifest, update the Slack app, and reinstall it. Channel replies continue while you do this. Session strategy in the pane is always `per_thread`. The configured strategy still applies to channel conversations. ### Streaming Replies Replies in the agent pane render as the Agent produces them. Channel threads receive one finished message instead of token-by-token updates. ## How the Agent Replies How the Agent talks in Slack is set on the Agent, not on the channel. See the Agent’s **Communication** setting and [Explicit communication](https://everruns.com/docs/features/explicit-communication/). | Agent communication | What people see in Slack | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Direct** (default) | Every assistant response is published. Replies stream in the agent pane. | | **Explicit** | The Agent posts only what it sends with `send_message`. Its other assistant text stays in Everruns as working notes. It can call `no_reply` to choose not to answer. | With explicit communication, `send_message` posts into the thread that started the turn, as this channel’s bot, at most once per call. The Agent cannot choose another channel or thread. Messages can be up to 12,000 characters of Markdown. To share files the Agent made, it lists their session paths in `send_message`’s `files` (up to 10 files, 8 MiB combined). Slack shows them in the same thread, right under the text. The bot needs the `files:write` scope. Success means Slack accepted the post; the `conversation.message` event carries `platform`, `channel` and `message_ref`. For Slack, `message_ref` is the message timestamp: use it as `timestamp` with `slack_update_message` when the Slack actions capability is enabled. If delivery is uncertain, the error says so; the Agent should not resend blindly because the message may already be visible. A turn started by a session schedule (the Agent’s `create_schedule`) has no Slack message of its own. Its `send_message` goes to the conversation of the session’s latest Slack message: inline in a direct message, top-level in a `per_channel` channel, and in the thread for a `per_thread` session. A session that has never received a Slack message cannot post. To run on a clock in a conversation from the start, before anyone has written, give a schedule trigger a Slack target instead: see [Run in a Slack conversation](https://everruns.com/docs/features/agent-triggers/#run-in-a-slack-conversation). The agent pane shows a working status while the turn runs. Approval cards and task progress appear independently of the Agent’s messages. If a turn ends without anything posted to the thread, or an explicit Agent’s turn fails or is cancelled, Everruns posts one short status line with a link to the session. An explicit Agent that calls `no_reply` chose silence, so its thread gets no status line. ### Formatting Agents write standard Markdown, and Everruns posts it as Slack `markdown` blocks, so headings, lists, tables, quotes, links and fenced code render as written. Slack differs from GitHub Markdown in a few places: | Markdown | In Slack | | -------------------------------------- | -------------------------------------------------------------------------------------------- | | `<@U0123ABCD>` | Mentions that person. A plain `@name` is text and notifies no one. | | `` | A link, not an image. Share images as files: `send_message` `files`, or `slack_upload_file`. | | HTML, footnotes, math | Shown as raw text. | | `#####` and deeper | Rendered as a level 4 heading. | | ``, ``, `` | Posted as plain `@here` text: an Agent never notifies a whole channel. | If Slack rejects a reply’s blocks, for example over a mention of a user group that does not exist, Everruns posts the same reply once more as plain text so it still arrives. Agents with the [Slack actions](#slack-actions) capability get these rules in their instructions. ## Session Strategies | Strategy | Behavior | Tag Pattern | | ------------- | ---------------------------------------- | -------------------------- | | `per_thread` | Each Slack thread is a separate session. | `slack:thread:{thread_ts}` | | `per_channel` | One session serves the channel. | `slack:channel:{channel}` | | `per_user` | One session serves each Slack user. | `slack:user:{user}` | New channels start with `per_channel`, so the agent keeps one conversation per Slack channel. Use `per_thread` when every thread is a separate request, such as a support queue. ## How It Works ### Architecture  ### Message Flow  **Inbound path:** 1. Slack posts a message event to `/v1/channels/{channel_id}/slack/events`. 2. The channel verifies the signing secret and rejects duplicates. 3. Everruns acknowledges Slack within three seconds. 4. The channel finds or creates a session from the configured strategy. 5. Everruns creates a user message and starts an Agent turn. **Outbound path:** 6. The Slack delivery dispatcher watches the turn. 7. For a Direct Agent, the TurnAgent emits completed output messages and the dispatcher posts them. 8. For an Explicit Agent, `send_message` posts messages directly and returns delivery receipts. 9. Automatic delivery retries transient failures with exponential backoff. `send_message` returns errors without retrying an uncertain send. 10. The dispatcher unregisters when the turn completes, fails, or is cancelled. ## Troubleshooting ### URL Verification Failed * Confirm that the channel is published. * Confirm that `PUBLIC_APP_URL` is a public HTTPS origin and that Everruns restarted after the value changed. * Confirm that the Request URL contains `/v1/channels/{channel_id}/slack/events`. ### Bot Does Not Respond * Confirm that the channel is published and enabled. * Invite the bot to the channel with `/invite @botname`. * Confirm that the Slack app has the required bot events and the `chat:write` scope. * Confirm that the channel has the correct signing secret and bot token. ### Request Verification Failed * Confirm that the channel’s signing secret matches the value under the Slack app’s **Basic Information** page. * Confirm that the Everruns server clock is accurate. ## Approvals When an Agent pauses for approval, Slack renders **Approve** and **Decline** buttons in the thread. Only the person whose message the Agent is answering can use them. Enable **Private approval cards** in the channel’s conversation settings to show approval details only to the requester. This is opt-in; existing channels keep thread-visible cards. Through the channel API, set `private_approvals` in the Slack `channel_config`:
```json
{
"private_approvals": true
}
```
Private cards use Slack ephemeral messages, which may disappear when the person reconnects and are not guaranteed to be delivered while they are inactive. If a card disappears or cannot be delivered, open the session in Everruns and answer the pending request there. The pending request and single-use checks remain in durable session storage across server restarts; disappearing cards never grant approval. A stale or already-answered card cannot approve a new request. Failed private delivery never falls back to posting the question in the public thread. This setting protects the approval card, not the entire conversation. Agent replies, including the result after approval, still follow the channel’s normal visibility. It does not change who can approve or grant access to the session in Everruns. The generated manifest already points Slack interactivity at this channel. A Slack app created before interactive approvals existed must save a fresh manifest once. ## Task Progress When an Agent delegates work, Slack shows one **Tasks** message and updates it as workers finish. The message lists up to five tasks and summarizes larger groups by count. ## Reactions Reactions work both ways on messages the conversation stored: the messages people sent and the agent’s replies. * An emoji a person adds or removes in Slack is stored on that message as theirs, and reaches the agent as a short note, the same as a reaction in Chat. * When the agent reacts with the **Reactions** capability’s `react` tool, the emoji also appears on the Slack message. ### Acknowledging messages With the **Reactions** capability, an agent reacts 👀 when it starts working on a Slack message and ✅ once it has answered, so people in the thread can see it got the message before the reply arrives. This is a default in the capability’s instructions, not an automatic reaction: the agent’s own instructions win, so write “Don’t react to messages” or “Use 🫡 instead of 👀” to change it. It applies to Slack messages only; Everruns chat already shows live progress. Connecting an agent’s first Slack channel turns the Reactions capability on, recorded in the agent’s history. Remove it in the agent’s capabilities if you do not want reactions; adding another Slack channel does not turn it back on. Agent checks suggest it for an agent that answers Slack without it. Hearing reactions needs the `reactions:read` scope and the `reaction_added` and `reaction_removed` events, which the generated manifest includes. An app installed before them keeps working without reactions: update its manifest and reinstall the app to turn them on. Custom workspace emoji are stored as `:name:`. ## Slack actions | | | | ---------------- | --------------- | | **ID** | `slack` | | **Category** | Integrations | | **Features** | `slack_actions` | | **Dependencies** | None | An agent published to a Slack channel can reply in its thread. The `slack` capability lets it do the rest, as the same bot the workspace invited: react to a message, rewrite one it posted, share a file, or resolve a user ID to a name. No second credential. The tools resolve the channel’s own bot token server-side, so there is nothing extra to provision, scope, or rotate. ### Requirements The tools only work in a session a Slack message created. An agent that has the capability enabled but is running from the API, a schedule, or another channel has no Slack channel to act as, and every tool returns an error saying so rather than acting as some other channel’s bot. Where an agent carries two Slack channels, each with its own bot, the tools act as the channel that created the session. Your Slack app needs the scope for each action you use: `reactions:write` for reactions, `chat:write` for updates, `files:write` for uploads, and `users:read` for lookups. Slack answers a missing scope with an error the agent sees. ### Tools #### `slack_add_reaction` Slack messages include their exact channel and timestamp in the agent’s context. The agent uses that reference to target a reaction; a message’s date or rounded timestamp cannot identify it. If a bot was installed before reaction permission was included, reconnect the Slack app and approve `reactions:write`. Deploying an updated manifest does not add permissions to an existing bot token. Add an emoji reaction to a message. The cheapest acknowledgement available — prefer it over posting “working on it”. | Parameter | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------- | | `channel` | string | yes | Channel ID the message is in | | `timestamp` | string | yes | The message’s `ts` | | `name` | string | yes | Emoji name without colons (e.g. `eyes`) | Reacting with an emoji that is already there succeeds; the result says `already_reacted`. #### `slack_update_message` Rewrite a message this bot posted. Use it to turn a status message into its result instead of posting a second message. | Parameter | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------------- | | `channel` | string | yes | Channel ID the message is in | | `timestamp` | string | yes | The `ts` of the bot message to rewrite | | `text` | string | yes | Replacement text; Markdown is rendered | Only messages this bot posted can be updated. #### `slack_lookup_user` Resolve a Slack user ID to that person’s display name, real name, timezone, and whether they are a bot. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------- | | `user_id` | string | yes | Slack user ID (the `<@U…>` mention form is accepted) | Returns only those addressing fields. Email, phone, and title are not exposed to the agent. #### `slack_upload_file` Share inline text or an existing session file into the Slack thread this session is in. The Agent does not name the channel or thread: Everruns uses the session’s own conversation. The bot needs the `files:write` scope. Reconnect an existing install to grant that scope. An Agent with explicit communication should attach files to `send_message` instead, so they arrive with its message. This tool is for Agents that reply directly. | Parameter | Type | Required | Description | | ----------------- | ------ | ----------- | ---------------------------------------------------------------- | | `filename` | string | yes | Filename shown in Slack, including its extension | | `content` | string | conditional | Inline text. Supply exactly one of `content` and `session_path`. | | `session_path` | string | conditional | Existing text or binary file in the session workspace | | `initial_comment` | string | no | Message posted alongside the file | Content is capped at 8 MiB. ### Notes * Posting to an arbitrary channel is deliberately not offered. The blast radius of “anywhere the bot is” is wider than “the thread that asked”. The control plane verifies the channel and thread against trusted session metadata before sending an action to Slack. * A retired or disabled channel stops acting immediately, even for a session it created earlier. * Slack rate limits reach the agent with Slack’s own retry advice rather than as a generic failure. * The [Slack MCP server](https://everruns.com/docs/features/mcp/) stays supported for anything this does not cover. This removes the second credential for the common cases; it does not replace MCP. ## See also * [Publish an Agent to Slack](https://everruns.com/docs/how-to/publish-to-slack/): a step-by-step guide. * [Channels](https://everruns.com/docs/features/channels/): every channel type and the channel lifecycle. * [Slack API Documentation](https://api.slack.com/docs) and the [Slack Events API](https://api.slack.com/events-api).
---
# Soft Approval
> Prompt-level consent gate. The agent pauses and asks before destructive or outward-facing actions, and runs safe work without interruption.
Source:
| | | | ---------------- | ---------------------------------------------------------- | | **ID** | `soft_approval` | | **Category** | Safety | | **Tools** | `request_approval`, `record_approval`, `set_approval_mode` | | **Features** | None | | **Dependencies** | None | Soft approval asks the agent to stop and get the user’s consent before a critical action, and to run everything else without asking. It works through the system prompt and three tools. It is guidance for the model, not an enforcement point: a call the model makes still runs. When a call must not run without a person’s decision, use [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) instead. That gate holds the call until someone approves it, whatever the model does. [Base](https://everruns.com/docs/built-ins/harnesses/base/) and every harness built on it, the deprecated [Generic](https://everruns.com/docs/built-ins/harnesses/generic/) and the [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) include soft approval at the `normal` level. ## Levels | Mode | The agent asks before | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `off` | Nothing. The capability adds no prompt. | | `auto` | Only when unsure whether a person wants the action, or told to wait. Pair it with [Tool Approval’s auto mode](https://everruns.com/docs/capabilities/tool-approval/#auto-mode), where a reviewer model answers routine calls; when the reviewer blocks one, the agent asks here, records the yes and retries. | | `normal` (default) | Destructive or irreversible actions (deleting files or data, dropping records, force-push, history rewrites) and outward-facing ones (pushing, publishing, opening pull requests, sending messages or mail, deploying, spending money). Ordinary edits and local, reversible changes proceed. | | `protective` | Any action that changes state: writing or deleting files, commits and pushes, installing or removing packages, requests with side effects, changes to shared resources, and any command that is not plainly read-only. | At every level except `off`, the prompt tells the agent to plan, batch the safe steps, and never pause on read-only inspection. ## Configuration
```json
{
"ref": "soft_approval",
"config": { "mode": "normal" }
}
```
`mode` accepts `off`, `auto`, `normal`, or `protective`, and the synonyms listed under [`set_approval_mode`](#set_approval_mode). Any other value fails validation. ## Tools ### `request_approval` The agent calls it at a critical action, then ends its turn. The call is the pause: it tells the user the agent is waiting. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------- | | `action` | string | Yes | The action awaiting approval, for example “delete the staging database” | | `question` | string | No | One short question for the user. Defaults to “Go ahead?” | The result carries `awaiting_approval: true`, the action and question, and the turn and input message it was asked in. ### `record_approval` After the user says yes, the agent calls it with what was approved, then carries the action out. A plain affirmative counts as approval; a hesitant or negative reply does not. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------------------------------- | | `action` | string | Yes | The specific action the user approved | | `detail` | string | No | Extra context such as the command or scope. It is logged, so it must not contain secrets. | The result records the turn and input message the consent was given in. An auditor can join that message to the host’s own record of who sent it. One approval covers one action. A category the user pre-authorizes (“no need to ask for commits”), or a workflow the user invoked by name, covers the actions it names; the agent records that grant once. ### `set_approval_mode` When the user asks the agent to be more or less careful, the agent calls it with `mode`. It accepts `protective`, `normal`, `auto`, and `off`, plus synonyms such as `paranoid`, `careful`, `default`, and `yolo`. The new level overrides the configured `mode` for that session from the next turn on. It changes only this prompt layer, never the enforced [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) gate. ## Relation to Ask User [Ask User](https://everruns.com/docs/capabilities/ask-user/#not-a-consent-gate) questions auto-resolve, so an answer to them never grants permission. Soft approval’s wait does not auto-resolve. The interactive harnesses enable both, so the agent has a place for preference questions and a separate place for consent. ## See also * [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/), the hard approval gate * [Ask User](https://everruns.com/docs/capabilities/ask-user/), structured questions to the user * [Guardrails](https://everruns.com/docs/capabilities/guardrails/), config-driven checks over output and tool activity
---
# SQL Database
> Session-scoped SQLite databases: create tables, run queries, and persist relational data per session.
Source:
## Framework Enable the `sql-database` Cargo feature and bind application-owned services with `.sql_database(databases)`. See [Framework services](https://everruns.com/docs/framework/data-services/) for credentials, persistence and a complete real-model example. The remaining setup sections describe the hosted Platform. | | | | ---------------- | ---------------------- | | **ID** | `session_sql_database` | | **Category** | Data | | **Features** | `sql_database` | | **Dependencies** | None | Session-scoped SQLite databases for structured data storage. Create tables, insert data, and run queries, all isolated to the current session. ## Tools ### `sql_execute` Run DDL/DML statements (CREATE TABLE, INSERT, UPDATE, DELETE). | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------- | | `database` | string | yes | Database name (alphanumeric and underscores); created if missing | | `sql` | string | yes | SQL statement to execute | ### `sql_query` Run SELECT queries. Results limited to 1000 rows. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ------------- | | `database` | string | yes | Database name | | `sql` | string | yes | SELECT query | ### `sql_schema` Introspect the database schema, list tables, columns, and types. | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------- | | `database` | string | yes | Database name | | `table` | string | no | Table name; omit to list all tables | ## Notes * Database is session-scoped, destroyed when the session ends * SELECT queries return at most 1000 rows * Standard SQLite SQL syntax ## See Also * [Storage](https://everruns.com/docs/capabilities/session-storage/), simpler key/value alternative * [File System](https://everruns.com/docs/capabilities/file-system/), file-based data storage * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Sub Agents
> Spawn subagents that run tasks in isolated context windows, through the generic session task tools.
Source:
| | | | ---------------- | ----------- | | **ID** | `subagents` | | **Category** | Core | | **Features** | `subagents` | | **Dependencies** | None | Spawn subagents for parallel task execution. Each subagent runs in its own isolated context window, allowing the parent agent to delegate verbose or independent tasks without cluttering the main conversation. Subagents inherit the parent’s harness and agent configuration but operate with their own message history. ## Tools ### `spawn_agent` Sessions with `subagents` expose `target.type: "subagent"` in the shared `spawn_agent` dispatcher. If first-party handoffs or external A2A delegation are also active, the same tool advertises those target types too. The dispatcher returns a `task_id` for the generic session task tools and moves Everruns toward one delegation surface across subagents, first-party agent handoffs, and external A2A agents. Create and start a new subagent by calling `spawn_agent` with `target.type: "subagent"`. By default the subagent runs in the background: the tool returns immediately with a `task_id`, the parent agent keeps working, and the session is notified when the subagent finishes. Use the `task_id` with the generic session task tools to monitor, message, or cancel the subagent. | Parameter | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | Human-readable name for the subagent. Must be unique within the session. | | `instructions` | string | yes | Instructions for what the subagent should do. This becomes the subagent’s initial prompt. | | `target.type` | string | yes | Must be `subagent`. | | `mode` | string | no | `background` (default) returns immediately with a `task_id`; `foreground` blocks until the subagent completes and returns its result inline. | | `model` | string | no | A helper model key from the agent’s list (built in: `same`, `fast`, `coding`, `deep`, `second_opinion`). Omit to run on the parent’s model, or on Auto to let the Decision model pick. Only shown when the agent may switch models. | | `blueprint` | string | no | Optional specialist blueprint ID, such as `github_scout`, that supplies its own prompt, model, and private tools. | | `config` | object | no | Blueprint-specific configuration, validated against the blueprint’s schema before the child session is created. Only valid when `blueprint` is set. | ## Helper models An agent lists the models its subagents may run on as **helper models**: keys the spawning model names, each with a “when to use” line. The model never sees or names a raw model; each key points at a job of the agent’s preset or the organization defaults, a job of another preset, a model of the organization, or another provider’s preset. | Key | Runs on | Typical use | | ---------------- | ----------------------------------------------------- | -------------------------- | | `same` | The parent’s model (the default) | Most subagents | | `fast` | The Small job | Search, lookups, summaries | | `coding` | The Coding job | Implementation work | | `deep` | The Research job | Hard reasoning, planning | | `second_opinion` | The Default job of a provider other than the parent’s | Verifier, reviewer | Edit the list on the agent page under **Helper models**: repoint or remove built-in keys, add your own (for example `gemini` on the Gemini preset), and choose who picks: the agent, or **Auto**, where the organization’s Decision model reads the task and picks a key. Keep only `same` to stop subagents from switching models. The list lives in the Subagents capability config (`helper_models`, `helper_model_pick`), so the API, MCP, CLI and agent packages carry it:
```json
{"ref": "subagents", "config": {
"helper_models": [
{"key": "same", "when": "Most work.", "target": {"type": "same"}},
{"key": "verifier", "when": "Review a finished change.",
"target": {"type": "other_provider", "job": "default"}}
],
"helper_model_pick": "agent"
}}
```
The subagent keeps the resolved model for follow-ups, and the session’s Subagents tab shows each subagent’s key, model and who picked it. ## Managing subagents after spawn Use the generic `session_tasks` tools to monitor and steer subagents after spawning. The `task_id` is returned by `spawn_agent`. * `list_tasks` with `kind: "subagent"`, list all subagent tasks and their status * `get_task` with the task ID, get detailed status and result for a specific subagent * `message_task`, send a steering message or additional context to a running subagent * `cancel_task`, request cooperative cancellation of a subagent; returns the task’s state after the cancel request plus its recent messages, the same shape as `get_task` * `wait_task`, block until a subagent reaches a terminal or interrupted state Repeated `list_tasks` polls can pass the previous response’s `snapshot` as `since`, using the same filters. If nothing changed, the response contains `unchanged: true`, `count`, and `snapshot` instead of repeating the tasks. Progress, pending input requests, state details, and outcomes still trigger a fresh list. Omit `since` to retrieve the list again, or use `get_task` for full details. When you only need to wait for completion or a request for input, prefer `wait_task` over polling. ## Notes * **Governed spawning**: subagents can spawn nested subagents up to `max_subagent_depth` (default 2); set it to 0 to block subagent spawning. Each root session also has `max_active_descendant_tasks` (default 16) and `max_total_descendant_tasks` (default 200) caps to bound wide fan-out and repeated spawn loops. * **Shared budget pool**: nested subagents spend from the root session’s session-scoped budget. * **Background mode (default)**: spawning returns immediately with a `task_id`. The final result lands on the task record (`summary` via `get_task`), and the parent session is woken when the subagent reaches a terminal state. Background runs are capped at 6 hours. * **Foreground mode**: `mode: "foreground"` blocks until the subagent completes and returns its result inline. Foreground execution has a 5-minute timeout. * **Inherited configuration**: subagents inherit the parent’s harness and agent configuration, and the model you chose for the parent chat unless the spawn names a helper key. * **Blueprints**: specialist blueprints can run with their own prompt, model, and private tools while still using the same subagent lifecycle. ## See Also * [Agent handoff](https://everruns.com/docs/capabilities/agent-handoff/), task monitoring and control (`list_tasks`, `get_task`, `message_task`, `cancel_task`, `wait_task`) * [Author an agent blueprint](https://everruns.com/docs/framework/agent-blueprints/), contributing a specialist agent with a typed configuration contract * [GitHub Scout](https://everruns.com/docs/capabilities/github-scout/), blueprint-only GitHub repository exploration * [A2A](https://everruns.com/docs/features/a2a/), delegating to external agents with `target.type: "external_a2a"` * [Session](https://everruns.com/docs/capabilities/session/), session metadata and lifecycle * [Platform](https://everruns.com/docs/capabilities/platform/), agent and platform configuration * [Capabilities Overview](https://everruns.com/docs/capabilities/), full list of available capabilities
---
# Task Management
> Structured task lists for tracking multi-step work within a session.
Source:
| | | | ---------------- | --------------------- | | **ID** | `stateless_todo_list` | | **Category** | Core | | **Features** | None | | **Dependencies** | None | Enables agents to create and manage structured task lists. State is maintained in conversation history, each tool call sends the complete list. ## Tools ### `write_todos` Create or update the complete task list. Each call replaces the entire list. | Parameter | Type | Required | Description | | --------- | ----- | -------- | -------------------------------------------------- | | `todos` | array | yes | Array of `{ content, status, activeForm }` objects | Task statuses: `pending`, `in_progress`, `completed`. ### `report_done` Report finished work once, before the final reply: what was done, how it was checked, and links to what it produced. The session’s work report shows this summary instead of the first sentence of the reply, and a coordinated worker’s `complete_assignment` is read the same way. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------- | | `summary` | string | yes | One or two sentences, leading with the result | | `validation` | string | no | How the work was checked | | `outcome` | string | no | `done` (default) or `failed` | | `artifacts` | array | no | Up to 10 `{ name, type, url?, path? }` links | ## Notes * **Stateless**: no database table; state lives in conversation history * Each `write_todos` call must include the **complete** list (not incremental updates) * Best practice: exactly one task `in_progress` at a time * Only mark a task `completed` when fully done (tests pass, no errors) * `activeForm` is the present-continuous label shown during execution (e.g., “Running tests”) ## See Also * [Session](https://everruns.com/docs/capabilities/session/), session metadata management * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Tool Approval
> Hold back risky tool calls until a person approves them. The call does not run until someone says yes.
Source:
| | | | ---------------- | --------------- | | **ID** | `tool_approval` | | **Category** | Safety | | **Tools** | None | | **Dependencies** | None | A hard approval gate. Before a risky tool runs, the turn pauses and a person decides. Unlike [soft approval](https://everruns.com/docs/capabilities/ask-user/#not-a-consent-gate), which asks the model to pause, this gate does not depend on the model: a call nobody approved does not run. ## What gets gated Each tool declares what it does, and the gate reads those declarations rather than guessing from names: | Mode | Asks before | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `normal` (default) | Tools that declare themselves destructive or outward-facing (they reach outside the session), and tools that declare they require approval | | `protective` | Anything not declared read-only. A tool with no declarations counts as one that changes state | | `auto` | The same calls as `protective`, but a reviewer model answers first and asks a person only when it will not decide. See [Auto mode](#auto-mode) | | `off` | Nothing | A tool cannot avoid the gate by declaring itself read-only and outward-facing at the same time. ## Configuration
```json
{
"ref": "tool_approval",
"config": {
"mode": "auto",
"timeout_seconds": 900,
"rules": [
{ "tool": "github_merge_*", "action": "ask" },
{ "tool": "send_email", "action": "never" }
],
"auto": { "notes": ["github.com/acme is our organization; pushing branches there is routine."] }
}
}
```
| Field | Default | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mode` | `normal` | `off`, `auto`, `normal`, or `protective` | | `timeout_seconds` | `900` | How long a request waits for an answer before it counts as rejected (60 to 86400) | | `rules` | none | Tool name patterns (`*` matches anything) with `allow` (run without asking), `ask` (always a person) or `never` (blocked). The strictest match wins, in every mode. At most 50 | | `auto.notes` | none | Plain sentences the auto reviewer reads: what you trust, what counts as production. At most 20 | ## Auto mode Long tasks stall when every routine call waits for a person. In `auto` mode a reviewer model looks at each call the gate would hold and answers: * **Allow**: the call runs. * **Block**: the call does not run and the agent is told which rule it broke. The agent can ask you in chat; once you say yes, its retry is allowed. * **Ask a person**: the call waits for you as in any other mode. The reviewer sees what people wrote in the session, the agent’s tool calls since the last message, the call itself and your trust notes. It never sees the agent’s own text, tool output or tool descriptions, so instructions hidden in a web page or a file cannot talk it into anything. It blocks by default anything that sends data out, deletes what already existed, contacts people, spends money, changes access or production, acts in bulk, or goes beyond what a person asked for. When the reviewer is unavailable or unsure, a person decides: it never lets a call through by default. After 3 blocks in a row, or 20 in a session, it stops reviewing and every call goes to a person until someone approves one. Tools that always require approval, and tools with an `ask` rule, always go to a person. Each verdict is recorded as a `tool.reviewed` session event and in the organization audit log as `agent.approval.auto_reviewed`. ## Who picks the mode The agent’s config sets the mode. A person can change it for one session from the **Approvals** button in the session header, and set their own default for all their sessions in **Settings → My approvals**. The same from the API:
```bash
everruns sessions approval-mode set --session-id $SESSION_ID --mode auto
curl -X PUT "$EVERRUNS_API/v1/user/preferences/tool_approval" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"value": {"default_mode": "auto", "rules": [{"tool": "send_*", "action": "ask"}]}}'
```
Personal rules can only add caution (`ask` or `never`). A person cannot turn the gate off for an agent whose config turned it on: `off` runs as `auto`. Organization admins can limit the modes and add rules and trust notes for every agent in **Settings → Approvals**, which also lists the reviewer’s recent verdicts, or with `tool_approval_policy` on `PATCH /v1/orgs/{org}`:
```json
{
"tool_approval_policy": {
"allowed_modes": ["auto", "normal", "protective"],
"rules": [{ "tool": "*_delete_*", "action": "ask" }],
"trust_notes": ["Only the prod-* clusters are production."]
}
}
```
A mode the organization does not allow runs as the next more careful one. ## Answering a request When a call is held back, the session waits with status `waiting_for_tool_results` and emits a `tool.call_requested` event containing one `approve_tool_call` call per held-back call. Its arguments show the tool, the arguments it would run with, why it was gated, and the deadline. The session UI renders these as approval cards. Answer them with:
```bash
curl -X POST "$EVERRUNS_API/v1/sessions/$SESSION_ID/tool-approvals" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"decisions": [{"tool_call_id": "tool_approval_toolu_01...", "decision": "allow"}]}'
```
| Decision | Effect | | --------------- | ----------------------------------------------- | | `allow` | This exact call may run, once | | `allow_always` | Every call of this tool in this session may run | | `reject` | This call does not run | | `reject_always` | No call of this tool runs in this session | All requests from one pause are answered together. A request left out of the submission is not approved. Answering requires permission to manage the session. After an answer the turn resumes and the agent calls the tool again. An `allow` covers only the call with exactly the arguments that were shown; different arguments are asked about again. If nobody answers before the deadline, the requests count as rejected and the turn resumes. Nothing is remembered, so the agent can ask again later. ## When to enable it Enable it for agents that can send messages, spend money, change production systems, or browse with [computer use](https://everruns.com/docs/capabilities/computer-use/): anything where one wrong call is expensive. An agent that runs unattended on a schedule or trigger will wait for the full timeout on every gated call and then carry on without it. `auto` cuts most of those waits; calls the reviewer hands to a person still wait. Use `off`, or leave the capability off, for agents nobody is watching.
---
# Tool Call Repair
> Detects and repairs malformed tool-call arguments from the model, recovering the turn instead of surfacing a raw parse error.
Source:
| | | | ---------------- | ------------------ | | **ID** | `tool_call_repair` | | **Category** | Safety | | **Features** | None | | **Dependencies** | None | | **Risk** | Low | Opt-in recovery net for malformed tool calls. Models occasionally emit tool-call arguments that are not clean JSON, wrapped in a Markdown code fence, surrounded by prose, with trailing commas or single quotes, or with values typed as strings where the schema wants numbers. Without repair, such a call either surfaces a parse error or silently collapses to empty arguments and fails downstream. This capability salvages the call so the turn proceeds. **Disabled by default.** The capability is registered so agents can enable it, but contributes nothing unless explicitly selected. With it off, behavior is byte-for-byte unchanged. ## Tools None, the capability intercepts inside the `reason` step, after the model’s tool calls are finalized and before the assistant message is built. ## How It Works 1. **Deterministic local salvage**: A pure function runs over each call’s `arguments`: it unwraps fenced code blocks and strips surrounding prose, removes trailing commas, normalizes single quotes to double quotes, and coerces string-typed known keys to the type declared by the tool’s JSON schema (e.g. `"42"` → `42` for an integer property). Optional keys the model filled with `null` or `"null"` where the schema does not accept it are dropped, since leaving the key out is what the model meant. An already-valid call is a no-op. 2. **Bounded corrective re-prompt**: When local salvage cannot recover a usable object, the capability allows up to `max_reprompts` attempts per call (default 1. before falling through to the normal error path. The re-prompt is realized by the agent loop: the unrepaired call proceeds to today’s error path and the model retries on the next iteration. The per-call cap guarantees there is no infinite repair loop. 3. **Observability**: Each malformed call emits one `tool.call_repaired` event carrying an outcome label: `local-salvage`, `re-prompt`, or `gave-up`. ## Configuration ### Default
```json
{
"capabilities": ["tool_call_repair"]
}
```
### Custom re-prompt cap
```json
{
"capabilities": [
{
"ref": "tool_call_repair",
"config": { "max_reprompts": 2 }
}
]
}
```
`max_reprompts` accepts `0`–`5`. `0` means “salvage locally or fall straight through to the error path with no re-prompt”. ## When To Enable Use this capability when: * You run models or providers that occasionally wrap tool arguments in prose or code fences, or emit lenient JSON (single quotes, trailing commas) * You want a malformed call to recover the turn rather than waste an iteration on a raw parse error ## Limitations * **Verbatim JSON only**: salvage extracts an embedded JSON object; it does not invent missing required fields or guess intent from natural language * **Bounded input**: argument blobs larger than 256 KiB are treated as un-salvageable without parsing (a denial-of-service guard against runaway model output) * **No deep type checking**: coercion handles top-level `integer` / `number` / `boolean` string values; full schema validation remains the tool’s job ## See Also * [Events](https://everruns.com/docs/features/events/), the streaming event protocol that carries `tool.call_repaired` * [Capabilities](https://everruns.com/docs/features/capabilities/), the extension model this capability plugs into
---
# Tool Search
> Deferred tool loading for agents with many tools, using the provider's hosted tool search on OpenAI and Claude models and a client-side search everywhere else.
Source:
Agents with many tools spend a large part of every prompt on tool parameter schemas. Tool search sends only tool names and descriptions up front and loads a tool’s full schema when the model needs it. Tool calls and results work the same way; only how schemas reach the model changes. Four capabilities provide it: | ID | Mechanism | Works on | On an unsupported model | | -------------------- | -------------------------------------- | ------------------------------------------------------ | -------------------------------- | | `auto_tool_search` | Picks one of the three below per model | Any model | Falls back to client-side | | `openai_tool_search` | OpenAI hosted tool search | GPT-5.4 and newer (`gpt-5.4*`, `gpt-5.5*`, `gpt-5.6*`) | Does nothing (full schemas sent) | | `claude_tool_search` | Anthropic hosted tool search | Claude 4 and newer, first-party API | Does nothing (full schemas sent) | | `tool_search` | Client-side `tool_search` tool | Any model | Not applicable | Use `auto_tool_search` unless you know the model and want one mechanism explicitly. It is what the [Worker](https://everruns.com/docs/built-ins/harnesses/worker/) harness uses. Do not combine `auto_tool_search` with any of the other three on the same agent; it already provides all three paths. An explicit `tool_search` with `bounded: true` overrides inherited automatic or hosted search, so an Agent can enforce a bounded catalog on a Worker harness. All four capabilities have category Optimization, no features, and no dependencies. ## Auto tool search `auto_tool_search` resolves to one of three underlying mechanisms based on the model: * **Models with native OpenAI tool search** (GPT-5.4 and newer) → the hosted mechanism described in [OpenAI Tool Search](#hosted-openai): namespaces + `defer_loading` + a `{"type": "tool_search"}` activator. No extra tool is added; the provider handles search server-side. * **Models with native Claude tool search** (Opus 4, Sonnet 4.6, Haiku 4.5, and Fable 5 and newer) → the hosted mechanism described in [Claude Tool Search](#hosted-claude): per-tool `defer_loading` + a `tool_search_tool_bm25_20251119` server tool. No extra tool is added; the provider handles search server-side. * **All other models** (Gemini, OpenAI Completions, Claude/GPT reached via a gateway that doesn’t implement the hosted format, …) → the client-side mechanism described in [Tool Search](#client-side): schemas are stripped to stubs and a `tool_search` tool loads them back on demand. The choice is made when the agent’s capabilities are assembled, once the model is known. You don’t have to know in advance which provider an agent will use. The dispatch looks at the **model id** (matched against the first-party OpenAI/Anthropic profiles), not the transport. In practice that handles the common gateway cases: a Claude model served via Amazon Bedrock or OpenRouter carries a distinct id (`anthropic.claude-…`, `anthropic/claude-…`) that doesn’t match the bare first-party profile, so `auto_tool_search` resolves to the client-side mechanism there. > **Edge case:** if a masked transport presents a *bare* first-party id that does resolve (e.g. a `gpt-5.4` served through an OpenAI-compatible gateway), `auto_tool_search` picks the hosted capability, but the driver then suppresses the hosted wire format for that transport, so full schemas are sent with **no** client-side fallback (a missed optimization, not a failure). If you run a first-party model id through such a gateway, add the [Tool Search](#client-side) capability explicitly to force client-side deferral. ### Tools One, the client-side `tool_search` tool, added only on models without native support. On models with native tool search, no tool is added and the provider’s hosted search is used instead. ### Configuration
```json
{
"capabilities": ["auto_tool_search"]
}
```
The default threshold is 15 tools. To change it:
```json
{
"capabilities": [
{
"ref": "auto_tool_search",
"config": { "threshold": 10 }
}
]
}
```
The threshold (minimum tool count before deferral activates) applies to every mechanism. Set it to `1` to always activate when the capability is present. ## Deferrable policy Each tool has a `deferrable` policy that controls whether its schema can be deferred: | Policy | Behavior | | ----------- | ------------------------------------------------------------------------- | | `never` | Full schema always sent (use for high-frequency tools like `write_todos`) | | `automatic` | Deferred when tool_search is active and above threshold (default) | | `always` | Always deferred when tool_search is active | ## Hosted: OpenAI `openai_tool_search` enables [OpenAI’s tool_search](https://platform.openai.com/docs/guides/tool-search). It configures the LLM driver and adds no tool. 1. **Threshold check**: tool_search only activates when the total tool count meets or exceeds the threshold (default: 15) 2. **Namespace grouping**: tools are grouped by their capability’s category into [namespace](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools) entries, giving the model semantic structure for discovery. Wire namespace `name` values are normalized to provider-safe identifiers (for example `File Operations` → `File_Operations`); descriptions keep the human-readable category label 3. **Deferred schemas**: tools marked as deferrable have `defer_loading: true` set, meaning only name + description are sent upfront 4. **`tool_search` entry**: a `{"type": "tool_search"}` activator is appended to the tools array, enabling the model’s built-in tool search index 5. **Transparent execution**: tool calls and results work identically; the only difference is how tools are presented to the model ### Model support Tool search requires model-level support. Currently supported: | Model family | Supported | | ---------------- | ----------------------------------- | | `gpt-5.6*` | Yes | | `gpt-5.5*` | Yes | | `gpt-5.4*` | Yes | | All other models | No (capability is silently ignored) | When the capability is enabled but the model doesn’t support tool_search, the feature is silently skipped, no errors, no behavior change. Configure it like `auto_tool_search`, with `"ref": "openai_tool_search"` and an optional `threshold`. ### Limitations * **OpenAI only**: tool_search is an OpenAI Responses API feature; other providers ignore this capability. * **Supported OpenAI models only**: earlier OpenAI models don’t support tool_search. * **No client-side tools**: currently only applies to built-in (server-executed) tools. See the [OpenAI Responses API tools parameter](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools) for the namespace and tool_search types. ## Hosted: Claude `claude_tool_search` enables [Anthropic’s hosted tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool). It configures the LLM driver and adds no tool. 1. **Threshold check**: tool search only activates when the total tool count meets or exceeds the threshold (default: 15). Below the threshold, full schemas are sent as usual. 2. **Deferred schemas**: every deferrable tool gets `defer_loading: true`, so only its name and description reach the model upfront. Anthropic defers each tool individually (there is no namespace grouping). 3. **Hosted search tool**: a `tool_search_tool_bm25_20251119` server tool is added to the request. The model issues a natural-language query against the catalog (tool names, descriptions, argument names, and argument descriptions) and Anthropic returns the 3–5 most relevant tools, expanding them into full definitions inline. 4. **Transparent execution**: the model then calls a discovered tool with a normal `tool_use`; tool calls and results work identically. The only difference is how tools are presented to the model. Because the hosted search tool is itself never deferred, Anthropic’s requirement that *at least one tool be non-deferred* is always satisfied, even when every function tool is deferrable. Keeping the 3 to 5 most frequently used tools non-deferred (policy `never`) avoids a search round-trip before the agent’s first hot-path call. ### Model support Tool search requires model-level support. Per Anthropic, it is available on: | Model family | Supported | | ------------------------------------------------------------------------------ | ----------------------------------- | | Opus 5.5 / 5 (`claude-opus-5-5`, `claude-opus-5`) | Yes | | Opus 4.x (`claude-opus-4*`) | Yes | | Sonnet 5.5 / 5 (`claude-sonnet-5-5`, `claude-sonnet-5`) | Yes | | Sonnet 4.6 (`claude-sonnet-4-6`) | Yes | | Haiku 5.5 / 4.5 (`claude-haiku-5-5`, `claude-haiku-4-5`) | Yes | | Fable 5.2 / 5.1 / 5 (`claude-fable-5-2`, `claude-fable-5-1`, `claude-fable-5`) | Yes | | Mythos 5.2 (`claude-mythos-5-2`) | Yes | | Retired pre-4 Claude models | No (capability is silently ignored) | When the capability is enabled but the model doesn’t support tool search, the feature is **silently skipped, full tool schemas are sent as usual**. This standalone capability does *not* add a client-side fallback: on an unsupported model it simply does nothing (no error, no behavior change). For automatic fallback to client-side deferral, use [Auto Tool Search](#auto-tool-search) (or add the [Tool Search](#client-side) capability explicitly). Claude models reached through a non–first-party transport don’t get hosted tool search either, because those transports don’t implement the hosted format: * **Amazon Bedrock**: this integration uses the ConverseStream API; Anthropic’s server-side tool search on Bedrock is only available via the InvokeModel API. * **OpenRouter**: its stateless OpenAI-compatible endpoint accepts but does not implement Anthropic’s hosted tool search. With `claude_tool_search` alone, those transports also send full schemas; pair with [Auto Tool Search](#auto-tool-search) to get client-side deferral there instead. Configure it like `auto_tool_search`, with `"ref": "claude_tool_search"` and an optional `threshold`. ## Client-side `tool_search` implements tool search entirely client-side, so it works with Gemini, OpenAI Completions, models reached through gateways that don’t implement hosted search, and any other provider. Bounded search and CLI `tools search` normalize Unicode accents and segment multilingual words. For example, `仓库` matches `搜索仓库问题`, and composed `café` matches the same word written with a combining acute accent. This is same-language lexical matching, not translation or accent removal. Exact name matches retain canonical invocation names and current access checks. For large MCP catalogs, `tool_search` can use bounded schema disclosure. Set `bounded: true`; the optional `max_active_tools`, `max_active_bytes`, and `max_result_bytes` settings adjust the built-in limits for active native schemas and search responses. Legacy behavior remains the default unless bounded mode is enabled. See [Large MCP catalogs and tool surfaces](https://everruns.com/docs/features/large-mcp-catalogs/) for the complete configuration and runtime behavior. ### Tools * **`tool_search`**: search the available tools by keyword and load their full parameter schemas. It is never deferred itself. ### How it works The diagram below traces one deferred tool through a full round-trip, from schema stripping at context-assembly time, through the `tool_search` call, to calling the real tool with its restored parameters.  1. **Threshold check**: deferral only activates when the total tool count meets or exceeds the threshold (default: 15). Below it, full schemas are sent unchanged. 2. **Schema stripping**: a tool-definition hook replaces the parameter schema of every deferrable tool with a minimal open-object stub (name + description survive). The shared prompt carries the search instruction once instead of repeating it in every stub. This runs when the runtime agent is built, so the model never receives the full schemas upfront. 3. **`tool_search` tool**: a real tool is added to the agent. When the model calls it with a query, the tool inspects its sibling tools and returns the full JSON parameter schemas of the matches. 4. **Progressive disclosure**: `tool_search` also records the matched tools as *revealed*. The hook re-runs on every reasoning iteration, so on the next step the revealed tools are advertised with their full, authoritative schema on the *registered* definition. This is what lets a structured tool caller actually pass arguments to a previously deferred tool, rather than only reading its schema as text. 5. **System-prompt guidance**: a short note instructs the model to call `tool_search` before using a tool whose parameters it has not yet loaded. 6. **Transparent execution**: the underlying tools stay registered and executable. Tool calls and results work identically; only how schemas reach the model changes. ### Never-defer allowlist `DeferrablePolicy::Never` is set by the tool’s *owner*. An embedder that composes tools it does not own (for example file/shell tools from another crate) can instead keep specific tools fully loaded by name: * Programmatically: `ToolSearchCapability::with_never_defer(["read_file", "bash", ...])`. * By configuration: a `never_defer` array (merged with any programmatic list). Allowlisted tools behave exactly like `DeferrablePolicy::Never` tools, their full schema is always sent, so the agent is never forced through a `tool_search` round-trip before its first read/edit/shell call. ### Legacy search ranking and result bounding The behavior in this section describes the default, legacy generic search. Bounded mode uses the server-aware index and active/result byte limits described in [Large MCP catalogs](https://everruns.com/docs/features/large-mcp-catalogs/). In bounded mode, a source-only query returns a server refinement rather than arbitrary operation schemas. Because there is no hosted semantic index, `tool_search` ranks matches client-side with a deliberately simple, predictable scheme: * **Field-weighted keyword overlap**: each whitespace-separated query term scores **3** if it appears in a tool’s *name* and **1** if it only appears in the *description*. A name hit is a far stronger signal of intent than an incidental word in prose, so it dominates. * **Exact-name bonus**: a query that is exactly a tool name gets a large bonus (**+100**), so “load this specific tool” always ranks that tool first. The deferred stub tells the model to query the exact tool name, so this is the common path. Wrapping punctuation is stripped first, so a quoted or backticked name (`"read_file"`, `` `read_file` ``) still matches. * **Top-band cutoff**: only results scoring at least **half the top score** are returned, trimming weak tail matches so a loose query does not drag in loosely related tools. * **Result cap**: at most **8** tools are returned per call. Every returned tool is also *revealed* (its full schema is un-deferred for the rest of the session), so the cap bounds both the response payload and how much of the catalogue a single search can permanently un-defer. * **Visible-tool scoping**: the search only considers tools visible in the current turn (the turn-scoped allowlist), so it never reveals a tool the agent could not otherwise call. * **No-match fallback**: if nothing matches, the tool returns the catalogue of available tool *names* (not schemas) so the model can refine its query instead of dead-ending. An empty query lists tools so the model can browse. The session reveal set that drives progressive disclosure is itself bounded: it is keyed per session and evicts the oldest sessions past a fixed cap, so reveals never leak across sessions or grow without limit (an evicted session simply re-runs `tool_search`). ### Configuration
```json
{
"capabilities": ["tool_search"]
}
```
The activation threshold defaults to 15 tools (`DEFAULT_TOOL_SEARCH_THRESHOLD`). Both the threshold and a never-defer allowlist can be set via capability config:
```json
{
"capabilities": [
{
"ref": "tool_search",
"config": {
"threshold": 20,
"never_defer": ["read_file", "write_file", "edit_file", "list_directory", "grep_files", "bash"]
}
}
]
}
```
`reveal` (experimental) chooses how a found tool becomes callable. With `redefine` (the default), its full schema replaces the placeholder in the tool list from the next step. With `in_result`, the tool list never changes: the model calls the tool using the schema the search returned, and every call is still checked against the tool’s real schema before it runs. On models that cannot carry tool changes inside the conversation, `in_result` keeps the prompt cache through a search. Some models call badly against a placeholder schema: in our tests Muse Spark sent numbers and objects as strings and never recovered, while GPT-6 Luna and Mistral Large 4 called as well as with `redefine`. Use it only with a model you have checked. ### Benchmarks Deferral only touches how tool *parameter schemas* reach the model, names and descriptions still go out in full, so the savings scale with how many tools an agent carries and how rich their schemas are. Measured on a representative 19-tool generic-agent surface (file, shell, web-fetch, session, storage, todo, time, scheduling, and subagent tools, plus `tool_search` itself), comparing the serialized tool list the driver sends to the model **with and without** deferral on the first turn: | Metric | Full schemas | Deferred (first turn) | Saving | | --------------------------- | ------------------------- | ----------------------- | --------------- | | Tool list sent to model | \~9.1 KB (\~2,270 tokens) | \~3.0 KB (\~740 tokens) | **67% smaller** | | Parameter-schema bytes only | \~7.2 KB | \~1.0 KB | **86% smaller** | Token figures use the \~4-chars-per-token rule of thumb for JSON. 18 of the 19 tools were deferred (`tool_search` keeps its schema). Net savings grow with tool count: an agent with dozens of MCP tools defers proportionally more. Reproduce this benchmark with:
```bash
cargo test -p everruns-core --features builtins --lib benchmark_prompt_size_reduction -- --nocapture
```
The trade-off is one extra `tool_search` round-trip per deferred tool before its first use; for many-tool agents the upfront token savings dominate. ### Limitations * **Server-executed tools**: the search reads schemas from the worker-side tool registry. This includes built-in tools and MCP server tools (MCP tools are registered as first-class registry tools). Client-side tools that are not registered worker-side are not returned by `tool_search` (their stripped definition is still sent so the model knows they exist). * **Extra round-trip**: loading a schema costs one `tool_search` call before the first use of a deferred tool. The token savings outweigh this for agents with many tools. ## See also * [OpenAI Tool Search documentation](https://platform.openai.com/docs/guides/tool-search) * [Anthropic tool search tool documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) * [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Auto-Continue After Usage Limit
> When an LLM subscription/plan usage limit is reached, automatically resume the interrupted work shortly after the limit resets.
Source:
| | | | ---------------- | --------------------------- | | **ID** | `usage_limit_auto_continue` | | **Category** | Core | | **Features** | None | | **Dependencies** | None | | **Risk** | Low | Some providers cap usage per subscription window rather than per minute. When a plan usage limit is hit, for example the ChatGPT/Codex `429` `usage_limit_reached` response, the turn fails and the session goes idle until the limit resets, often hours later. This capability makes the session resume on its own once the window clears, so long-running work is not silently stranded. It contributes **no tools**. The behavior is encapsulated behind a reusable platform boundary, the capability supplies an *LLM error hook* (an in-process capability hook, the same family as tool-call hooks and message filters) that the agent runtime invokes generically when a turn fails with a terminal error. The runtime has no special-casing for usage limits; any capability can provide the same kind of error-recovery hook. ## How It Works 1. **Decision**: The provider error is classified as `provider_usage_limit_reached`, which captures the absolute reset time (`resets_at`, unix seconds) reported by the provider. This is driver-agnostic: any driver whose error body carries the `usage_limit_reached` wording is covered. 2. **Scheduling**: When the capability is enabled and a reset time is present, a one-shot session schedule is created to fire `delay_seconds` after the reset. When it fires, the configured `prompt` is injected as a user message and the interrupted work resumes. 3. **Message copy**: The user-facing error reads *“You’re out of LLM usage limits. Your usage limit resets at \.”* When (and only when) a continuation was actually scheduled, it appends *“We’ll continue work automatically once it resets.”*, so the copy never promises a resumption that will not happen. Without the capability, the same error stays generic and no continuation is scheduled. ## Configuration ### Default
```json
{
"capabilities": ["usage_limit_auto_continue"]
}
```
Defaults: continuation fires **120 seconds** after the reported reset with the prompt **“Continue tasks”**. ### Custom delay and prompt
```json
{
"capabilities": [
{
"ref": "usage_limit_auto_continue",
"config": {
"delay_seconds": 300,
"prompt": "Resume the migration where you left off."
}
}
]
}
```
| Field | Type | Default | Description | | --------------- | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- | | `delay_seconds` | integer (0–86400) | `120` | How long to wait after the reset before resuming. A small buffer avoids racing the provider’s reset clock. | | `prompt` | string | `"Continue tasks"` | Message injected to resume work when the limit resets. | ## When To Enable Use this capability for agents running long, autonomous, or scheduled work on provider plans that enforce usage-window limits, where a multi-hour stall would otherwise require a human to manually restart the session. ## Limitations * Requires a provider whose error reports a concrete reset time; without one the error copy stays generic and no continuation is scheduled. * The continuation is delivered through the session schedule machinery, so it requires both a session schedule store and a schedule poller in the deployment. The hosted platform provides both. The default embedded runtime provides neither, so this capability is **not** part of the runtime-safe preset, an embedder must wire a `SessionScheduleStore` (e.g. via a schedule-store factory) and run a poller for it to take effect; otherwise its error hook is a no-op and the error copy stays generic. ## See Also * [Schedules](https://everruns.com/docs/capabilities/session-schedules/), the scheduling machinery the continuation reuses * [Capabilities](https://everruns.com/docs/features/capabilities/), the capability model
---
# User Hooks
> Run user-authored shell commands at lifecycle and tool events. Block, mutate, or audit agent actions from outside the model.
Source:
| | | | ---------------- | ------------ | | **ID** | `user_hooks` | | **Category** | Automation | | **Features** | None | | **Dependencies** | None | | **Risk** | High | User Hooks let you inject shell commands at six well-defined points in the agent execution lifecycle. The runtime hands each hook a structured JSON payload through environment variables (`$EVERRUNS_HOOK_PAYLOAD_JSON` plus a copy at `$EVERRUNS_HOOK_PAYLOAD_PATH` on the session VFS) and reads a structured decision back from stdout. (Delivery is via env vars rather than process stdin because the `bashkit_shell` interpreter runs the script in-process and exposes no process stdin.) Hooks can run silently (logging only), mutate the inputs they observe, or block the action outright. This is the same pattern you’ll recognize from Claude Code hooks, Git hooks, and pre/post-tool middleware in agent SDKs, applied as a first-class capability so any agent can adopt it, any hook bundle can be shared across an organization, and every invocation lands in the audit log. ## When to enable * **Security gates**: block any `bash` call matching `rm -rf /` before the sandbox sees it. * **Format-on-write**: run `cargo fmt` or `prettier` after every `edit_file`. * **Audit / observability**: POST every tool call to your SIEM. * **Project bootstrapping**: at `session_start`, clone a repo, install deps, or seed a workspace. * **CI-style validation**: at `turn_end`, run tests and surface failures back to the model on the next turn. ## Risk High. The capability accepts arbitrary shell commands from config. Even though the commands run inside the session’s `bashkit_shell` sandbox (no host filesystem, no host network beyond the session’s egress policy), the assignment gate is admin-only, anyone who can configure this capability can run arbitrary code in the session sandbox on every agent action. ## Events Six events. Two (`pre_tool_use`, `user_prompt_submit`) can block; the rest are advisory-only. **`pre_tool_use` and `post_tool_use` fire today**; the other four events ship their schema/validation here but their runtime wire-in lands in follow-up changes (see “What’s not yet wired” below). | Event | Fires at | Can block? | Mutation surface | | -------------------- | ------------------------------------ | ---------- | -------------------- | | `session_start` | New session created | no | none | | `user_prompt_submit` | User message accepted, before reason | yes | user message text | | `pre_tool_use` | Each tool call, before execution | yes | `ToolCall.arguments` | | `post_tool_use` | Each tool call, after execution | no | `ToolResult` | | `turn_end` | Turn finishes | no | none | | `session_end` | Session close/archive | no | none | See [Bash hook contract](#bash-hook-contract) for block and mutation responses. ## Configuration The capability accepts two top-level fields:
```json
{
"capabilities": [
{
"ref": "user_hooks",
"config": {
"hooks": [ /* UserHookSpec entries */ ],
"disabled_contributions": [ /* HookId strings to mute */ ]
}
}
]
}
```
### `UserHookSpec`
```jsonc
{
"id": "fmt_after_edit", // optional; defaults to "{event}_{idx}"
"event": "post_tool_use",
"matcher": { "tool_name": "edit_file" }, // tool events only
"executor": {
"type": "bash",
"command": "scripts/fmt.sh",
"env": { "FMT_PROFILE": "ci" }
},
"timeout_ms": 5000, // 100..30_000
"on_error": "warn", // "block" | "allow" | "warn"
"description": "Run formatter after edit_file"
}
```
#### Matcher The `matcher` block applies only to `pre_tool_use` and `post_tool_use`. Setting it on lifecycle events is rejected at validation time. | Field | Meaning | | ---------------- | ------------------------------------------------------ | | `tool_name` | Exact tool name match | | `tool_name_glob` | Restricted glob: `a\|b\|c` alternation or trailing `*` | | `args_jsonpath` | Dot-path into `ToolCall.arguments` (e.g. `$.command`) | | `match_regex` | Fires when extracted value matches this regex | | `deny_regex` | Inverse, fires when extracted value matches this regex | `match_regex` and `deny_regex` are mutually exclusive. Regex flavor is the Rust `regex` crate (no look-around, no backreferences). #### `on_error` What to do when the executor itself fails (timeout, non-JSON output, sandbox error): * `block`, treat as `{"decision": "block", "reason": "hook failed"}`. Use for security-critical hooks. * `allow`, log + continue. * `warn`, log + emit `hook.warning` event + continue. **Default.** ## Bash hook contract The bash executor is modeled after Claude Code hooks with one departure: the payload is delivered via env vars (and a session-VFS file) rather than stdin, because the bashkit interpreter doesn’t expose process-level stdin to user scripts. ### Input, env vars + VFS file Every hook invocation sets these env vars: | Var | Meaning | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `EVERRUNS_HOOK_PAYLOAD_JSON` | Full payload, JSON-encoded as one string. Read with `jq -n 'env.EVERRUNS_HOOK_PAYLOAD_JSON \| fromjson'`. | | `EVERRUNS_HOOK_PAYLOAD_PATH` | Path on the session VFS to a file containing the same JSON. Cleaned up after the hook returns. Use for `cat "$EVERRUNS_HOOK_PAYLOAD_PATH" \| jq` workflows. | | `EVERRUNS_HOOK_EVENT` | One of `session_start`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `turn_end`, `session_end`. | | `EVERRUNS_HOOK_ID` | Stable hook id (`{capability_id}:{name}` or `user:{name}`). | | `EVERRUNS_HOOK_SESSION_ID` | Current session id. | | `EVERRUNS_HOOK_TURN_ID` | Set when a turn is in flight. | | `EVERRUNS_HOOK_TOOL_NAME` | Set for `pre_tool_use` / `post_tool_use`. | | `EVERRUNS_HOOK_TOOL_CALL_ID` | Set for `pre_tool_use` / `post_tool_use`. | Payload envelope:
```json
{
"event": "pre_tool_use",
"hook_id": "user:guard_rm",
"session_id": "ses_…",
"turn_id": "trn_…",
"org_id": "org_…",
"agent_id": "agt_…",
"ts": "2026-05-28T12:34:56.789Z",
"data": {
"tool_name": "bash",
"tool_call_id": "call_…",
"arguments": { "command": "ls -la" }
}
}
```
### Output, stdout Three accepted shapes, tried in this order: 1. **Empty stdout**: exit 0 = allow; non-zero = block (stderr surfaced as the block reason). This is the Git-hook escape hatch. 2. **JSON decision**: stdout starts with `{`:
```json
{
"decision": "allow" | "mutate" | "block",
"reason": "string shown in audit/UI",
"user_message": "string surfaced to the user when blocking",
"patch": { /* event-specific mutation */ }
}
```
3. **Anything else** → executor error → `on_error` policy applies. ### Limits * **Timeout**: configurable per hook; default 5 s, max 30 s. * **Output size**: 64 KiB total (stdout + stderr). * **Sandbox**: runs through `bashkit_shell` against the session VFS. No host shell. Inherits the session’s egress policy. * **stderr**: captured into the audit log; never shown to the model unless `decision == "block"` with no `reason`. ## Composition Hooks chain in capability-declaration order, then array order within each capability. The first `block` decision wins; mutations from earlier hooks survive even if a later hook blocks. Tool approval and `tool_use` guardrails always run after your `pre_tool_use` hooks, whatever order the capabilities are declared in. They judge the arguments your hooks produced, so a `mutate` decision cannot turn an approved call into one nobody approved, and an approval request shows the rewritten arguments. A hook that blocks a call means no one is asked to approve it. When a `mutate` decision changes the arguments of a call that then runs, the `tool.completed` event records the arguments that ran in `executed_arguments`, next to the original call on `tool.started`. Capabilities other than `user_hooks` can ship hook bundles, see [Hook bundles from other capabilities](#hook-bundles-from-other-capabilities). To mute a bundled hook, list its `HookId` under `disabled_contributions`:
```json
{
"capabilities": [
{ "ref": "rust_quality_pack" },
{ "ref": "user_hooks", "config": {
"disabled_contributions": ["rust_quality_pack:fmt_after_edit"]
} }
]
}
```
`HookId` format: * Capability contribution: `{capability_id}:{name}` * User config: `user:{name}` ## Hook bundles from other capabilities Any built-in capability can contribute hook specs to your agent by overriding `Capability::user_hooks_with_config` and returning a list of `UserHookSpec`s. The `guarded-bash-demo` seed agent is a live example: its `user_hooks` capability config ships a `pre_tool_use` hook that refuses destructive `rm -rf` invocations before the bash tool ever runs, with no extra setup. Capability-contributed hooks ride the trust gate of enabling the contributing capability, so admin assignment rules still apply. Operators can mute any individual contribution via `disabled_contributions` on a sibling `user_hooks` capability config. > Declarative-capability hook bundles (one POST to register, many agents to reuse) are on the roadmap and are not yet wired into the declarative capability schema. See the [hook bundle examples](https://github.com/everruns/everruns/tree/main/examples/hook-bundles) for ready-to-paste user-config bundle JSON. ## Examples ### Block `rm -rf` from the bash tool
```json
{
"capabilities": [
{
"ref": "bashkit_shell"
},
{
"ref": "user_hooks",
"config": {
"hooks": [
{
"id": "guard_rm",
"event": "pre_tool_use",
"matcher": {
"tool_name": "bash",
"args_jsonpath": "$.commands",
"deny_regex": "(?:^|;|&&|\\|)\\s*rm\\s+-rf\\b"
},
"executor": {
"type": "bash",
"command": "echo '{\"decision\":\"block\",\"reason\":\"rm -rf is not allowed\",\"user_message\":\"That command is blocked by policy.\"}'"
},
"on_error": "block",
"description": "Reject destructive rm invocations"
}
]
}
}
]
}
```
### Format Rust files after every edit
```json
{
"capabilities": [
{ "ref": "session_file_system" },
{ "ref": "bashkit_shell" },
{
"ref": "user_hooks",
"config": {
"hooks": [
{
"id": "fmt_rs",
"event": "post_tool_use",
"matcher": {
"tool_name": "edit_file",
"args_jsonpath": "$.path",
"match_regex": "\\.rs$"
},
"executor": {
"type": "bash",
"command": "cargo fmt --check 2>&1 || cargo fmt"
},
"on_error": "warn"
}
]
}
}
]
}
```
### Seed a workspace on session start
```json
{
"capabilities": [
{ "ref": "session_file_system" },
{ "ref": "bashkit_shell" },
{
"ref": "user_hooks",
"config": {
"hooks": [
{
"id": "init",
"event": "session_start",
"executor": {
"type": "bash",
"command": "echo 'session bootstrapped' > /workspace/.bootstrap && echo '{}'"
},
"on_error": "warn",
"description": "Drop a sentinel file the agent can read"
}
]
}
}
]
}
```
### Block a user prompt that pastes a secret `user_prompt_submit` is the only lifecycle event that can **block**: a `block` decision aborts the turn before the LLM runs. The original prompt text arrives in `data.message`. Here the hook reads it, and if it looks like a pasted private key, rejects the turn with a message shown to the user. `on_error: "block"` makes the hook fail closed.
```json
{
"capabilities": [
{ "ref": "bashkit_shell" },
{
"ref": "user_hooks",
"config": {
"hooks": [
{
"id": "block_secrets_in_prompt",
"event": "user_prompt_submit",
"executor": {
"type": "bash",
"command": "msg=$(echo \"$EVERRUNS_HOOK_PAYLOAD_JSON\" | jq -r '.data.message'); if printf '%s' \"$msg\" | grep -qiE 'BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY'; then echo '{\"decision\":\"block\",\"reason\":\"prompt contains a private key\",\"user_message\":\"Your message looks like it contains a private key and was blocked. Remove the secret and resend.\"}'; else echo '{}'; fi"
},
"timeout_ms": 5000,
"on_error": "block",
"description": "Reject prompts that paste a private key"
}
]
}
}
]
}
```
`user_prompt_submit` can also **mutate** the prompt instead of blocking, emit `{"decision":"mutate","patch":{"message":""}}` and the turn proceeds with the rewritten text. For example, to prepend a house style reminder:
```jsonc
{
"id": "prepend_style_note",
"event": "user_prompt_submit",
"executor": {
"type": "bash",
"command": "echo \"$EVERRUNS_HOOK_PAYLOAD_JSON\" | jq -c '{decision:\"mutate\",patch:{message:(\"[reminder: follow the house style guide]\\n\" + .data.message)}}'"
},
"on_error": "warn"
}
```
### Log every completed turn `turn_end` is advisory, its decision is ignored, so use it for side effects like metrics or audit trails. The payload’s `data.success` reports whether the turn finished cleanly.
```json
{
"capabilities": [
{ "ref": "session_file_system" },
{ "ref": "bashkit_shell" },
{
"ref": "user_hooks",
"config": {
"hooks": [
{
"id": "log_turn_end",
"event": "turn_end",
"executor": {
"type": "bash",
"command": "echo \"$EVERRUNS_HOOK_PAYLOAD_JSON\" | jq -r '.ts + \" turn \" + .turn_id + \" success=\" + (.data.success | tostring)' >> /workspace/.turn-log; echo '{}'"
},
"timeout_ms": 3000,
"on_error": "warn",
"description": "Append one line per completed turn to /workspace/.turn-log"
}
]
}
}
]
}
```
## Observability Today, hook decisions and errors are recorded in the server logs via `tracing`: blocks, ignored post-hook blocks, mutations, `on_error` outcomes, and `disabled_contributions` mutings are logged with the resolved `hook_id` and the `tool_call_id`. **Planned (deferred):** structured `hook.invoked` / `hook.completed` / `hook.blocked` / `hook.warning` events emitted through the same observability pipeline as tool events (Braintrust, OTel). These are not emitted yet, see the spec’s observability section. ## Event firing All six events fire: * **`pre_tool_use`**: before each tool call; can block or mutate the call. * **`post_tool_use`**: after each tool call; can mutate the result. * **`session_start`**: after a session is created (mounts + initial files in place); advisory. * **`session_end`**: when a session is deleted, before VFS eviction; advisory. * **`user_prompt_submit`**: on the first reason iteration, before the LLM is consulted; can block (aborts the turn with a user-facing message) or mutate the user message text. * **`turn_end`**: when a turn reaches a terminal outcome; advisory. Note on `user_prompt_submit` blocking: the API persists the user message and runs the turn asynchronously, so a block does not reject the HTTP request, it aborts the turn. The session shows a `turn.failed` outcome carrying the hook’s `user_message`. ## See also * [Capabilities](https://everruns.com/docs/capabilities/), compose tools and runtime behavior * [Guardrails](https://everruns.com/docs/capabilities/guardrails/), runtime safeguards * [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), the sandbox that runs hook commands
---
# User MCP Servers
> Give an agent the MCP servers of the person chatting with it, signed in as that person, and optionally let it add and connect them in chat.
Source:
| | | | ---------------- | ------------ | | **ID** | `user_mcp` | | **Category** | Integrations | | **Features** | None | | **Dependencies** | None | | **Risk** | Medium | Adds the [user MCP servers](https://everruns.com/docs/features/user-mcp-servers/) of the person who sent the current message to the agent’s MCP servers for that turn. Each server signs in as that person. With `use` alone the capability adds no tools of its own; the tools come from the person’s servers. With `manage` on, the agent can also change the person’s list in chat. ## When to enable * A personal assistant such as Platform Chat, where each person brings their own Linear, Notion or internal servers. * Any agent people talk to directly and should be able to extend for themselves without editing the agent. Leave it off for agents that run unattended or in shared channels: they get nothing from it. ## Configuration | Setting | Default | Effect | | ------------------- | ------- | ----------------------------------------------------------------------------------------------- | | `use` | `true` | Add the person’s enabled servers to each turn. | | `manage` | `false` | Give the agent the tools below to change the person’s list. | | `allow_custom_urls` | `false` | With `manage`, let the agent add a server by URL, not only from the organization’s MCP catalog. |
```json
{ "ref": "user_mcp", "config": { "use": true, "manage": true } }
```
## Tools Added only when `manage` is on. They act on the list of the person who sent the message, the same list as **Settings > My MCP servers**, and never on the organization catalog. Read-only discovery can list approved organization presets before the agent chooses one to add. | Tool | What it does | Shared approval | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `list_user_mcp_servers` | Lists the person’s servers and those added to this conversation only: enabled, signed in, and whether this agent skips one because its own server has the same name | No | | `list_mcp_catalog` | Lists approved organization presets with their exact catalog names, sanitized endpoint URLs, descriptions and authentication modes. Follow `next_cursor` until null, including after an empty page | No | | `add_user_mcp_server` | Adds a catalog server (`{"catalog": "linear"}`), or a server by URL when `allow_custom_urls` is on. With `"scope": "chat"` it is added to this conversation only | In normal/protective mode | | `remove_user_mcp_server` | Removes a server, from this conversation or from the list | In protective mode | | `enable_user_mcp_server` | Turns a server on | In normal/protective mode | | `disable_user_mcp_server` | Turns a server off without removing it | In protective mode | | `connect_mcp_server` | Shows the person a Connect card for a server that needs a sign-in | No | Before adding a catalog server, use `list_mcp_catalog` and pass a returned name as `catalog` to `add_user_mcp_server`. Catalog names are chosen by the organization; they need not match the provider’s name. Discovery returns bounded pages of active presets with short descriptions, never credentials or headers, and does not contact servers or begin OAuth. It has the same verified-person and single-participant restrictions as management. `add_user_mcp_server` and `enable_user_mcp_server` declare that they require approval through the agent’s shared [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) policy. With `tool_approval` enabled in `normal` or `protective` mode, they wait for approval in chat. With the capability absent or its mode set to `off`, they run without a hard approval gate. `user_mcp` adds no separate gate or approval setting. Other management tools follow the same mode and their tool hints; `remove` and `disable` only take tools away. OAuth sign-in remains a separate authorization step, regardless of the tool approval mode. A server added or enabled in a turn is usable from the person’s next message. ### This conversation only `add_user_mcp_server` with `"scope": "chat"` adds the server to the current conversation instead of the person’s list. It joins every later turn of this conversation, loads on demand like the person’s other servers, and never appears in **Settings > My MCP servers** or in their other conversations. `remove_user_mcp_server` takes it away from the next message. The same rules apply as for the list: the shared approval policy, catalog servers only unless `allow_custom_urls` is on, and no keys or headers. A catalog server signs in as the person, as it would from their list. A custom server that signs in with OAuth cannot be added this way, because its sign-in needs the list entry; add it to the list instead. A name that one of the agent’s own servers, or a resource attached through [Resource Discovery](https://everruns.com/docs/integrations/ard/), already uses in this conversation is refused. In Chat, an **MCP** button in the conversation header lists these servers, with their host and whether you have signed in, and removes one with a click. The same list is `GET /v1/sessions/{session_id}/mcp-servers`, and `DELETE /v1/sessions/{session_id}/mcp-servers/{name}` removes one. `connect_mcp_server` never sees a credential: the person signs in in their own browser, as with any Connect card. `connect_mcp_server` is also added on its own, without `manage` and without the capability being configured, when one of the agent’s own MCP servers acts as `user` or `user_or_service`, so the agent can offer the sign-in before a call fails. For a server that acts as the agent (`service`), the card leads to the agent’s **MCP servers** sheet, where only someone allowed to manage MCP servers can authorize it; anyone else is told to ask an admin. An agent server set to `connectInChat: never` gets no card: the tool returns the same settings link for the agent to pass on (see [Connecting from chat](https://everruns.com/docs/features/mcp/#connecting-from-chat)). Servers added in chat cannot carry API keys or headers; the person adds those in Settings. ## Behaviour * Only the person who sent the message counts, never the session owner or the agent’s own account. Unattended runs get no servers. * Sessions with more than one person get no servers. * An agent or capability server with the same name wins; the person’s server is skipped. `list_user_mcp_servers` and the agent’s **MCP servers** sheet report it. * The manage tools refuse to run without a person (unattended runs) and in sessions with more than one person, with a message saying so. * A server that fails validation is skipped on its own; the rest still load. * The person’s servers load on demand by default: the agent sees one line per server (`mcp_`) and loads a server’s tools through `tool_search`, or by calling that line, when it needs them. They are callable from its next step and stay loaded for the rest of the conversation (see [Loading tools on demand](https://everruns.com/docs/features/mcp/#loading-tools-on-demand)). Turning off **Load tools on demand** on a server in **Settings > My MCP servers** (`deferred: false` when adding or updating it under `/v1/virtual-users/{id}/mcp-servers`) lists its tools at the start of every turn instead. Servers added for one conversation only always load on demand. ## Risk Medium. The agent can call any tool on servers the person chose, with the person’s login. Tool approval and the agent’s other guardrails apply to these tools as to any MCP tool. With `manage`, adding a server is how a prompt injection would try to send the person’s data somewhere new. Enable Tool Approval in `normal` or `protective` mode to hold add and enable calls for the person’s approval. Leaving approval absent or off allows these calls to run autonomously. Custom URLs remain off by default, and every URL goes through the same address checks as the API.
---
# Web Fetch
> Fetch a URL and convert its HTML to markdown or plain text, with SSRF protection and structured fetchers for common developer and research sources.
Source:
| | | | ---------------- | ----------- | | **ID** | `web_fetch` | | **Category** | Network | | **Features** | None | | **Dependencies** | None | Fetch content from URLs and convert HTML to markdown or plain text. Powered by [FetchKit](https://github.com/everruns/fetchkit) with built-in SSRF protection, low-noise extraction, bounded crawl discovery, and structured fetchers for common developer and research sources. ## Tools ### `web_fetch` Fetch a URL and return its content. | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | ----------------------------------------------------------------------- | | `url` | string | yes | URL to fetch | | `method` | string | no | `GET` (default), `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, or `OPTIONS` | | `headers` | object | no | Request headers, such as `Authorization` | | `body` | string | no | Raw request body | | `json` | any | no | JSON request body; sets `Content-Type: application/json` | | `form` | object | no | Form fields, sent as `application/x-www-form-urlencoded` | | `as_markdown` | boolean | no | Convert HTML to markdown | | `as_text` | boolean | no | Convert HTML to plain text | | `content_focus` | string | no | Extraction mode: `full`, `main`, `readable`, or `agent` | | `crawl` | boolean | no | Discover and fetch a bounded set of same-origin pages | | `max_pages` | integer | no | Maximum crawl pages, including the seed (default: 5, maximum: 20) | | `if_none_match` | string | no | ETag for a conditional request | | `if_modified_since` | string | no | Last-Modified value for a conditional request | | `save_to_file` | string | no | Workspace destination when file download is enabled for the capability | Returns: content body, status code, metadata, quality signals, redirect history, and crawl summaries when requested. ### API requests A method other than `GET` or `HEAD`, or any of `headers`, `body`, `json`, or `form`, sends one plain HTTP request instead of a page fetch. The result is the status code, response headers, and the response text as received, without markdown conversion. Redirects are returned rather than followed. This lets an agent follow a service’s own instructions for agents, such as an `auth.md` agent registration followed by a token request:
```json
{"url": "https://example.com/oauth/token", "method": "POST",
"form": {"grant_type": "client_credentials", "client_id": "..."}}
```
API requests need the host’s egress service, so they pass the same network access and system egress policy checks as fetches. On deployments that restrict egress (such as the Everruns demo instance), plain reads can reach any public site, while requests that send data (a method other than GET or HEAD, or a body) only reach the platform’s list of approved services. Request and response bodies are limited to 256 KB, and the request times out after 30 seconds. If your organization needs to send data to its own services on such a deployment, a platform administrator can allow it to extend the list. Org admins then add their hosts under **Settings > Organization > Outbound allowlist**, one per line (`api.example.com`, `*.example.com`, or an `https://example.com/path/` prefix, up to 50, public hostnames only). The extra hosts apply to your organization’s traffic only, changes take effect within a minute, and the platform’s blocked hosts stay blocked. ## Notes * **Timeouts**: 1s for first byte, 30s for body. Partial content returned on body timeout. * **Binary content**: Images, PDFs, etc. return metadata only (content type, size), not the binary data. * **Focused extraction**: Use `content_focus: "agent"` for FetchKit’s lowest-noise extraction strategy. * **No JavaScript rendering**: Web Fetch returns the server’s response as delivered. Pages that build their content client-side need a browser capability such as [Browserless](https://everruns.com/docs/capabilities/browserless/). * **Crawl scope**: Crawl discovery stays on the seed URL’s origin and enforces FetchKit’s page limit. * **SSRF protection**: Private IPs (loopback, RFC1918, link-local, CGNAT) are blocked by default with DNS pinning to prevent rebinding attacks. * **Excessive newlines**: Automatically filtered from converted content. ## See Also * [File System](https://everruns.com/docs/capabilities/file-system/), save fetched content to workspace * [Capabilities Overview](https://everruns.com/docs/capabilities/) ## Write-only credentials Use `$NAME` in the exact header or form field authorized by a credential binding. `credential_usage` explicitly selects `service` (default) or the verified `user`. It never falls back to another identity. For example:
```json
{
"url": "https://mail.example/api/messages",
"method": "POST",
"credential_usage": "user",
"headers": { "Authorization": "Bearer $MAIL_TOKEN" },
"json": { "to": "recipient@example.com", "subject": "Hello" }
}
```
To capture an authentication response without showing its token to the model, declare every expected secret field:
```json
{
"url": "https://mail.example/oauth/token",
"method": "POST",
"credential_usage": "user",
"form": { "grant_type": "refresh_token", "refresh_token": "$MAIL_REFRESH" },
"capture_secrets": [
{
"name": "MAIL_TOKEN",
"from": "/access_token",
"scope": "virtual_user",
"binding": {
"url": "https://mail.example/api",
"auth": { "type": "bearer" }
},
"expires_in_from": "/expires_in"
}
]
}
```
The user approves persistent storage, replacement, and cross-origin bindings before any request is sent. The result contains `$MAIL_TOKEN` instead of the value. Up to eight captures save together; malformed JSON, duplicate keys, missing fields, interrupted/oversized responses, or storage failures withhold the response and save no partial values. Credential requests have a 256 KiB response limit and cannot crawl, render, extract, or save files. Bindings support bearer headers, named headers, and named form fields (`{"type":"form_field","name":"refresh_token"}`). References in URLs, arbitrary bodies, JSON values, or mixed strings are rejected. Redirects are returned without following them. Known literal, JSON-escaped, and form-encoded token echoes are redacted before the result enters chat or events. Declare all claim tokens, assertions, access tokens, and refresh tokens the service returns; arbitrary encodings such as base64 are outside this redaction guarantee. The same binding is what Bashkit HTTP uses. A command inside a Daytona, E2B, or Modal sandbox runs without it: those machines do not receive `$NAME`, and their outbound HTTPS is not rewritten with the secret. Modal can still inject a GitHub connection token outside the VM; that path is separate from this binding. Manage personal credentials in **Settings > Connections**, service credentials on their virtual user, agent credentials on the agent’s **Credentials** tab, organization credentials in **Settings > Organization**, and session credentials from the session’s **Credentials** action. Values are write-only. Expired or revoked bindings fail with renewal/reconnect guidance.
---
# Web Search
> One web_search tool answered by the search provider you choose, with free search as the fallback.
Source:
| | | | ---------------- | ------------ | | **ID** | `web_search` | | **Category** | Network | | **Features** | None | | **Dependencies** | None | Web Search gives an agent one `web_search` tool. Where a search goes is a setting on the capability, not a different tool: the agent keeps the same tool, prompts and history when you switch providers or models. The Worker harnesses include it, so a new worker agent can search with no key and no setup; a Conversation agent adds it on the agent. ## Providers | Setting | What answers | Cost | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Organization default** (`org_default`) | The organization’s default provider (see below); Automatic for a new organization | Depends on the provider | | **Automatic** (`auto`) | The organization’s Automatic order: the model’s own search, then the organization’s search accounts, then the deployment’s own search when it offers one, then free search | Depends on the provider that answers | | **Model provider search** (`native`) | The model’s own search, on OpenAI, Anthropic, Gemini and OpenRouter models that have it (see below). Other models use free search. | Billed by the model provider | | **Brave Search** (`brave`) | The Brave Search API with a user, session or application key, else the organization’s first Brave account | Billed on the Brave key | | **Parallel** (`parallel`) | The Parallel Search API (`fast` mode) with a user, session or application key, else the organization’s first Parallel account | Billed on the Parallel key, about $1 per 1,000 searches | | **A search account** (`account`, with `account_id`) | One organization search account, such as “Brave Search · Team”, “Parallel · Research” or a [Cloudflare Web Search](https://everruns.com/docs/integrations/cloudflare-web-search/) account on Ceramic, Exa or Linkup | Billed on that account’s key, or for Cloudflare on its AI Gateway credits ($0.25 per 1,000 searches on Ceramic) | | **Free search** (`free`) | DuckDuckGo, then DuckDuckGo Lite, then Mojeek, then Wikipedia | Free | Free search is the last fallback of every setting: when the chosen provider has no key, rejects it, is rate limited or is unavailable, free search answers and the run records why. Set `fallback` to `none` to use only the chosen provider. ## Model provider search When model provider search comes first in an agent’s plan, the model searches with its provider’s own search instead of calling `web_search`: the provider runs the searches inside the model call and the answer cites its sources. This is decided on every turn, for the model running that turn and the organization’s current defaults, so a session that switches models keeps searching: | Model provider | Native search | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | OpenAI, Azure OpenAI, ChatGPT Plan (framework hosts) | OpenAI web search, on models that have it (GPT-4o, GPT-4.1, GPT-5 and later, o3, o4-mini) | | OpenRouter | The model vendor’s own search, on models OpenRouter runs it for (OpenAI GPT-4.1 and GPT-5 and later, Claude, Gemini 3, Grok 4, Perplexity) | | Anthropic | Anthropic web search, on Claude 3.5 Haiku, Claude 3.7 Sonnet and Claude 4 and later, up to 5 searches per model call | | Gemini | Grounding with Google Search, on Gemini 2.0 Flash, 2.5 and 3 and later, when `web_search` is the agent’s only tool | | Others | None: the next provider in the plan answers | The agent’s domain filters and the organization’s blocked domains go with each request. A provider that cannot apply them leaves the `web_search` tool in place, and the next provider in the plan answers: OpenAI search cannot exclude sites, so an agent or organization with blocked domains searches with its next provider on OpenAI models. Anthropic takes allowed or blocked sites but not both at once, and Gemini takes neither. Gemini also cannot yet search natively next to the agent’s other tools, so an agent with more tools than `web_search` searches with its next provider on Gemini models. On OpenRouter, native search is only requested for models that have it, so OpenRouter’s own fallback search never answers in place of the plan. Each native search is billed by the model provider: about $10 per 1,000 searches on OpenAI and Anthropic, $14 per 1,000 search queries on Gemini 3 and $35 per 1,000 grounded answers on Gemini 2.x. The model call records it as a `hosted_tool` cost component (`web_search_call`, with the number of searches) and budgets count it. In chat, a native search shows as a **Searching the web for ”…”** row. If an OpenAI Responses search ends before completing, its activity is marked as failed. Any partial answer and citations remain available. Everruns does not retry the search automatically; provider usage still counts toward cost. The OpenAI and OpenRouter server tools capabilities keep their own `web_search` option. When one of them already turns on its provider’s search, that configuration is used. ## In the UI **Registers > Web search** has two tabs, like Models: * **Providers**: a card per way the organization can search. **Model provider search** lists which connected model providers offer it and its price; each search account shows whether its key is set and its place in Automatic; a deployment that pays for a search provider itself (Everruns search on the Everruns demo instance) shows it with its price; **Free search** is always there. Admins connect an account with **Connect search provider**, and test, rotate or disconnect it from its card. * **Defaults**: the default provider, the Automatic order (move entries up or down; free search stays last), **Allow model provider search** with its cost, what happens when a provider fails, results per search, and blocked domains. In the agent editor, expand **Web search** under Capabilities to pick the provider (Organization default, Automatic, Model provider search, a search account or Free search). **How this agent will search** says, for the agent’s default model, which provider answers first, what it costs and what comes next. Results per search, freshness, fallback and domain filters follow. In chat, each search is one **Searched ”…”** row with the result count, the provider that answered, the duration, and a note when an earlier provider failed. Expand it to see the top results, then open **Details and raw response** for every attempt and each provider’s verbatim response. In Session Trace, a `web_search` step lists its attempts, with a failed one in red. ## Organization search accounts and defaults An organization admin connects search accounts as organization connections (`POST /v1/orgs/{org}/organization-connections/providers/brave_search`, `.../parallel` or `.../cloudflare_web_search`), the same way sandbox provider accounts are connected. Every agent of the organization can then search with them; the key never reaches the agent. `PATCH /v1/orgs/{org}` with `web_search_defaults` sets the organization’s defaults: | Field | Default | Description | | -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | `auto` | What `org_default` agents use: `auto`, `native`, `brave`, `parallel`, `account` (with `account_id`) or `free` | | `automatic_order` | `["native", "free"]` | Order of Automatic: `native`, search account ids and `hosted` (the deployment’s own search, when it offers one). Free search is always last; entries left out keep their place (native first, other accounts after the listed ones, `hosted` just before free search) | | `allow_native` | `true` | Whether agents may use the model provider’s own search (billed by the model provider) | | `fallback` | `next` | Fallback for agents that do not set their own | | `results_per_search` | 8 | Results per search when neither the model nor the agent asks, 1 to 20 | | `blocked_domains` | none | Sites no search returns, on top of each agent’s `blocked_domains` | Changes reach running sessions from their next search, within 30 seconds. `GET /v1/search-providers` lists what the organization can search with, and `POST /v1/search-providers/preview` shows the plan an agent’s setting resolves to for a model. For `brave`, a key is read from the user’s Brave Search connection, then the `BRAVE_SEARCH_API_KEY` session secret, then (Framework only) the `BRAVE_SEARCH_API_KEY` environment variable, then the organization’s first Brave Search account. `parallel` reads keys the same way: the user’s Parallel connection, then the `PARALLEL_API_KEY` session secret, then (Framework only) the `PARALLEL_API_KEY` environment variable, then the organization’s first Parallel account. Parallel searches its own web index and returns longer excerpts than Brave, so results carry an `excerpt` the model can quote. It applies the agent’s allowed or blocked sites and freshness itself. A [Cloudflare Web Search](https://everruns.com/docs/integrations/cloudflare-web-search/) account searches the index it was connected with (Ceramic, Exa or Linkup) and returns at most 10 results. The API has no site or date filters, so allowed and blocked sites are applied to its results and freshness is not. Free search is best effort. Search engines sometimes answer automated traffic with a bot check; free search treats that as a failure and moves to the next source instead of reporting no results. Answers are cached for ten minutes, and requests to one search engine are spaced out. ## Settings | Field | Default | Description | | ----------------- | ------------------ | ---------------------------------------------------------------------- | | `provider` | `org_default` | One of the settings above | | `account_id` | none | The search account, with `provider: account` | | `fallback` | organization’s | `next` falls back to the next provider, then free search; `none` stops | | `limit` | organization’s (8) | Results per search, 1 to 20 | | `freshness` | none | `day`, `week`, `month` or `year` | | `allowed_domains` | none | Only results from these sites | | `blocked_domains` | none | Never results from these sites | | `show_provider` | `false` | Tell the model which provider answered and why |
```json
{"ref": "web_search", "config": {"provider": "brave", "blocked_domains": ["pinterest.com"]}}
```
## One search per agent Provider-specific search capabilities stay available for agents built around one provider: Brave Search, DuckDuckGo, Parallel Search and Fetch, Parallel Paid Search, and the OpenAI and OpenRouter server tools with their `web_search` tool on. Each says whose search it is. An agent that has two of these, or one of them next to an MCP server’s `web_search` tool, gets a `capabilities.duplicate_web_search` warning from [Agent Checks](https://everruns.com/docs/features/agent-checks/). Two search tools make the model guess which one to use. The warning never blocks a save. ## Tools ### `web_search` | Parameter | Type | Required | Description | | ----------- | --------- | -------- | ------------------------------------------------------------------- | | `query` | string | yes | What to search for | | `limit` | integer | no | How many results, 1 to 20 | | `freshness` | string | no | `day`, `week`, `month` or `year` | | `domains` | string\[] | no | Only results from these sites; cannot widen the agent’s own filters | | `topic` | string | no | `dev` also searches GitHub, npm and crates.io (free search) | Returns the query and a list of results, each with an `id`, `title`, `url`, `site`, and when known `published`, `snippet` and `excerpt`. The model cites a claim with the result’s `url` or `id`; an `id` stays the same for the same URL throughout a session. Free search adds an `answer` when an encyclopedia abstract matches. To show those citations as numbered source chips in the chat, also add [Web Citations](https://everruns.com/docs/capabilities/citation-web/) (`citation_web`). It covers model provider search too, from the citations the provider returns. Which provider answered, every attempt with its reason, and each provider’s raw response are kept on the tool call for people (the run’s details and Session Trace). The model sees them only with `show_provider`. ## Framework Enable the `web-search` feature and add the capability:
```rust
use everruns::WebSearch;
let agent = Agent::builder()
// ...
.capability(WebSearch::auto())
.build()?;
```
`WebSearch::brave().no_fallback()`, `WebSearch::parallel()`, `WebSearch::free()`, `.limit(5)` and `.blocked_domains(["pinterest.com"])` set the other options. The builder writes only config; put a Brave key in `BRAVE_SEARCH_API_KEY` and a Parallel key in `PARALLEL_API_KEY`.