# Bento

## Authentication

The bento daemon uses bearer token authentication. Tokens are issued on the server where the daemon runs, then configured on each client machine where your coding agent (Claude Code, Codex, pi) connects from.

### Server side

On the machine running the daemon, issue a token:

```bash
bento token issue --email you@example.com
```

This outputs a `bento_pat_...` token. Save it — it's only shown once.

You can list and revoke tokens:

```bash
bento token list
bento token revoke <token-id>
```

### Client side

Each coding agent needs the token configured so it can authenticate with the daemon. The daemon URL will typically be a Tailscale Funnel URL (e.g. `https://<node>.tail<id>.ts.net/mcp`) since the daemon runs on a remote server.

For local development where the daemon runs on the same machine, use `http://127.0.0.1:7890/mcp`.

#### Claude Code

Run from your project directory:

```bash
claude mcp add --transport http bento http://127.0.0.1:7890/mcp \
  --header "Authorization: Bearer <token>"
```

This writes to `~/.claude.json` under the current project (local scope — the token stays out of any committed file). Pass `--scope user` to share the entry across all projects on this machine.

Restart Claude Code (or run `/mcp` and reconnect) to pick up the change.

```json
"mcpServers": {
    "bento": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:7890/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
}
```

#### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.bento]
url = "http://127.0.0.1:7890/mcp"
http_headers = { Authorization = "Bearer <token>" }
```

#### pi

The `remote-workloads` extension reads `BENTO_TOKEN` from the environment. Add to your project `.envrc`:

```bash
export BENTO_DAEMON_URL="http://127.0.0.1:7890"
export BENTO_TOKEN="<token>"
```

Then restart pi to pick up the new environment.


## CLI Reference

The `bento` CLI manages the daemon lifecycle and provides operational visibility.

### Lifecycle

#### `bento daemon start`

Start the daemon. Uses the installed user service (launchd on macOS, systemd on Linux) when present; otherwise spawns a detached Bun process.

```bash
bento daemon start
```

#### `bento daemon stop`

Stop the daemon. Sends SIGTERM and waits up to 10s before escalating to SIGKILL.

```bash
bento daemon stop
```

#### `bento daemon restart`

Stop then start the daemon. On macOS with a launchd-installed service, the service is reinstalled so the plist is regenerated — `launchctl kickstart` alone would miss edits to env vars, working directory, or `PATH`.

```bash
bento daemon restart
```

#### `bento daemon install`

Install the daemon as a user service: a launchd agent on macOS, a systemd user unit (`~/.config/systemd/user/bento.service`) on Linux.

```bash
bento daemon install
```

#### `bento daemon uninstall`

Stop, disable, and remove the user service.

```bash
bento daemon uninstall
```

### Observability

#### `bento daemon status`

Show daemon process status and probe the local and public-tunnel endpoints for reachability.

```bash
bento daemon status
```

```
daemon: pid=12345
local   : reachable (4ms) — bento uptime=3600s
tunnel  : not configured (no `tunnel:` block in bento.yaml)
```

When a tunnel is configured, the `tunnel` line reports the public URL and its latency — see [Public Access](/public-access).

#### `bento daemon logs [target]`

Show daemon logs, or logs for a specific agent.

```bash
bento daemon logs            # daemon logs
bento daemon logs reviewer   # agent-specific logs
bento daemon logs -f         # follow mode
bento daemon logs -n 100     # last 100 lines
```

| Flag             | Description                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `-f`, `--follow` | Tail logs in real-time                                                                                     |
| `-n <lines>`     | Number of lines to show (default: 50)                                                                      |
| `--agent`        | Tail the most recent agent run's stdout; pass a run ID as the positional `target` to select a specific run |
| `--render flat`  | Collapse stream-json events to readable per-turn text                                                      |
| `--render raw`   | Raw NDJSON (default)                                                                                       |

#### `bento trace <trigger-id>`

Print a full lifecycle trace for a trigger — trigger → workload → invocations → agents.

```bash
bento trace <trigger-id>
```

| Flag            | Description                                     |
| --------------- | ----------------------------------------------- |
| `--json`        | Output as JSON (for programmatic consumption)   |
| `--no-messages` | Skip extracting agent messages from stdout logs |

#### `bento queue status`

Show the Graphile Worker queue state and job counts.

```bash
bento queue status
```

```
state:     active
waiting:   2
active:    1
failed:    0
completed: 47
delayed:   0
```

#### `bento queue resume`

Resume processing after a circuit breaker trip.

```bash
bento queue resume
bento queue resume --token <token>
```

### Diagnostics

#### `bento doctor`

Validate infrastructure: config, database, runtimes, sandbox, tunnel, daytona, auth, repos, orchestrator, worktrees, workloads, and queue. Checks are defined in `bento.doctor.yaml`.

```bash
bento doctor
```

| Flag     | Description                                                              |
| -------- | ------------------------------------------------------------------------ |
| `--fix`  | Auto-remediate issues (requires per-check opt-in in `bento.doctor.yaml`) |
| `--json` | Output as JSON                                                           |

#### `bento probe <scope> [target]`

Run a single sandbox probe through the daemon.

```bash
bento probe runtime claude
bento probe env ANTHROPIC_API_KEY
bento probe gh-auth
bento probe ping claude/claude-sonnet-4-6
```

| Scope     | Target              | Description                                             |
| --------- | ------------------- | ------------------------------------------------------- |
| `runtime` | `<name>`            | Check a runtime is installed and callable               |
| `env`     | `<KEY>`             | Check an environment variable is visible in the sandbox |
| `gh-auth` | —                   | Check GitHub authentication                             |
| `ping`    | `<runtime>/<model>` | Round-trip a minimal request to a model                 |

#### `bento runtimes`

Ping each unique `(runtime, model)` combination referenced by `agents/*/SOUL.md` and `skills/*/SOUL.md`.

```bash
bento runtimes
```

| Flag             | Description                        |
| ---------------- | ---------------------------------- |
| `--timeout <ms>` | Per-combo timeout (default: 60000) |

### Triggers & auth

#### `bento trigger inspect <id>`

Show what the runtime would receive for a stored trigger.

```bash
bento trigger inspect <id>
```

| Flag              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `--event`         | Print the original webhook payload (JSON)                          |
| `--prompt`        | Print the rendered user prompt                                     |
| `--system-prompt` | Print the assembled system prompt (SOUL.md + skill body + augment) |
| `--args`          | Print the full argv as JSON                                        |
| `--size`          | Print prompt + argv size breakdown with token estimates            |
| `--json`          | Print the full inspection result as JSON                           |
| `--pipeline <n>`  | Pick a single pipeline when multiple match                         |

#### `bento replay <trigger-id>`

Re-dispatch a stored trigger through the daemon.

```bash
bento replay <trigger-id>
bento replay <trigger-id> --payload '{"key":"value"}'
```

| Flag               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `--payload <json>` | Override the trigger payload                       |
| `--token <token>`  | Management token (or set `BENTO_MANAGEMENT_TOKEN`) |

#### `bento trigger schedule <name>`

Fire a scheduled pipeline now, bypassing its cron — the manual equivalent of a cron tick.

```bash
bento trigger schedule triage-sweep
```

| Flag              | Description                                        |
| ----------------- | -------------------------------------------------- |
| `--token <token>` | Management token (or set `BENTO_MANAGEMENT_TOKEN`) |

#### `bento token`

Manage bearer tokens for authenticated daemon access.

```bash
bento token issue --email you@example.com
bento token list
bento token revoke <id>
```

| Subcommand    | Flags                                                    | Description                                                            |
| ------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
| `issue`       | `--email <addr>` (required), `--name <label>`, `--force` | Mint a bearer token; `--force` rotates an existing token for the email |
| `list`        | —                                                        | List issued tokens                                                     |
| `revoke <id>` | —                                                        | Revoke a token by id                                                   |

#### `bento ask <query>`

Search the wiki, blueprints, and recipes, then answer with Claude.

```bash
bento ask "how do I configure a tunnel?"
```

| Flag            | Description                               |
| --------------- | ----------------------------------------- |
| `--fast`        | BM25 only — no LLM reranking, instant     |
| `--runtime <r>` | Runtime to use (default: claude)          |
| `--model <m>`   | Model to use (default: claude-sonnet-4-6) |

### Global Options

| Option            | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `--port <port>`   | Daemon port for status/probe/queue commands (default: 7890)                    |
| `--token <token>` | Management token for state-changing commands (or set `BENTO_MANAGEMENT_TOKEN`) |

### Environment Variables

| Variable                 | Description                            |
| ------------------------ | -------------------------------------- |
| `BENTO_DAEMON_ENTRY`     | Override path to the daemon entrypoint |
| `BENTO_MANAGEMENT_TOKEN` | Auth token for management endpoints    |


## Configuration

Bento reads two config layers when the daemon starts:

* **`.bento/daemon.yaml`** — daemon-wide settings (database, ports, defaults, tunnel)
* **`.bento/pipelines/*.yaml`** — one file per pipeline definition

Both files are created by `bento init`. Runtime state (PID, logs, workspaces) lives under `~/.bento/<name>/` and is never committed.

Environment variables are expanded with `${VAR}` syntax in both files.

***

### daemon.yaml

```yaml
# Daemon identity — used for launchd/systemd service name and log dir
name: bento

logging:
  level: info          # error | warn | info | debug

database:
  url: postgresql://bento:bento@localhost:8421/bento

# Global defaults applied to every pipeline unless overridden
defaults:
  limits:
    max_concurrent: 2
  guardrails:
    timeout: 300       # seconds before an agent run is killed
    max_tokens: 50000

# The orchestrator decides which agent/model handles a given workload
orchestrator:
  runtime: claude
  model: claude-opus-4-6

# Named repo shortcuts — used in pipeline prompts via {{repo.*}}
repos:
  my-project:
    url: acme/my-project   # GitHub owner/repo
    branch: main
    issue_tracker: github

webhooks:
  host: 127.0.0.1
  port: 7890
  secret: ${GITHUB_WEBHOOK_SECRET}

# Optional: expose the webhook port via a public tunnel at startup.
# See Public Access for Cloudflare and Tailscale options.
# tunnel:
#   provider: cloudflare
#   mode: quick

queue:
  concurrency: 2
  retry:
    attempts: 1
  circuit_breaker:
    failure_threshold: 3

# Optional: override the sandbox backend (auto-detected by default)
# sandboxes:
#   backend: docker

# Knowledge retrieval — inject relevant source context into agent prompts
pipeline:
  retrieve:
    topK: 20
```

#### Field reference

| Field                                     | Default     | Description                                                                        |
| ----------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `name`                                    | `bento`     | Service identifier; sets the launchd/systemd unit name and `~/.bento/<name>/` path |
| `logging.level`                           | `info`      | Log verbosity: `error`, `warn`, `info`, `debug`                                    |
| `database.url`                            | —           | PostgreSQL connection string                                                       |
| `defaults.limits.max_concurrent`          | —           | Max simultaneous agent runs across all pipelines                                   |
| `defaults.guardrails.timeout`             | —           | Seconds before a run is killed (pipeline can override)                             |
| `defaults.guardrails.max_tokens`          | —           | Token budget per run                                                               |
| `orchestrator.runtime`                    | `claude`    | Runtime used for orchestration decisions                                           |
| `orchestrator.model`                      | —           | Model override for the orchestrator                                                |
| `webhooks.host`                           | `127.0.0.1` | Bind address                                                                       |
| `webhooks.port`                           | `7890`      | Bind port                                                                          |
| `webhooks.secret`                         | —           | GitHub webhook secret for HMAC verification                                        |
| `queue.concurrency`                       | —           | Parallel jobs the queue worker runs                                                |
| `queue.retry.attempts`                    | `1`         | Retry count on job failure                                                         |
| `queue.circuit_breaker.failure_threshold` | —           | Failures before the circuit opens                                                  |
| `pipeline.retrieve.topK`                  | —           | Number of source chunks injected per prompt (requires `qmd`)                       |

***

### Pipeline files

Each file under `.bento/pipelines/` defines one pipeline. The filename is cosmetic; the `name:` field (or the filename stem if omitted) is the pipeline's identity.

#### Webhook trigger

```yaml
name: pr-review

trigger:
  github:
    - pull_request.opened
    - pull_request.synchronize

agent: reviewer

prompt: |
  Review PR #{{event.pull_request.number}} ("{{event.pull_request.title}}")
  on {{event.repository.full_name}}, opened by @{{event.pull_request.user.login}},
  for merge readiness.

guardrails:
  timeout: 900       # override the daemon default for this pipeline
```

#### Schedule trigger

```yaml
trigger:
  schedule: "*/5 * * * *"   # standard cron expression

agent: heartbeat
prompt: |
  Reply with exactly the word "pong" and nothing else.

sandbox:
  backend: docker    # override sandbox for this pipeline

guardrails:
  read_only: true
  timeout: 60

options:
  stateless: true    # skip injecting/accumulating run notes

orchestrator: false  # bypass orchestrator for trivial tasks
```

#### Trigger sources

See [Triggers](/triggers) for the full reference — event string formats, filter syntax, cron expressions, and prompt template variables.

#### Pipeline field reference

| Field                   | Default        | Description                                                     |
| ----------------------- | -------------- | --------------------------------------------------------------- |
| `name`                  | filename stem  | Pipeline identifier                                             |
| `trigger`               | —              | One or more trigger sources (required)                          |
| `agent`                 | —              | Agent persona to use (`agents/<name>/SOUL.md`)                  |
| `prompt`                | —              | Prompt template; `{{event.*}}` expands from the webhook payload |
| `guardrails.timeout`    | daemon default | Seconds before the run is killed                                |
| `guardrails.max_tokens` | daemon default | Token budget                                                    |
| `guardrails.read_only`  | `false`        | Restrict agent to read-only file operations                     |
| `sandbox.backend`       | auto-detected  | Override sandbox: `docker`, `podman`, `daytona`, `just-bash`    |
| `options.stateless`     | `false`        | Skip cross-run note injection/accumulation                      |
| `orchestrator`          | `true`         | Set to `false` to bypass orchestrator routing                   |

***

### Auth tokens

Bearer tokens are managed via the CLI and stored in the daemon's database. See [Authentication](/authentication).

```yaml
# daemon.yaml — static token config (alternative to CLI-issued tokens)
auth:
  tokens:
    - id: cli-prod
      secret: ${BENTO_TOKEN_CLI}
      scopes: ["pipelines:*", "agents:*"]
    - id: ci-runner
      secret: ${BENTO_TOKEN_CI}
      scopes: ["pipelines:review"]
```


## Getting Started

Bento is an opinionated framework for running AI agents in response to events. It provides the scaffolding and plumbing to respond to a range of triggers and run agents in ephemeral containerised sandboxes, with no human in the loop.

### Prerequisites

* [Docker](https://docs.docker.com/get-docker/) — for the Postgres database
* [Claude Code](https://github.com/anthropics/claude-code) (`claude`) — the default agent runtime
* A GitHub account (for webhook triggers)
* **macOS only**: Homebrew SQLite — `brew install sqlite`
  *(Apple's system SQLite omits loadable extensions, which qmd requires for vector search)*

**Optional — knowledge retrieval:**

```bash
npm install -g @tobilu/qmd
```

When `qmd` is on PATH, the daemon indexes your source files and injects relevant
context into agent prompts. Missing → retrieval phase silently disabled.

### Install

```bash
curl -sSL https://install.getbento.sh | sh
```

Downloads the `bento` binary for your platform. The installer reports where it
landed (typically `/opt/homebrew/bin` on macOS, `/usr/local/bin` on Linux).

Verify:

```bash
bento --version
```

### Start Postgres

The daemon needs Postgres at `postgresql://bento:bento@localhost:8421/bento`.
Grab the canonical compose file and bring it up:

```bash
curl -fsSL https://install.getbento.sh/services.yml -o docker-compose.yml
docker compose up -d
```

(Data lives in a named volume — `docker compose down` doesn't wipe it. `down -v` does.)

### Scaffold a project

Inside the directory you want to wire up:

```bash
cd ~/dev/my-project
bento init
```

This creates `.bento/daemon.yaml` (daemon config) and `.bento/pipelines/pr-review.yaml`
(a starter PR-review pipeline). If the directory has a GitHub remote, the repo is
detected automatically.

`.bento/` is gitignored by default — it holds per-developer secrets and local
settings. Edit `daemon.yaml` to set your `GITHUB_WEBHOOK_SECRET` and database URL.

### Register and start the daemon

Run this from the project directory (the same one where you ran `bento init`):

```bash
bento daemon install   # registers launchd (macOS) or systemd (Linux)
bento daemon start
```

`bento daemon install` writes a service unit that auto-restarts the daemon and
runs it under your user account. `bento daemon start` kicks it off immediately
without waiting for a reboot.

Check everything is healthy:

```bash
bento doctor
```

### Connect GitHub webhooks

The daemon listens for GitHub webhook events. Point your repo's webhook at the daemon:

1. Run `bento doctor` — it shows your webhook URL
2. In your GitHub repo: **Settings → Webhooks → Add webhook**
   * Payload URL: the URL from `bento doctor`
   * Content type: `application/json`
   * Secret: the value of `GITHUB_WEBHOOK_SECRET` from your config
   * Events: *Pull requests*, *Pull request reviews*, *Issue comments*

### Open a PR

Once the webhook is connected, open a pull request. The daemon receives the event,
spins up an agent, and posts a review to the PR.

Watch it happen:

```bash
bento daemon logs -f
```

### Configuration reference

`.bento/daemon.yaml` controls daemon-wide settings (database URL, ports, sandbox
backend, pipeline lifecycle hooks). Each file under `.bento/pipelines/` is one
pipeline definition. See [Configuration](/configuration) for the full field reference.

**Runtime state** (PID, log, agent dirs) lives under `~/.bento/<name>/` where
`name` is the `name:` field in `daemon.yaml` (defaults to `bento`). Workspaces
are shared at `~/.bento/workspaces/`. Neither directory is committed to git.


## Inspecting Runs

Every pipeline run leaves a paper trail across three surfaces: the **triggers**
table (the entry point), the run's **trace** (envelope + per-phase tasks), and
the agent's **logs** (raw stdout / parsed turns). This page walks through how
to navigate them when you need to know what happened.

### 1. Find a trigger

Triggers are the source of truth — every webhook, every cron tick, every MCP
call enters the system through one. The DB is the most direct way to list
them:

```bash
PGPASSWORD=bento psql -h localhost -U bento -d bento \
  -c "select id, kind, source, event_type, pipeline, status, run_id, arrived_at
      from triggers
      order by arrived_at desc
      limit 10;"
```

```
      id      |  kind   | source  | event_type          | pipeline  | status | run_id     | arrived_at
--------------+---------+---------+---------------------+-----------+--------+------------+--------------------
 d990d0a0-5f1 | webhook | github  | pull_request.opened | pr-review | done   | XbSjXLrysC | 2026-05-26 11:35:21
 e10552e5-7d1 | schedule| -       | -                   | heartbeat | done   | mecOey_7rx | 2026-05-26 11:40:00
```

Filter by `kind`, `pipeline`, `status`, or `source` to narrow down. The
shortened id (first 12 chars) is enough for the trace command — `bento trace`
accepts any unique prefix.

### 2. Trace a trigger

`bento trace <id>` follows one trigger through every layer it touched:

```bash
bento trace d990d0a0-5f1
```

```
══════════════════════════════════════════════════════════════════════
  TRACE: d990d0a0-5f1
══════════════════════════════════════════════════════════════════════

┌─ Trigger
│  id:         d990d0a0-5f1
│  kind:       webhook
│  source:     github/pull_request.opened
│  pipeline:   pr-review
│  status:     done
│  arrived:    Tue May 26 2026 12:35:21
│  completed:  Tue May 26 2026 12:42:38
│  run_id:     XbSjXLrysC
└

┌─ Workload
│  id:       043cbc31-31ac-4726-862c-07511d286547
│  status:   active
│  ttl:      3600s
└

┌─ Invocations (1)
└── [a020a45e] reviewer
      runtime=claude model=claude-sonnet-4-6 status=completed duration=436.7s
      ✓ workspace-setup (setup) 1457ms [ok]
      ✓ task:reviewer (spawn) 220750ms [ok]
      ✓ task:reviewer (spawn) 232402ms [ok]
      ✓ spawn (spawn) 435163ms [ok]

      ┌─ Orchestrator Output
      │ <agent's final synthesised reply>
      └
```

The four sections, top to bottom:

* **Trigger** — what came in (HTTP webhook, cron, MCP), when, which pipeline
  matched, terminal status.
* **Workload** — the longer-lived container an invocation belongs to. One
  webhook can submit several invocations under one workload.
* **Invocations** — one per agent run. Each lists its phases (`workspace-setup`,
  `spawn`, hooks) with duration + outcome. An orchestrated run shows
  `task:<agent>` sub-spawns for each tool call the orchestrator made.
* **Orchestrator Output** — what the agent finally returned, after notes /
  citations / post-back processing.

#### Useful flags

| Flag            | When                                                     |
| --------------- | -------------------------------------------------------- |
| `--json`        | Pipe to `jq` for scripted inspection                     |
| `--no-messages` | Skip agent message parsing — faster when the run is long |

### 3. Read the agent's stdout

The trace shows *what* the agent said at the end. To see *how it got there* —
turn-by-turn, tool calls, intermediate thoughts — go to the agent log:

```bash
# Raw stream-json (the format the runtime CLI emitted)
bento daemon logs XbSjXLrysC --agent

# Same data, collapsed to readable per-turn text
bento daemon logs XbSjXLrysC --agent --render flat
```

`--render flat` is usually what you want during debugging; `raw` is for
piping into a parser.

### 4. Watch a daemon in flight

For *live* tracing — what the daemon is doing right now — tail its log:

```bash
bento daemon logs        # last 50 lines
bento daemon logs -f     # follow mode (tail -f)
bento daemon logs -n 200 # widen the window
```

The daemon's `name:` field in `.bento/daemon.yaml` (default `bento`) determines
where things live and what they're called:

| Thing         | Path / label                 |
| ------------- | ---------------------------- |
| Log file      | `~/.bento/<name>/daemon.log` |
| PID file      | `~/.bento/<name>/daemon.pid` |
| launchd label | `dev.bento.<name>`           |
| systemd unit  | `<name>.service`             |
| Process title | `<name>-daemon`              |

So with `name: myproject`, journalctl reads:

```bash
journalctl --user -u myproject.service -f
```

Run-id-stamped lines correlate with `bento trace`:

```
[INFO] [workload-manager] invocation a020a45e running
[INFO] [workload-manager] invocation a020a45e workspace ready  duration=1457ms
[INFO] [workload-manager] pipeline [pr-review] executing  run=XbSjXLrysC ...
```

### 5. Common questions

**"Why did the agent fail?"** — `bento trace <id>` first. If the failure is
in a hook, the failing step shows `outcome=errored` with the captured stderr.
If the failure is in the agent itself, drop to `bento daemon logs <runId> --agent --render flat`.

**"What did the agent actually see?"** — the run dir on disk:
`~/.bento/workspaces/<workspace>/runs/<runId>/`. It holds the assembled prompt
(`meta.json`), the agent's stdout/stderr files, and per-step artifacts under
`steps/`.

**"Why didn't my webhook match a pipeline?"** — list discarded triggers:

```bash
PGPASSWORD=bento psql -h localhost -U bento -d bento \
  -c "select id, source, event_type, note from triggers
      where status = 'discarded'
      order by arrived_at desc limit 10;"
```

The `note` column carries the matcher's verdict (e.g. `no pipeline matched`,
`filter rejected: <expr>`).

**"What did setup actually do?"** — the workspace-setup task is the first
phase in every invocation; its duration tells you whether a clone happened
(seconds) or it was a no-op mkdir (milliseconds). The shell script that ran
is deterministic from `WorkspaceSource` — see
`packages/sandboxes/src/setup-script.ts:buildSetupScript`.


## Public Access

The daemon binds to `127.0.0.1:7890` by default. To accept GitHub webhooks or reach the daemon from another machine, expose it through a tunnel.

|                      | Cloudflare Quick Tunnel | Tailscale Funnel               |
| -------------------- | ----------------------- | ------------------------------ |
| **Account required** | No                      | Yes (free)                     |
| **URL stability**    | Rotates on restart      | Persistent (`*.ts.net`)        |
| **Best for**         | One-off testing, demos  | Production webhooks, daily use |
| **Prerequisite**     | `cloudflared` on PATH   | Tailscale enrolled on host     |

***

### Cloudflare Tunnel

Bento can spin up a [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) alongside the daemon, exposing the local `127.0.0.1:7890` port via an ephemeral `*.trycloudflare.com` URL with no Cloudflare account required. Useful for one-off webhook receivers, demos, and "show this to a teammate for an hour."

#### Prerequisites

* `cloudflared` on the daemon host's `PATH`. On macOS: `brew install cloudflared`. On Linux see [Cloudflare's install docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).
* `bento doctor` validates this when the `tunnel:` block is present in `bento.yaml`.

#### Quick tunnel (no account)

Add a `tunnel:` block to `bento.yaml`:

```yaml
tunnel:
  provider: cloudflare
  mode: quick
```

Then restart the daemon:

```bash
bento restart
```

The daemon spawns `cloudflared`, parses the public URL out of its startup log, and emits one info line:

```
[INFO] [tunnel] public URL ready: https://essentially-carrying-recorder-merely.trycloudflare.com
```

`bento status` surfaces the same URL:

```
local   : reachable (8ms) — @bento/daemon uptime=14s
tunnel  : reachable (83ms) — https://essentially-carrying-recorder-merely.trycloudflare.com
funnel  : not configured (tailscale funnel not active)
```

:::warning
Quick Tunnel URLs **rotate on every daemon restart**. For a stable URL use a [named tunnel](#named-tunnels-stable-url) or Tailscale Funnel.
:::

#### Use the public URL

**GitHub webhooks** — point the webhook delivery URL at:

```
https://<random>.trycloudflare.com/events
```

Make sure `webhooks.secret` in `bento.yaml` matches the GitHub webhook secret so signature verification passes. The daemon also accepts `/webhooks/github` and `/webhooks/linear`.

**MCP clients** — configure Claude Code / Codex / pi against the tunnel URL — see [Authentication](/authentication) for the exact commands. Issue a bearer token first:

```bash
bento token issue --email you@example.com
```

#### Lifecycle

* The tunnel is supervised as a child of the daemon. `bento stop` sends `SIGTERM` to `cloudflared` before stopping the HTTP server.
* If `cloudflared` crashes while the daemon is up, the daemon logs the exit code at `warn` and keeps running. Restart to re-establish the tunnel.
* The daemon does **not** block on tunnel readiness during startup.

#### Named tunnels (stable URL)

For a stable URL, pre-create a **named tunnel** in your Cloudflare account. The auto-generated `<uuid>.cfargotunnel.com` URL is only valid as a CNAME target — you need a real hostname.

##### Prerequisites

* A free [Cloudflare account](https://dash.cloudflare.com/sign-up).
* `cloudflared` on the host.
* A hostname you control with a CNAME pointing at the tunnel:
  * **Cloudflare DNS** — `cloudflared tunnel route dns` creates the CNAME automatically.
  * **External DNS** — create `bento.example.com CNAME <tunnel-uuid>.cfargotunnel.com` yourself.

##### One-time setup

1. Authenticate `cloudflared`:

   ```bash
   cloudflared tunnel login
   ```

2. Create the tunnel:

   ```bash
   cloudflared tunnel create bento-prod
   ```

3. Route a hostname:

   ```bash
   # Cloudflare-managed DNS:
   cloudflared tunnel route dns bento-prod bento.example.com

   # External DNS: add a CNAME manually:
   # bento.example.com   CNAME   <uuid>.cfargotunnel.com
   ```

##### Point bento at the tunnel

```yaml
tunnel:
  provider: cloudflare
  mode: named
  name: bento-prod
```

Then `bento restart`. The daemon runs `cloudflared tunnel run`, detects the registered hostname, and surfaces it in `bento status`.

##### Tear down

```bash
cloudflared tunnel delete bento-prod
```

Remove the DNS CNAME separately via your DNS provider.

##### Files

| Path                         | Created by              | Purpose                                  | Needed at runtime?          |
| ---------------------------- | ----------------------- | ---------------------------------------- | --------------------------- |
| `~/.cloudflared/cert.pem`    | `tunnel login`          | Manage tunnels (create/delete/route DNS) | No                          |
| `~/.cloudflared/<uuid>.json` | `tunnel create <name>`  | Authenticate the running tunnel          | **Yes**                     |
| `~/.cloudflared/config.yml`  | hand-written (optional) | Ingress rules                            | Only if not passing `--url` |

#### Notes

* Quick tunnels are public and unauthenticated at the tunnel layer. The daemon's bearer-token middleware and webhook signature verification are the only auth — never disable them.
* Cloudflare may rate-limit Quick Tunnels under heavy traffic. For production webhook ingestion use a named tunnel.

***

### Tailscale Funnel

[Tailscale Funnel](https://tailscale.com/kb/1223/funnel) gives a persistent TLS-terminated `*.ts.net` URL routed back to your machine over the tailnet.

Two ways to wire it up:

* **Let bento manage it** — `tunnel:` block in `bento.yaml`; bento calls `tailscale funnel --bg <port>` at start and teardown.
* **Manage it yourself** — run `tailscale funnel --bg 7890` once; `bento status` still detects it.

#### Prerequisites

* A [Tailscale](https://tailscale.com) account with the daemon's host enrolled.
* HTTPS certificates and Funnel enabled for your tailnet (admin console: **DNS → HTTPS Certificates** and **Access Controls → Funnel**).

#### Bento-managed mode

```yaml
tunnel:
  provider: tailscale
  mode: funnel
```

`bento restart` execs `tailscale funnel --bg 7890`, polls `tailscale funnel status` for the public URL, and surfaces it via `bento status`.

On shutdown bento runs `tailscale funnel --bg off` — but only if it was the one that enabled the funnel. If a funnel was already active at startup, bento adopts the existing URL and skips both setup and teardown.

:::warning
`tailscale funnel --bg off` is **not port-scoped** — it disables every funnel on the host. If you run multiple funnels on the same machine, set them up before starting bento (so bento adopts and leaves them alone) or use manual mode.
:::

#### Manual mode

```bash
tailscale funnel --bg 7890
```

`--bg` persists across shell exits. You only need to run this once per machine.

Verify:

```bash
tailscale funnel status
# https://8640p.tail673878.ts.net (Funnel on)
# |-- / proxy http://127.0.0.1:7890
```

`bento status` picks it up automatically:

```
local   : reachable (4ms) — bento uptime=120s
funnel  : reachable (38ms) — https://8640p.tail673878.ts.net
```

#### Use the public URL

**MCP clients** — configure Claude Code, Codex, or pi — see [Authentication](/authentication). Issue a token first:

```bash
bento token issue --email you@example.com
```

**GitHub webhooks** — point the delivery URL at:

```
https://<node>.tail<id>.ts.net/events
```

Set the same secret as `webhooks.secret` in `bento.yaml`.

#### Stopping the funnel

```bash
tailscale funnel --bg off
```

Unbinds the public URL but leaves the daemon running locally.

#### Notes

* Funnel only serves ports `443`, `8443`, and `10000` on the public side. Tailscale maps `:443` → `:7890` automatically.
* Funnel traffic counts against tailnet bandwidth limits. For high-volume webhook traffic consider a server with a real DNS record.
* The funnel URL is publicly reachable. Authentication is enforced by the daemon's bearer-token middleware — never disable it.


## Troubleshooting

### Start here: `bento doctor`

```bash
bento doctor
```

Checks the daemon process, database connection, `cloudflared` / `tailscale` availability, and webhook reachability. Most setup problems show up here with a plain-text description.

***

### Daemon won't start

**Symptom:** `bento daemon start` exits immediately or `bento status` shows the daemon as unreachable.

1. Check the daemon log:
   ```bash
   bento daemon logs
   ```
2. Common causes:
   * **Port 7890 already in use** — `lsof -i :7890` to find the occupant
   * **Database unreachable** — confirm Postgres is running: `docker compose ps`
   * **Missing `GITHUB_WEBHOOK_SECRET`** — the variable must be set in your shell or `.env` file before `bento daemon start`

***

### Webhooks not firing

**Symptom:** You open a PR and the daemon receives nothing.

1. Confirm the daemon is reachable from the internet:
   ```bash
   bento doctor
   # → local: reachable, tunnel: reachable
   ```
2. Check the GitHub webhook delivery log (repo **Settings → Webhooks → Recent Deliveries**). Look for HTTP errors or timeouts.
3. If you're using a Cloudflare Quick Tunnel, the URL rotates on restart — re-register it with GitHub after every `bento restart`.
4. Confirm the webhook secret in GitHub matches `webhooks.secret` in `daemon.yaml`. A mismatch returns `401` and silently drops the event.
5. Check daemon logs for signature verification errors:
   ```bash
   bento daemon logs -f
   ```

***

### Agent run not appearing

**Symptom:** A webhook was delivered (GitHub shows `200`) but no agent run shows up.

1. Check the pipeline trigger matches the event type. `pull_request.opened` and `pull_request.synchronize` are the most common:
   ```bash
   bento trace <event-id>
   ```
2. Check queue depth — a backlog may delay the run:
   ```bash
   bento queue status
   ```
3. Check `defaults.limits.max_concurrent` in `daemon.yaml`. If all slots are taken, new jobs queue behind the running ones.

***

### Agent run failed or timed out

**Symptom:** The run appears in `bento status` but shows `failed` or `timeout`.

1. Read the agent's stdout:
   ```bash
   bento logs <invocation-id>
   ```
2. Increase `guardrails.timeout` in the pipeline file if the task is genuinely long-running.
3. Check for sandbox issues — if the agent can't clone the repo or reach the network, it fails early:
   ```bash
   bento probe <invocation-id>
   ```
4. Check `queue.circuit_breaker.failure_threshold` — repeated failures open the circuit and stop queuing jobs for that pipeline until the daemon restarts.

***

### Authentication failures

**Symptom:** `401 Unauthorized` from the daemon or MCP client can't connect.

1. List issued tokens:
   ```bash
   bento token list
   ```
2. Verify the token your client is using matches one of the listed IDs.
3. Confirm the token's `scopes` permit the operation (e.g. `pipelines:*` for pipeline invocations).
4. Re-issue a token if needed:
   ```bash
   bento token issue --email you@example.com
   ```
   See [Authentication](/authentication) for client setup.

***

### Tunnel not reachable

**Symptom:** `bento status` shows `tunnel : pending` or `tunnel : error`.

**Cloudflare Quick Tunnel:**

* Confirm `cloudflared` is on PATH: `which cloudflared`
* The tunnel takes up to 5s to establish after `bento start`. Run `bento status` again after a few seconds.
* Check daemon logs for `cloudflared` errors:
  ```bash
  bento daemon logs | grep tunnel
  ```

**Tailscale Funnel:**

* Confirm the host is enrolled in your tailnet: `tailscale status`
* Confirm HTTPS certificates are enabled in the Tailscale admin console (**DNS → HTTPS Certificates**)
* Confirm Funnel is enabled (**Access Controls → Funnel**)
* Run `tailscale funnel status` to verify the funnel is active

***

### Database issues

**Symptom:** `database unreachable` in `bento doctor`.

```bash
docker compose ps         # is the container running?
docker compose up -d      # restart if stopped
```

The canonical Compose file sets up Postgres at `postgresql://bento:bento@localhost:8421/bento`. Confirm this matches `database.url` in `daemon.yaml`.

***

### Inspecting a specific run

For deep inspection of a single invocation — agent stdout, prompt, context, and timing — see [Inspecting Runs](/inspect).


## Filters

All event-based triggers (`github`, `linear`, `webhook`) support a `filter:` block. Filters let multiple pipelines subscribe to the same event type with different criteria — only the pipelines whose filters pass are enqueued.

All conditions in a `filter:` block are AND-ed: every condition must pass for the pipeline to fire.

### `filter.repos`

Allow-list of GitHub `repository.full_name` values. Events from repos not in the list are dropped.

```yaml
filter:
  repos: [acme/frontend, acme/backend]
```

Only applies to `github` triggers.

### `filter.when`

AND-equality checks against nested payload paths. Every entry must match.

```yaml
filter:
  when:
    review.state: approved
    pull_request.user.login: my-bot   # PR must be authored by the bot
```

Paths use dot notation to traverse nested JSON. The check is strict equality (`===`).

### `filter.not`

Reject the event if **any** entry matches. Useful for loop-breaker guards.

```yaml
filter:
  not:
    review.user.login: my-bot         # ignore reviews submitted by the bot
    comment.user.login: my-bot        # ignore comments from the bot
```

### `filter.mentioned`

Checks whether the daemon's configured GitHub login appears as an `@mention` in the event's text body (comment body, review body, etc.).

```yaml
filter:
  mentioned: true    # fire only when bot is @-mentioned (actor mode)
  # or
  mentioned: false   # fire only when bot is NOT @-mentioned (observer mode)
```

Pairing an observer pipeline (`mentioned: false`) with an actor pipeline (`mentioned: true`) on the same event type is the standard pattern for tiered response — observe everything, act only when asked:

```yaml
# pr-review-comment.yaml — observe all inline comments
trigger:
  github: [pull_request_review_comment.created]
  filter:
    not: { comment.user.login: my-bot }
    mentioned: false
agent: reviewer
skill: pr-comment-review

# pr-review-comment-mentioned.yaml — act when @-mentioned
trigger:
  github: [pull_request_review_comment.created]
  filter:
    mentioned: true
agent: editor
skill: pr-comment-act
```

### `filter.assignee`

Checks `payload.assignee.login`. The special value `bot` resolves to the daemon's configured GitHub login.

```yaml
filter:
  assignee: bot     # only fire when the event is assigned to the bot
```

### Combining filters

All conditions in the block must pass simultaneously. This example fires only for approved reviews on bot-authored PRs, submitted by a human (not the bot itself):

```yaml
trigger:
  github:
    - pull_request_review.submitted
  filter:
    when:
      review.state: approved
      pull_request.user.login: my-bot
    not:
      review.user.login: my-bot
```

### See also

* [Event Matcher](/architecture/event-matcher-layered-architecture) — planned richer routing (per-repo agents, typed payloads, `filter.branches`, `filter.authors`)


## GitHub Trigger

The daemon accepts GitHub webhooks at `/webhooks/github` and the alias `/events`. Every request is verified with HMAC-SHA256 against the `webhooks.secret` in `daemon.yaml` — unverified requests are rejected.

### Event string format

GitHub sends an `x-github-event` header (the event type) and a JSON payload. If the payload has an `action` field, the daemon combines them with a dot:

```
x-github-event: pull_request
payload.action: opened
→ event string: "pull_request.opened"

x-github-event: deployment_status
(no action field)
→ event string: "deployment_status"
```

### Prefix matching

A trigger pattern matches if it equals the event string **or** is a prefix of it (separated by `.`). This means you can subscribe to an entire event type:

```yaml
trigger:
  github:
    - pull_request          # matches pull_request.opened, pull_request.synchronize, pull_request.closed, ...
    - pull_request.opened   # matches only pull_request.opened
```

### Common events

| Event pattern                         | When                                          |
| ------------------------------------- | --------------------------------------------- |
| `pull_request.opened`                 | New PR opened                                 |
| `pull_request.synchronize`            | New commits pushed to an open PR              |
| `pull_request.closed`                 | PR closed (merged or abandoned)               |
| `pull_request_review.submitted`       | A reviewer submits a review                   |
| `pull_request_review_comment.created` | An inline review comment is posted            |
| `issue_comment.created`               | A top-level PR/issue comment is posted        |
| `deployment_status`                   | A deployment status event (e.g. CI completes) |
| `push`                                | Commits pushed to any branch                  |

### Loop-breaker guards

The daemon applies two automatic guards before matching pipelines — these reject events even if the trigger pattern would otherwise match:

1. **Self-authored comments** — if `sender.login` matches the daemon's configured GitHub login, issue and PR comments are rejected. This prevents a pipeline from triggering on its own output and looping. (Reviews and pushes are exempt — the bot needs to participate in the review cycle.)
2. **Merged or closed PR** — if a PR event arrives for a PR that is already merged or closed, the event is rejected.

### Examples

```yaml
# Fire on PR open and every push to the PR branch
trigger:
  github:
    - pull_request.opened
    - pull_request.synchronize

# Fire when a deployment succeeds on a specific repo
trigger:
  github:
    - deployment_status
  filter:
    repos: [acme/backend]
    when:
      deployment_status.state: success

# Observer mode: every inline review comment, except from the bot itself
trigger:
  github:
    - pull_request_review_comment.created
  filter:
    not:
      comment.user.login: my-bot
    mentioned: false
```

### Prompt variables

`{{event.*}}` paths available in the prompt template for GitHub events:

#### Pull request events

| Variable                          | Value                    |
| --------------------------------- | ------------------------ |
| `event.pull_request.number`       | PR number                |
| `event.pull_request.title`        | PR title                 |
| `event.pull_request.body`         | PR description           |
| `event.pull_request.user.login`   | PR author's GitHub login |
| `event.pull_request.html_url`     | URL to the PR            |
| `event.pull_request.head.ref`     | Head branch name         |
| `event.pull_request.head.sha`     | Head commit SHA          |
| `event.pull_request.base.ref`     | Base branch name         |
| `event.pull_request.draft`        | `true` if draft          |
| `event.repository.full_name`      | `owner/repo`             |
| `event.repository.default_branch` | Default branch           |

#### Review events

| Variable                  | Value                                        |
| ------------------------- | -------------------------------------------- |
| `event.review.id`         | Review ID                                    |
| `event.review.state`      | `approved`, `changes_requested`, `commented` |
| `event.review.body`       | Review summary body                          |
| `event.review.user.login` | Reviewer's login                             |

#### Comment events

| Variable                   | Value                                |
| -------------------------- | ------------------------------------ |
| `event.comment.body`       | Comment text                         |
| `event.comment.user.login` | Commenter's login                    |
| `event.comment.path`       | File path (inline comments only)     |
| `event.comment.line`       | Line number (inline comments only)   |
| `event.comment.diff_hunk`  | Diff context (inline comments only)  |
| `event.issue.number`       | PR/issue number (top-level comments) |
| `event.issue.title`        | PR/issue title                       |

#### Deployment events

| Variable                        | Value                                 |
| ------------------------------- | ------------------------------------- |
| `event.deployment.ref`          | Branch or tag deployed                |
| `event.deployment.environment`  | Target environment                    |
| `event.deployment_status.state` | `success`, `failure`, `pending`, etc. |

### See also

* [Filters](/triggers/filters) — narrow which events reach this pipeline
* [Public Access](/public-access) — expose the daemon to receive webhooks


## Triggers

A trigger is what causes a pipeline to fire. Each pipeline declares exactly one `trigger:` block in its YAML file. When the daemon receives an event that matches a pipeline's trigger (and passes any filters), it enqueues a run.

### Trigger types

| Type                               | Key                    | When it fires                                                    |
| ---------------------------------- | ---------------------- | ---------------------------------------------------------------- |
| **[GitHub](/triggers/github)**     | `trigger.github`       | Incoming GitHub webhook event matching the listed event patterns |
| **[Linear](/triggers/linear)**     | `trigger.linear`       | Incoming Linear webhook event matching the listed event patterns |
| **[Webhook](/triggers/webhook)**   | `trigger.webhook`      | POST to `/webhooks/{name}` matching the listed names             |
| **[Schedule](/triggers/schedule)** | `trigger.schedule`     | Cron expression evaluated by Graphile Worker                     |
| **[Manual](/triggers/manual)**     | `trigger.manual: true` | On-demand via `bento trigger fire <pipeline>`                    |

A pipeline can combine `manual: true` with any other trigger type to enable both on-demand and automatic firing.

All event-based triggers (`github`, `linear`, `webhook`) support a [`filter:`](/triggers/filters) block for narrowing which events reach the pipeline.


## Linear Trigger

The daemon accepts Linear webhooks at `/webhooks/linear` (or any request carrying a `linear-event` header).

### Event string format

Linear sends `type` and optionally `action` in the JSON payload:

```
payload.type:   Issue
payload.action: create
→ event string: "Issue.create"

payload.type:   Issue
(no action)
→ event string: "Issue"
```

### Supported events

| Event pattern    | When                       |
| ---------------- | -------------------------- |
| `Issue.create`   | New issue created          |
| `Issue.update`   | Issue updated              |
| `Comment.create` | Comment posted on an issue |

### Example

```yaml
# Fire when a new issue is created in a specific team
trigger:
  linear:
    - Issue.create
  filter:
    when:
      data.team.key: HAR
```

### Prompt variables

| Variable                 | Value                 |
| ------------------------ | --------------------- |
| `event.data.title`       | Issue title           |
| `event.data.description` | Issue description     |
| `event.data.team.key`    | Team key (e.g. `HAR`) |
| `event.data.priority`    | Issue priority        |

### See also

* [Filters](/triggers/filters) — narrow which events reach this pipeline


## Manual Trigger

Setting `trigger.manual: true` makes a pipeline fireable on demand:

```bash
bento trigger fire <pipeline-name>
```

Combine with another trigger type to support both automatic and on-demand firing:

```yaml
# Fires automatically on every PR, and also on demand
trigger:
  manual: true
  github:
    - pull_request.opened
agent: reviewer
```

### Example: smoke test on demand

```yaml
name: ask-knowledge-smoke
trigger:
  manual: true
  repo: acme/my-project
agent: solver
prompt: |
  Run the smoke tests and report pass/fail.
sandbox:
  backend: docker
orchestrator: false
```

```bash
bento trigger fire ask-knowledge-smoke
```


## Schedule Trigger

Schedule triggers use a standard 5-field cron expression evaluated by [Graphile Worker](https://worker.graphile.org/).

```yaml
trigger:
  schedule: "*/5 * * * *"   # every 5 minutes
```

### Cron format

```
┌───────── minute (0–59)
│ ┌─────── hour (0–23)
│ │ ┌───── day of month (1–31)
│ │ │ ┌─── month (1–12)
│ │ │ │ ┌─ day of week (0–6, 0=Sunday)
│ │ │ │ │
* * * * *
```

Common patterns:

| Expression    | Fires                                 |
| ------------- | ------------------------------------- |
| `*/5 * * * *` | Every 5 minutes                       |
| `0 */3 * * *` | Every 3 hours (midnight, 3am, 6am, …) |
| `0 7 * * *`   | Daily at 7am                          |
| `0 0 * * 1`   | Every Monday at midnight              |

### Workspace checkout

By default a scheduled pipeline runs without a repo checkout. To clone a repo before the agent starts, set `trigger.repo` and optionally `trigger.branch`:

```yaml
trigger:
  schedule: "0 */3 * * *"
  repo: acme/my-project      # owner/name — must match a key in daemon.yaml repos:
  branch: develop            # defaults to the repo's default branch
```

### Examples

```yaml
# Liveness probe — no repo checkout needed
trigger:
  schedule: "*/5 * * * *"
agent: heartbeat
prompt: Reply with exactly the word "pong" and nothing else.
options:
  stateless: true
orchestrator: false
```

```yaml
# Daily issue solver — clones repo before running
trigger:
  schedule: "0 7 * * *"
  repo: acme/my-project
  branch: develop
agent: solver
skill: solve-issue
```

```yaml
# Periodic docs drift audit — read-only, every 3 hours
trigger:
  schedule: "0 */3 * * *"
  repo: acme/my-project
  branch: develop
agent: archivist
skill: docs-drift-audit
guardrails:
  read_only: true
  timeout: 1200
orchestrator: false
```


## Generic Webhook Trigger

Any HTTP POST to `/webhooks/{name}` creates a generic webhook event where the event string is the path segment `{name}`.

```yaml
# Fires on POST /webhooks/deployment
trigger:
  webhook:
    - deployment
```

Generic webhooks have no signature verification. Use network-level controls (tunnel auth, IP allowlist) if the endpoint is public.

### Example

```yaml
trigger:
  webhook:
    - deploy-complete
agent: notifier
prompt: |
  A deployment just completed. Summarize and post to Slack.
orchestrator: false
```

### See also

* [Filters](/triggers/filters) — narrow which events reach this pipeline
* [Public Access](/public-access) — expose the daemon to receive webhooks


## The Case for a Layered Event Matcher

:::note
**Design proposal — not yet implemented.** This documents the intended architecture for multi-repo routing. The current flat matcher (`matchPipelines()`) is still in use. Ground truth: `services/daemon/src/{webhook,pipeline,context}.ts`, `packages/config/src/index.ts`.
:::

***

### 1. Where the Current Flat Approach Breaks Down

The current path from webhook to agent execution is:

```
HTTP POST → parseEvent() → WebhookEvent → matchPipelines() → assembleContext() → executePipeline()
```

`matchPipelines()` is the entire routing brain:

```typescript
// pipeline.ts:55–67
const triggers: string[] = pipeline.trigger[source] ?? [];
if (triggers.some((t) => event.event === t || event.event.startsWith(t + "."))) {
  matches.push([name, pipeline]);
}
```

That is a string prefix test. It is the only filter in the system. Every crack in the current design flows from that single fact.

#### 1.1 Multi-repo is structurally impossible

When GitHub sends `pull_request.opened`, the payload contains `event.payload.repository.full_name` — e.g. `acme/frontend` or `acme/payments`. The current matcher **never looks at it**. You cannot write two `pr-review` pipelines that differ only by repo without naming them differently and duplicating every other field. There is no `filter.repos` concept anywhere in `PipelineTrigger`.

Concretely: if you add a second webhook source (a second GitHub App, a monorepo), every `pull_request.opened` will match every `pr-review`-type pipeline simultaneously. You'll get N×M agent invocations.

#### 1.2 Context assembly can't do its job without project scope

`assembleContext()` in `context.ts` has two stubs that are deliberately returning `null`:

```typescript
async function gatherGitHistory(_event: WebhookEvent): Promise<string | null> {
  // TODO: use git log on the affected files
  return null;
}

async function gatherRelatedPRs(_event: WebhookEvent): Promise<string | null> {
  // TODO: query GitHub API for related PRs
  return null;
}
```

These are not stubs because the implementation is hard. They are stubs because the `WebhookEvent` passed in does not carry the information needed to do the work: **no repo URL, no installation token, no default branch, no clone path.** The context layer would have to re-parse `event.payload.repository` — buried in an untyped `Record<string, unknown>` — with no guarantee that field exists (e.g. Linear events have no repo at all).

The context builder is structurally blocked until there is a typed project scope object passed alongside the event.

#### 1.3 Agent selection is static and cannot be rule-driven

`PipelineConfig` has a single `agent: string` field. Every invocation of that pipeline uses the same agent. You cannot express:

* "use `security-agent` for anything in `acme/payments`"
* "use `fast-reviewer` for draft PRs, `thorough-reviewer` for PRs targeting `main`"
* "fall back to `reviewer` when no specialist matches"

The only workaround is to create separate pipelines with separate agent fields, duplicating all prompt and guardrail config. That duplication grows O(repos × agent-types).

#### 1.4 The trigger schema can't compose filters

`PipelineTrigger` is `{ github?: string[], linear?: string[], webhook?: string[] }`. It is a flat list of event name strings. There is no place to express:

* "only for PRs targeting `main` or `release/*`"
* "except when the author is `dependabot[bot]`"
* "only for repos in the `acme` org"
* "and only when the PR has the `needs-review` label"

Adding Slack would require modifying the `PipelineTrigger` interface, the config type, the matching code, and the context switch in `formatEvent()` — all in separate files with no clear ownership boundary.

#### 1.5 `formatEvent()` has implicit source knowledge baked in

```typescript
// context.ts:60–76
function formatEvent(event: WebhookEvent): string {
  if (event.source === "github") {
    const pr = payload.pull_request as Record<string, unknown>;
    // ...
  }
}
```

Every new domain source (Slack, Sentry, JIRA) requires a new `if` branch here, and another in `assembleContext()`, and another in `matchPipelines()`. The domain logic is fractured across three files with no extraction point.

***

### 2. The Layered Architecture

The key insight: **matching, context, and execution have fundamentally different information needs.** Mixing them prevents each from working correctly.

```
Layer 1: Domain Adapter     — HTTP → normalized WebhookEvent (exists)
Layer 2: Event Classifier   — WebhookEvent → typed ClassifiedEvent<T>
Layer 3: Project Router     — ClassifiedEvent → ProjectContext
Layer 4: Pipeline Matcher   — event + project → [MatchedPipeline]
Layer 5: Context Builder    — event + project + pipeline → EnrichedContext
Layer 6: Executor           — agent + prompt + context → spawn (exists)
```

Layers 2–5 are the missing infrastructure. Each has a clear, narrow contract. None leaks into the others.

***

### 3. Concrete Interface Proposal

#### Layer 2 — Event Classifier

```typescript
// packages/core/src/classifier.ts

export type EventDomain = 'github' | 'linear' | 'slack' | 'generic';

export type GitHubEventType =
  | 'pull_request'
  | 'push'
  | 'issue'
  | 'issue_comment'
  | 'pull_request_review'
  | 'check_run'
  | 'deployment';

export type LinearEventType = 'Issue' | 'Comment' | 'Project' | 'Cycle';

// Typed, normalized GitHub PR payload — no more Record<string, unknown> casting
export interface GitHubPRData {
  number: number;
  title: string;
  url: string;
  author: string;
  authorType: 'user' | 'bot';     // detect dependabot, renovate, etc.
  base: string;
  head: string;
  body: string;
  draft: boolean;
  labels: string[];
  repoFullName: string;           // 'acme/frontend' — the critical routing key
  repoDefaultBranch: string;
  installationId?: string;        // for per-repo GitHub App auth
  orgLogin: string;               // 'acme'
}

export interface GitHubPushData {
  repoFullName: string;
  ref: string;
  branch: string;
  pusher: string;
  commitCount: number;
  compareUrl: string;
  installationId?: string;
}

export interface LinearIssueData {
  id: string;
  title: string;
  description: string;
  teamKey: string;                // 'HAR' — the critical routing key
  projectId?: string;
  priority: number;
  assigneeId?: string;
  workspaceId: string;
}

export interface ClassifiedEvent<T = unknown> {
  raw: WebhookEvent;              // always available for fallback
  domain: EventDomain;
  type: string;                   // 'pull_request', 'Issue', etc.
  action: string;                 // 'opened', 'create', 'synchronize'
  qualifiedName: string;          // 'pull_request.opened' — the current event string
  data: T;                        // typed normalized payload
  receivedAt: Date;
}

export interface EventClassifier {
  /**
   * Classify a raw webhook event into a typed, normalized form.
   * Returns null if the event is unrecognized or malformed.
   */
  classify(event: WebhookEvent): ClassifiedEvent | null;
}
```

**Why this matters**: `ClassifiedEvent<GitHubPRData>` has `.data.repoFullName` as a typed string. There is no more `event.payload.repository?.full_name as string` scattered across the codebase. The classifier owns all the payload-parsing risk in one place.

***

#### Layer 3 — Project Router

```typescript
// packages/core/src/project.ts

export interface ProjectContext {
  // Identity
  domain: EventDomain;
  org?: string;                   // 'acme'
  repo?: string;                  // 'frontend'
  repoFullName?: string;          // 'acme/frontend'
  repoCloneUrl?: string;          // for git operations in context builder
  defaultBranch?: string;

  // Linear
  teamKey?: string;               // 'HAR'
  linearWorkspaceId?: string;

  // Auth
  installationId?: string;        // GitHub App installation for this repo
  tokenRef?: string;              // secret reference for API calls

  // Metadata
  tags?: string[];                // inherited from bento.yaml project config
}

export interface ProjectRouter {
  /**
   * Extract project scope from a classified event.
   * Never throws — returns a partial context if info is unavailable.
   */
  extractProject(event: ClassifiedEvent): ProjectContext;
}
```

**Why this matters**: `assembleContext()` currently receives a `WebhookEvent` and must do `event.payload.repository as Record<string,unknown>` before it can fetch git history. With `ProjectContext`, the context builder receives `project.repoCloneUrl` directly. The two stubs become implementable immediately.

***

#### Layer 4 — Pipeline Matcher (replaces `matchPipelines()`)

```typescript
// services/daemon/src/matcher.ts

// Extended trigger config (backwards compatible)
export interface PipelineTriggerFilter {
  repos?: string[];               // ['acme/frontend', 'acme/*'] — glob patterns
  branches?: string[];            // ['main', 'release/*']
  authors?: string[];             // ['!dependabot[bot]'] — '!' prefix = exclude
  labels?: string[];              // PR must have at least one of these
  draft?: boolean;                // true = only drafts, false = only non-drafts
  teams?: string[];               // Linear team keys: ['HAR', 'ENG']
}

// This extends PipelineConfig.trigger — no breaking change
export interface PipelineTriggerV2 extends PipelineTrigger {
  filter?: PipelineTriggerFilter;
}

export interface MatchedPipeline {
  name: string;
  config: PipelineConfig;
  agent: DiscoveredAgent;         // resolved here — executor never looks up by name again
  project: ProjectContext;
  matchScore: number;             // higher = more specific match (repo-filter beats no-filter)
}

export interface PipelineMatcher {
  /**
   * Find all pipelines that match this event and project context.
   * Returns matches sorted by specificity (most specific first).
   */
  match(
    event: ClassifiedEvent,
    project: ProjectContext,
    pipelines: Record<string, PipelineConfig>,
    agents: Map<string, DiscoveredAgent>,
  ): MatchedPipeline[];
}
```

**Match scoring example**: A pipeline with `filter.repos: ['acme/payments']` scores higher than one with no filter when the event comes from `acme/payments`. This prevents a "catch-all" pipeline from shadowing a specialized one, and makes the tie-breaking rule explicit rather than dependent on YAML ordering.

***

#### Layer 5 — Context Builder (replaces `assembleContext()`)

```typescript
// services/daemon/src/context.ts (enhanced)

export interface ContextBuilderOptions {
  pipeline: PipelineConfig;
  event: ClassifiedEvent;
  project: ProjectContext;
  logger: Logger;
}

export interface EnrichedContext {
  // Existing
  summary: string;
  sections: ContextSection[];

  // New — available to executor for prompt rendering
  project: ProjectContext;

  // Structured event data for typed template vars (not just payload paths)
  eventData: Record<string, unknown>;
}

export interface ContextBuilder {
  /**
   * Assemble context for a pipeline run.
   * Receives typed event + project — no payload-parsing needed here.
   */
  assemble(options: ContextBuilderOptions): Promise<EnrichedContext>;
}
```

**Why event-aware context building is necessary**: Git history for a PR requires:

1. Repo clone URL (`project.repoCloneUrl`) — from Layer 3
2. PR head SHA (`event.data.head` for GitHub) — from Layer 2
3. Auth token (`project.installationId`) — from Layer 3

None of these were available before this refactor. Context building was *fundamentally blocked* by the flat architecture. With these layers, `gatherGitHistory()` becomes:

```typescript
async function gatherGitHistory(
  event: ClassifiedEvent<GitHubPRData>,
  project: ProjectContext,
): Promise<string | null> {
  if (!project.repoCloneUrl) return null;
  const token = await resolveInstallationToken(project.installationId);
  // git log --oneline -20 HEAD..event.data.head
  // now actually implementable
}
```

***

### 4. How Multi-Project Support Works End-to-End

With these layers, `bento.yaml` can express per-repo pipelines without duplication:

```yaml
pipelines:
  # Catches all PRs — low specificity
  pr-review-default:
    trigger:
      github: [pull_request.opened, pull_request.synchronize]
    agent: reviewer
    prompt: "Review this PR..."

  # Catches only payments/ PRs — higher specificity, wins over default
  pr-review-payments:
    trigger:
      github: [pull_request.opened, pull_request.synchronize]
      filter:
        repos: ['acme/payments']
        branches: ['main']
    agent: security-reviewer      # different agent
    prompt: "Review this payment-service PR with security focus..."

  # Only non-bot PRs on frontend, targeting main
  pr-review-frontend:
    trigger:
      github: [pull_request.opened]
      filter:
        repos: ['acme/frontend']
        authors: ['!dependabot[bot]', '!renovate[bot]']
        draft: false
    agent: reviewer
    context:
      git_history: true           # now actually works via ProjectContext
```

The `PipelineMatcher` scores `pr-review-payments` above `pr-review-default` for `acme/payments` events because its filter is more specific. The correct agent is resolved at match time and passed to the executor — no secondary lookup.

***

### 5. The Abstraction Boundary

The critical boundary is between **Layers 4 and 5** — between *matching* and *context building*.

**Matching** (Layers 1–4) must be:

* Cheap — runs for every event, most will not match
* Stateless — no I/O, no API calls
* Deterministic — same event always produces the same matches

**Context building** (Layer 5) must be:

* Rich — fetch git history, query APIs, recall sessions
* Event-type-aware — PRs need diff context, issues need related ticket context
* Project-scope-aware — needs repo URL, auth tokens, branch info

The current code blurs this boundary: `handleEvent()` calls `matchPipelines()` (cheap), then immediately calls `assembleContext()` (expensive, I/O-bound) — and passes the same untyped `WebhookEvent` to both. The expensive work can't use the information it needs because that information was never extracted from the event at the matching stage.

The clean rule: **anything that requires I/O lives in Layer 5 and below. Anything that only reads the event lives in Layer 4 and above.**

***

### 6. What Does Not Change

* `WebhookEvent` interface — Layer 2 wraps it, not replaces it
* `WebhookServer` — still parses and emits `WebhookEvent`
* `PipelineQueue` / `executePipeline()` — executor is clean, unchanged
* `DiscoveredAgent` / `discoverAgents()` — SOUL.md discovery is fine
* `bento.yaml` structure — the existing pipeline format is valid; `filter` is additive
* All existing tests — `matchPipelines()` behavior is preserved for trigger-only pipelines

The refactor is additive. Layer 2 and 3 are new files. Layer 4 is a replacement for the 12-line `matchPipelines()` method. Layer 5 is an enhancement to the existing `assembleContext()` signature. Nothing is deleted until the old code can be shadowed by the new.

***

### 7. Summary

| Failing scenario                       | Root cause in current code            | Resolved by layer        |
| -------------------------------------- | ------------------------------------- | ------------------------ |
| Two repos, different agents            | `matchPipelines()` ignores payload    | Layer 3 + Layer 4 filter |
| Git history is always null             | `assembleContext()` lacks repo URL    | Layer 3 → Layer 5        |
| Adding Slack breaks 3 files            | Domain logic split across files       | Layer 2 classifier       |
| Can't exclude bots from triggers       | No filter clause in `PipelineTrigger` | Layer 4 filter schema    |
| Agent can't vary by repo               | `agent` is a static string field      | Layer 4 match scoring    |
| Prompt template can't use typed fields | `renderPrompt` only walks raw payload | Layer 5 `eventData`      |

The layered architecture does not make the code more complex. It makes the current hidden complexity explicit, gives each concern a named owner, and unblocks the features — git history, multi-repo routing, per-repo agents — that are already stubbed out or missing from the codebase.


## MCP Protocol Surface

### Overview

The daemon currently exposes itself over MCP as a thin RPC layer: a handful of tools (`create_workload`, `submit_invocation`, `get_invocation`, `cancel_invocation`, `close_workload`) plus agent and skill descriptors as resources. This is a **CLI-shaped MCP server** — every interaction is a request/response tool call, and the host has to poll to observe long-running work.

That's a fraction of what the protocol gives us. MCP is a *session* in which the server is a peer that can hold state, push updates, prompt the user directly, and call back into the host's model. For a system whose core primitive is **remote skill execution in a sandbox**, those affordances aren't decorative — they map onto things we already need.

This document is a roadmap for the protocol surface we want, ranked by leverage. Concrete shape, not implementation order; sequencing is the last section.

### Where we are today

Current MCP exposure (see `services/daemon/src/mcp/`):

* **Tools**: `create_workload`, `submit_invocation`, `get_invocation`, `list_invocations`, `cancel_invocation`, `close_workload`, `list_workloads`. Sync request/response over the wire.
* **Resources**: each agent (`agent://reviewer`, `agent://ghostwriter`) and skill (`skill://review-repo`, etc.) is exposed read-only as a markdown resource. Discovery works; no subscriptions, no parameterization.
* **Prompts, sampling, elicitation, progress, roots, completion**: unused.

The polling loop is the most visible cost. A skill that takes 90 seconds becomes 10–30 `get_invocation` tool calls from the host, each consuming context budget.

### The richer surface

#### Tier 1 — architectural shifts

##### Sampling — skills borrow the host's brain

Today, a skill that needs an LLM mid-execution either ships its own model credentials or doesn't use one. Sampling inverts this: the skill, mid-run, asks the daemon to call back into the *host's* LLM via `sampling/createMessage`. The host's model, the host's quota, the daemon orchestrating.

Why it matters:

* `review-repo`, `address-pr-comments`, `ghostwriter` all bake in a model today. They shouldn't have to.
* Skills become model-agnostic and portable across hosts (Claude Code, Cursor, Zed, custom).
* Eliminates a class of secret-management problem (no per-skill API keys).
* Cost attribution moves to the user invoking the skill, which is the right place for it.

Caveat: not every host implements sampling. Claude Desktop does; Code support is uneven. Plan for fallback to the skill's configured runtime when sampling isn't available.

##### Elicitation — structured human-in-the-loop

`address-pr-comments` is already a gated loop: for each comment the user picks `apply / wontfix / defer / discuss`. Right now this is implemented by round-tripping through tool results and prompt-engineered text. With elicitation, the daemon directly issues `elicitation/create` to the host with a JSON schema, and the host renders a typed form. The pause-and-ask becomes a first-class protocol move, not emergent behavior.

Skills that benefit:

* `address-pr-comments` — the per-comment decision
* `create-draft` — inline edits/approvals
* Any new "review and confirm" pattern (deploys, migrations, destructive ops)

##### Sandbox-as-URI-namespace via subscribable resources

Every observable inside a sandboxed workload becomes a resource:

```
workload://{id}                          # high-level state
workload://{id}/status                   # subscribable
workload://{id}/logs                     # subscribable, tail in real time
workload://{id}/invocations              # list
workload://{id}/invocations/{iid}        # invocation state, subscribable
workload://{id}/invocations/{iid}/result # produced artifact
workload://{id}/fs/{path}                # sandbox filesystem, lazy read
workload://{id}/artifacts/{name}         # named outputs
```

Clients call `resources/subscribe`; the daemon emits `notifications/resources/updated` as state changes. The host stops polling, the agent stops burning tokens watching, the user gets live state. This is the model the spec wants us in.

Resource templates make the URI shape discoverable:

```ts
{
  uriTemplate: "workload://{workload_id}/invocations/{invocation_id}",
  name: "Invocation state",
  mimeType: "application/json"
}
```

#### Tier 2 — clear wins, smaller surface

##### Prompts as the user-facing skill surface

Tools are for things the *agent* should decide to invoke. Prompts are for things the *user* should be able to invoke. Skills are mostly the latter.

Today: `submit_invocation(skill="review-repo", payload="...")` — the agent has to know to call this tool and how to shape the payload.

With prompts: each skill exposes itself via `prompts/list` with typed arguments:

```ts
{
  name: "review-repo",
  description: "Review a repository...",
  arguments: [
    { name: "url",   description: "Repo URL or local path", required: true },
    { name: "focus", description: "Optional focus area",     required: false }
  ]
}
```

The host surfaces `/review-repo {url} {focus?}` as a slash command. Same execution path underneath; vastly better discoverability. Tools stay for things like `cancel_invocation` that the agent should reach for autonomously.

##### Progress notifications

Long-running skills emit `notifications/progress` with `progressToken` against the originating request. `step 3/7: cloning repo…` flows to the host UI natively. Free UX, no protocol gymnastics.

##### Cancellation propagation

When the host issues `notifications/cancelled` for an in-flight request, the daemon must SIGTERM the sandbox process, mark the workload's invocation `cancelled`, and clean up. Today, hitting Esc in the host probably leaves the runtime running until TTL or natural completion.

##### Resource links in tool results

When a skill finishes, return a `resource_link` to `workload://{id}/invocations/{iid}/result` instead of inlining the artifact. Hosts that support it render inline; ones that don't follow the link. Cheaper on the wire, and the result stays addressable for re-fetching later (e.g. by another skill in the same workload).

#### Tier 3 — speculative but fun

##### MCP UI for a workload dashboard

A `ui://workloads` resource (HTML in the `mcp-app` profile) renders a live dashboard inside the host's iframe: active workloads, queue depth, recent results, log tails. Far more useful than text when 5 things are running. Already in the wild — Slack and Excalidraw both ship `ui://` resources we can study.

##### Roots → sandbox mounts

Hosts declare workspace roots via `roots/list`. The daemon uses those to decide what the sandbox is allowed to see at mount time. Roots become the bridge between "what the user is working on in their editor" and "what the sandbox filesystem boundary exposes."

##### Argument completion

`completion/complete` for skill prompt arguments — repo URLs, ticket IDs, PR numbers. Pulled from the daemon's KB or recent workload history. Makes prompts feel like real CLI commands with tab-completion.

### Mapping to daemon concepts

Cross-referencing [`workload-architecture.md`](./workload-architecture):

| Daemon concept               | Current MCP shape                                               | Richer MCP shape                                                                                                                  |
| ---------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Workload                     | Created by `create_workload` tool, observed by `list_workloads` | `workload://{id}` resource (subscribable). Created by tool, observed via subscription.                                            |
| Invocation                   | Submitted by `submit_invocation`, polled via `get_invocation`   | Submitted by tool *or* prompt invocation. Observed via `workload://{id}/invocations/{iid}` subscription + progress notifications. |
| Skill                        | `skill://{name}` markdown resource                              | Same resource + prompt entry with typed args + (optional) sampling client during execution.                                       |
| Agent                        | `agent://{name}` markdown resource                              | Same. Agents are persona configs; they don't need their own protocol surface.                                                     |
| Result                       | Returned in `get_invocation` payload                            | `resource_link` to `workload://{id}/invocations/{iid}/result`. Re-fetchable, embeddable.                                          |
| User decision point in skill | Prompt-engineered text in tool result                           | `elicitation/create` with JSON schema.                                                                                            |
| Skill log line               | Not exposed                                                     | Resource update on `workload://{id}/invocations/{iid}/logs`.                                                                      |
| Cancellation                 | `cancel_invocation` tool                                        | Same tool *plus* `notifications/cancelled` honored.                                                                               |

### Sequencing

Build order, by dependency and leverage:

1. **Subscribable workload/invocation resources + progress notifications.** Smallest change, biggest UX delta. Foundation for everything else (logs, artifacts, sandbox-as-namespace). No host-support concerns — resources and progress are widely supported.
2. **Resource links in invocation results + log resources.** Falls out of (1). Makes results addressable.
3. **Cancellation propagation.** Plumbing fix, not a new surface, but it's a correctness gap and the resources from (1) make verification easy.
4. **Prompts for skills.** User-facing win. Doesn't disturb existing tool callers (the tool API remains for agentic invocation).
5. **Elicitation.** Refactor `address-pr-comments` first as the proving ground. Other gated skills follow.
6. **Sampling.** Highest ceiling but largest unknowns — host coverage, fallback behavior, cost attribution UX. Pilot on one skill (`ghostwriter` is a good candidate: small, LLM-only, no sandbox integration).
7. **MCP UI dashboard, roots, completion.** Polish layer. Tackle once the core surface is stable.

### Non-goals

* We are not redesigning the underlying workload/invocation/skill model. The MCP surface is a *projection* of those concepts; the internal model in `services/daemon` stays as designed in `workload-architecture.md`.
* We are not committing to support every MCP host equally. Sampling and elicitation degrade gracefully where unsupported; the tool-based fallback path stays functional.
* We are not exposing raw sandbox shell access as a resource. `workload://{id}/fs/{path}` is read-only and scoped; mutations go through skills.


## Prompt Composition

How bento assembles the prompt an agent receives — which file or mechanism owns which part, and which message channel each part lands in.

Every agent invocation runs against a composed prompt. It is not written in one place: it is layered from operator-authored files and bento-injected blocks, then split across two channels — the **system** message and the **user** message. Keeping the layers separate is what lets one agent serve multiple pipelines without its instructions contradicting the task.

### Who controls each layer

Three parties contribute, and the dividing line is **control**, not file format:

* **The runtime** — the agent CLI (`claude`, `pi`, `codex`) ships its own base system prompt and tool set. bento does not author this; it is the floor everything else sits on.
* **bento** — injects the operating brief, the notes protocol, and the per-run fact blocks. These are derived from what bento itself provides (the sandbox, the checked-out workspace, the notes mechanism), so only bento can assert them. Not operator-editable.
* **The operator** — authors the persona, the procedure, and the task. This is the configurable surface.

### The layers

| Layer           | Source                                                          | Channel | Controlled by | Varies per       |
| --------------- | --------------------------------------------------------------- | ------- | ------------- | ---------------- |
| Runtime harness | the agent CLI                                                   | system  | runtime       | runtime          |
| Operating brief | bento-injected                                                  | system  | bento         | nothing — stable |
| Notes protocol  | bento-injected (`<notes-protocol>`)                             | system  | bento         | nothing — stable |
| Persona         | `agents/<name>/SOUL.md`                                         | system  | operator      | agent            |
| Procedure       | `skills/<name>/SKILL.md`                                        | system  | operator      | skill            |
| Task            | `pipelines.<name>.prompt` (`bento.yaml`)                        | user    | operator      | pipeline + event |
| Per-run facts   | bento-injected (`<context-sources>`, `<prior-runs>`, `<notes>`) | user    | bento         | run              |

### Channels: system vs user

The model API has two message roles, and they are not interchangeable.

* **System** carries identity and standing rules — stable across every turn of a run. Prompt caching matches a prefix, so stable content placed here is cached: a 24-turn run re-sends the system prompt 24 times but pays full price only once.
* **User** carries the task and its per-run data — necessarily variable, so it must sit *after* the cached prefix or it would bust the cache for everything before it.

This is the recurring split: a stable **contract** goes in the system channel; the matching per-run **fact** goes in the user channel.

* The operating brief (stable rule about the sandbox) is a system fragment; `<context-sources>` (this run's specific commit SHA) is a user fragment.
* The notes *protocol* (the constant convention for recording durable signals) is a system fragment; the accumulated `<notes>` (what prior runs actually recorded) is a user fragment.

Within the system channel the order is **operating brief → notes protocol → persona → procedure**. The bento-injected blocks (operating brief, notes protocol) are byte-identical across every agent, so leading with them lets all agents share that cached prefix.

### The composition rule

**Each layer is independent of the layers it composes with.**

* `SOUL.md` never names a skill, an output format, or a trigger type.
* `SKILL.md` never assumes a particular agent's voice.
* Neither names a pipeline.

A layer that violates this cannot be reused. If `SOUL.md` hard-codes "you are invoked when someone leaves a review comment", any pipeline that is *not* a review-comment pipeline inherits a system prompt that lies about the task.

### How it is assembled

`assemblePrompt` (`services/daemon/src/pipelines/prompt-assembly.ts`) does not hard-code which content goes to which channel. Each contributing block is a fragment that carries its own channel tag:

```ts
interface PromptFragment {
  channel: 'system' | 'user'
  text: string
}
```

`compose` then groups fragments by channel and joins each — it makes no placement decision. Moving a block between channels is a one-line retag where the fragment is built, not a rewrite of the assembler.

### Worked example: the reviewer

The `reviewer` agent is used by more than one pipeline — a whole-PR merge-readiness review and a single-comment reply. One persona, two procedures:

* `agents/reviewer/SOUL.md` — *"You are Reviewer. You read code critically, cite specifics, do not hedge, do not apologise for the author. Read-only."* Voice and standards only. Nothing about comments, diff hunks, or output formats.
* `skills/review/SKILL.md` — whole-PR procedure: read the checked-out repo, assess merge readiness, post a GitHub review with inline comments, end with a verdict.
* `skills/pr-comment-review/SKILL.md` — comment procedure: evaluate the comment against `HEAD`, form a position, emit the structured reply that `output: review_comment_reply` consumes.
* pipeline `prompt:` — *"Review PR #24 … produce APPROVE / REQUEST\_CHANGES / HOLD."*

The skill differentiates whole-PR review from comment-reply. Because the persona is scenario-free, one `reviewer` agent serves both — no need for a separate agent per pipeline.

### Why output contracts belong to the skill

A structured-JSON output requirement exists because a *pipeline* declares `output: review_comment_reply` — it is a property of that procedure, not of the agent's character. It belongs in the **skill**, not in `SOUL.md`. If the output contract lived in the persona, every pipeline using that agent would inherit it, including the ones that want a plain prose verdict.

The test for any instruction: if it would still be true for the same agent running a *different* kind of task, it is persona — put it in `SOUL.md`. If it changes with the task, it is procedure — put it in the skill, or in the pipeline prompt.


## Runtime Wrapper

Standardised metric collection across pi, claude, and codex runtimes.

Each runtime emits structured JSONL when invoked in non-interactive mode, but with different event schemas. The runtime wrapper normalises these into a common `SessionResult` type (defined in `packages/core/src/runtime.ts`) so the daemon, skill-evolve, and any other consumer can work uniformly.

### Interfaces

See `packages/core/src/runtime.ts` for the full TypeScript types.

The key types:

* **`SessionResult`** — the main output: usage, cost, tool calls, file operations, turns, status
* **`RuntimeAdapter`** — interface each runtime implements: `parse(lines, meta) → SessionResult`
* **`TokenUsage`** / **`CostBreakdown`** — normalised token and cost accounting
* **`ToolCall`** — name, args, result, status, duration
* **`Turn`** — one model round-trip with per-turn usage breakdown

### Invocation Modes

| Runtime | Command                          | Output mode flag                                                              | Event format                                        |
| ------- | -------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- |
| pi      | `pi -p`                          | `--mode json`                                                                 | Newline-delimited JSON events                       |
| claude  | `claude -p`                      | `--output-format json` (summary) or `--output-format stream-json` (streaming) | Single JSON object or newline-delimited JSON events |
| codex   | `codex exec --experimental-json` | Built-in                                                                      | Newline-delimited JSON events                       |

### Event Schemas

#### Pi (`--mode json`)

Pi emits a rich event stream with lifecycle events and per-message usage:

```
{type: "session", version, id, timestamp, cwd}
{type: "agent_start"}
{type: "turn_start"}
{type: "message_start", message: {role: "user", content: [...]}}
{type: "message_end",   message: {role: "user", content: [...]}}
{type: "message_start", message: {role: "assistant", content: [...], model, usage, stopReason}}
  ... message_update events (text deltas) ...
{type: "message_end",   message: {role: "assistant", ..., usage: {input, output, cacheRead, cacheWrite, totalTokens, cost: {input, output, cacheRead, cacheWrite, total}}}}
{type: "tool_execution_start", toolCallId, toolName, args}
{type: "tool_execution_end",   toolCallId, toolName, result, isError}
{type: "message_start", message: {role: "toolResult", content: [...]}}
{type: "message_end",   message: {role: "toolResult", ...}}
{type: "turn_end", message: {role: "assistant", ..., usage}, toolResults: [...]}
{type: "agent_end", messages: [...]}
```

**Key fields for metric extraction:**

| Metric             | Location                                                  |
| ------------------ | --------------------------------------------------------- |
| Session ID         | `session.id`                                              |
| Model              | `message.model` (on assistant messages)                   |
| Input tokens       | `message.usage.input`                                     |
| Output tokens      | `message.usage.output`                                    |
| Cache read tokens  | `message.usage.cacheRead`                                 |
| Cache write tokens | `message.usage.cacheWrite`                                |
| Total tokens       | `message.usage.totalTokens`                               |
| Cost (total)       | `message.usage.cost.total`                                |
| Cost (breakdown)   | `message.usage.cost.{input,output,cacheRead,cacheWrite}`  |
| Stop reason        | `message.stopReason`                                      |
| Tool name          | `tool_execution_start.toolName`                           |
| Tool args          | `tool_execution_start.args`                               |
| Tool result        | `tool_execution_end.result`                               |
| Tool error         | `tool_execution_end.isError`                              |
| Turns              | Count `turn_start` / `turn_end` pairs                     |
| Text output        | Concatenate `text` content blocks from assistant messages |

#### Claude (`--output-format json`)

Claude's JSON mode returns a single summary object after completion:

```json
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 2956,
  "duration_api_ms": 2890,
  "num_turns": 1,
  "result": "Hello!",
  "stop_reason": "end_turn",
  "session_id": "...",
  "total_cost_usd": 0.07,
  "usage": {
    "input_tokens": 5,
    "output_tokens": 8,
    "cache_creation_input_tokens": 9984,
    "cache_read_input_tokens": 14857,
    "server_tool_use": {"web_search_requests": 0}
  },
  "modelUsage": {
    "claude-opus-4-7[1m]": {
      "inputTokens": 5,
      "outputTokens": 8,
      "cacheReadInputTokens": 14857,
      "cacheCreationInputTokens": 9984,
      "costUSD": 0.07
    }
  }
}
```

**Key fields for metric extraction:**

| Metric             | Location                                                  |
| ------------------ | --------------------------------------------------------- |
| Session ID         | `session_id`                                              |
| Model              | First key in `modelUsage`                                 |
| Input tokens       | `usage.input_tokens`                                      |
| Output tokens      | `usage.output_tokens`                                     |
| Cache read tokens  | `usage.cache_read_input_tokens`                           |
| Cache write tokens | `usage.cache_creation_input_tokens`                       |
| Cost (total)       | `total_cost_usd`                                          |
| Cost (per-model)   | `modelUsage[model].costUSD`                               |
| Duration           | `duration_ms`                                             |
| API duration       | `duration_api_ms`                                         |
| Turns              | `num_turns`                                               |
| Stop reason        | `stop_reason`                                             |
| Text output        | `result`                                                  |
| Tool calls         | Not in JSON mode — need `stream-json` for per-tool detail |

**Note:** Claude's `--output-format json` gives aggregated metrics only. For per-tool-call detail (what meta-harness uses), `--output-format stream-json` emits per-event JSONL with `assistant` and `user` (tool\_result) events, similar to the Anthropic Messages API format.

#### Claude (`--output-format stream-json`)

Streaming mode emits events matching the Anthropic Messages API shape:

```
{type: "system", ...}
{type: "assistant", message: {content: [{type: "text", text: "..."} | {type: "tool_use", id, name, input}], usage: {input_tokens, output_tokens, ...}}}
{type: "user", message: {content: [{type: "tool_result", tool_use_id, content, is_error}]}}
{type: "result", session_id, total_cost_usd, usage: {...}}
```

This is richer than JSON mode — each assistant message has individual content blocks that can be `text` or `tool_use`, and the following `user` message carries the `tool_result`. The final `result` event has the summary.

#### Codex (`exec --experimental-json`)

Codex uses a thread/item model via its TypeScript SDK:

```
{type: "thread.started", thread_id: "..."}
{type: "turn.started"}
{type: "item.started", item: {id, type: "agent_message" | "command_execution" | "file_change" | "mcp_tool_call" | ...}}
{type: "item.updated", item: {...}}
{type: "item.completed", item: {...}}
{type: "turn.completed", usage: {input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens}}
```

**Item types (from codex SDK `items.ts`):**

| Item type           | Description         | Key fields                                                 |
| ------------------- | ------------------- | ---------------------------------------------------------- |
| `agent_message`     | Text response       | `text`                                                     |
| `reasoning`         | Chain-of-thought    | `text`                                                     |
| `command_execution` | Shell command       | `command`, `aggregated_output`, `exit_code`, `status`      |
| `file_change`       | File patch          | `changes: [{path, kind}]`, `status`                        |
| `mcp_tool_call`     | MCP tool invocation | `server`, `tool`, `arguments`, `result`, `error`, `status` |
| `web_search`        | Web search          | `query`                                                    |
| `todo_list`         | Agent's task list   | `items: [{text, completed}]`                               |
| `error`             | Non-fatal error     | `message`                                                  |

**Key fields for metric extraction:**

| Metric           | Location                                                                        |
| ---------------- | ------------------------------------------------------------------------------- |
| Session ID       | `thread.started.thread_id`                                                      |
| Model            | Not in events (passed as config)                                                |
| Input tokens     | `turn.completed.usage.input_tokens`                                             |
| Output tokens    | `turn.completed.usage.output_tokens`                                            |
| Cache tokens     | `turn.completed.usage.cached_input_tokens`                                      |
| Reasoning tokens | `turn.completed.usage.reasoning_output_tokens`                                  |
| Cost             | Not in events (must compute from token counts + pricing)                        |
| Turns            | Count `turn.started` / `turn.completed` pairs                                   |
| Stop reason      | Infer from last event type                                                      |
| Tool calls       | `item.completed` where `item.type === "command_execution"` or `"mcp_tool_call"` |
| File changes     | `item.completed` where `item.type === "file_change"`                            |
| Text output      | Concatenate `item.completed` where `item.type === "agent_message"`              |

**Codex gaps:**

* No cost data in events — must be computed externally from token counts and model pricing
* No explicit model field in events — passed as config, not echoed back
* `reasoning_output_tokens` is a distinct field (OpenAI counts reasoning separately)

### Field Mapping Summary

How each runtime field maps to the common `SessionResult`:

| SessionResult field | Pi                              | Claude (json)                       | Codex                                            |
| ------------------- | ------------------------------- | ----------------------------------- | ------------------------------------------------ |
| `sessionId`         | `session.id`                    | `session_id`                        | `thread.started.thread_id`                       |
| `model`             | `message.model`                 | `modelUsage` key                    | config input                                     |
| `status`            | infer from `agent_end`          | `subtype`                           | infer from exit                                  |
| `exitCode`          | process exit                    | process exit                        | process exit                                     |
| `usage.input`       | Σ `message.usage.input`         | `usage.input_tokens`                | Σ `turn.completed.usage.input_tokens`            |
| `usage.output`      | Σ `message.usage.output`        | `usage.output_tokens`               | Σ `turn.completed.usage.output_tokens`           |
| `usage.cacheRead`   | Σ `message.usage.cacheRead`     | `usage.cache_read_input_tokens`     | Σ `turn.completed.usage.cached_input_tokens`     |
| `usage.cacheWrite`  | Σ `message.usage.cacheWrite`    | `usage.cache_creation_input_tokens` | —                                                |
| `usage.reasoning`   | —                               | —                                   | Σ `turn.completed.usage.reasoning_output_tokens` |
| `cost.total`        | last `message.usage.cost.total` | `total_cost_usd`                    | computed                                         |
| `durationMs`        | compute from timestamps         | `duration_ms`                       | compute from timestamps                          |
| `turns`             | count `turn_end` events         | `num_turns`                         | count `turn.completed` events                    |
| `toolCalls`         | `tool_execution_{start,end}`    | stream-json `tool_use` blocks       | `command_execution` + `mcp_tool_call` items      |
| `fileChanges`       | infer from tool args            | infer from tool args                | `file_change` items (native)                     |
| `text`              | assistant text blocks           | `result`                            | `agent_message` items                            |

### Implementation Plan

Each runtime gets an adapter that implements `RuntimeAdapter`:

```
packages/core/src/
  runtime.ts          ← interfaces (done)
  adapters/
    pi.ts             ← parses pi --mode json output
    claude.ts         ← parses claude --output-format json (or stream-json)
    codex.ts          ← parses codex exec --experimental-json output
```

The daemon's `executePipeline` currently does raw `Bun.spawn` → `stdout.log`. It would instead:

1. Spawn the runtime with the appropriate JSON output flag
2. Collect JSONL lines
3. Pass them through the runtime's adapter → `SessionResult`
4. Store the `SessionResult` for querying, logging, and skill-evolve

### References

* [Pi source](https://github.com/nichochar/pi) — `--mode json` event format
* [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code) — `--output-format` options
* [Codex SDK](https://github.com/openai/codex/tree/main/sdk/typescript) — `events.ts` and `items.ts` type definitions
* [Meta-Harness claude\_wrapper.py](https://github.com/stanford-iris-lab/meta-harness) — reference for stream-json parsing
* `packages/core/src/runtime.ts` — the interfaces
* [`docs/skill-evolve.md`](./skill-evolve) — primary consumer of session metrics


## Skill Evolve

Automated improvement of bento skills and agent prompts using session history as training signal.

Inspired by [Meta-Harness](https://github.com/stanford-iris-lab/meta-harness) (Stanford IRIS Lab) — which searches over model harnesses by proposing candidates, benchmarking them, and tracking a Pareto frontier. We apply the same pattern to our own skills and agent definitions, using real session logs as the evaluation dataset.

### The Idea

Skills (SKILL.md) and agent souls (SOUL.md) are hand-written today. They encode operational knowledge — how to review a repo, how to do a PR review, how to structure context for a project. But they're static. They don't learn from whether sessions using them actually went well.

Skill-evolve closes this loop:

```
Sessions happen → logs accumulate → evaluate outcomes →
propose skill improvements → validate offline → promote winners
```

The "dataset" is session JSONL files. The "harness" is skill/agent definitions. The "evaluator" is whether improved skills would have produced better outcomes on past sessions. The "proposer" is a Claude Code session that reads failure patterns and drafts improvements.

### Architecture

```
┌─────────────────────────────────────────────────┐
│                  Cron (weekly)                   │
│                                                  │
│  1. Collect    session logs from ~/.pi/sessions  │
│  2. Evaluate   score sessions by outcome signal  │
│  3. Analyze    identify failure patterns          │
│  4. Propose    generate skill candidates          │
│  5. Validate   test candidates against held-out   │
│  6. Promote    update frontier, notify            │
└─────────────────────────────────────────────────┘
         │                          │
         ▼                          ▼
   evolution_summary.jsonl    frontier_skills.json
```

#### Step 1: Collect

Gather session logs from the past period. Each session JSONL contains the full conversation: user messages, assistant responses, tool calls, tool results, errors. Filter to sessions that used a specific skill or agent.

#### Step 2: Evaluate

Score each session. The outcome signal could be:

* **Completion** — did the session reach its goal? (heuristic: did the user say "thanks", approve a PR, or move on to a new topic without frustration?)
* **Efficiency** — tool call count, token usage, number of correction cycles ("no not that", "try again")
* **Error rate** — how many tool calls failed, how many retries
* **User corrections** — explicit feedback like "don't do X" or "that's wrong"

This is the hardest part. Unlike meta-harness's text classification accuracy or terminal-bench pass rate, our signal is noisy and subjective. Early versions should use simple heuristics; later versions can use an LLM-as-judge.

#### Step 3: Analyze

A proposer session reads:

* `evolution_summary.jsonl` — what skill variants have been tried, what worked
* `frontier_skills.json` — current best skill versions
* Session logs with low scores — what went wrong?
* Session logs with high scores — what patterns should be preserved?

The proposer identifies recurring failure modes. Examples:

* "The review-repo skill doesn't tell the agent to check for monorepo workspace configs, leading to missed context in 4/12 sessions"
* "The reviewer agent keeps suggesting changes to generated files because the soul doesn't mention ignoring dist/"
* "Project context injection is missing repo branch conventions, causing agents to push to wrong branches"

#### Step 4: Propose

The proposer generates skill candidates — concrete diffs to SKILL.md or SOUL.md files. Each candidate has:

```json
{
  "name": "review-repo-v3",
  "base": "skills/review-repo/SKILL.md",
  "hypothesis": "Adding monorepo detection step will reduce missed-context errors",
  "diff_summary": "Added workspace detection step between structure and architecture sections",
  "file": "candidates/review-repo-v3/SKILL.md"
}
```

Candidates are stored in a staging area, never applied directly.

#### Step 5: Validate

Replay past sessions against candidates. For each candidate skill:

* Take N held-out sessions that used the base skill
* Run them through a simulated evaluation: "given this session's initial request and the candidate skill, would the outcome improve?"
* This can be an LLM-as-judge comparison: show both the original session trace and what the new skill would have produced, ask which is better

This is offline validation — no real sessions are affected.

#### Step 6: Promote

If a candidate beats the current frontier on held-out sessions:

* Update `frontier_skills.json`
* Append to `evolution_summary.jsonl`
* Notify via Telegram/Slack: "Skill review-repo updated: added monorepo detection (improved on 3/5 held-out sessions)"
* The actual skill file is NOT auto-updated — the human reviews and applies

### State Files

Following meta-harness conventions:

#### `evolution_summary.jsonl`

One line per evaluated candidate:

```json
{
  "iteration": 3,
  "skill": "review-repo-v3",
  "base_skill": "skills/review-repo/SKILL.md",
  "hypothesis": "Adding monorepo detection reduces missed-context errors",
  "score": 0.73,
  "delta": 0.12,
  "sessions_evaluated": 8,
  "outcome": "0.73 (+0.12)",
  "timestamp": "2026-05-02T10:00:00Z"
}
```

#### `frontier_skills.json`

Current best version of each skill:

```json
{
  "review-repo": {
    "version": "v3",
    "score": 0.73,
    "candidate_path": "candidates/review-repo-v3/SKILL.md",
    "promoted_at": "2026-05-02T10:00:00Z"
  },
  "reviewer": {
    "version": "v1",
    "score": 0.61,
    "candidate_path": null
  }
}
```

### What Gets Evolved

| Artifact        | Location                     | What changes                                 |
| --------------- | ---------------------------- | -------------------------------------------- |
| Skills          | `skills/*/SKILL.md`          | Workflow steps, anti-patterns, output format |
| Agent souls     | `agents/*/SOUL.md`           | Focus areas, tone, review criteria           |
| Project context | `~/.projects/*/project.json` | Workflow guidelines, injected instructions   |
| System prompts  | Extension-injected prompts   | Context framing, constraints                 |

### Evaluation Signals

The quality of skill-evolve depends entirely on the evaluation signal. Possible approaches, from simple to sophisticated:

#### Tier 1: Heuristic (start here)

* Session length vs task complexity (shorter is better for simple tasks)
* Number of user corrections / "no" / "try again" messages
* Tool error rate
* Whether the session ended with apparent success

#### Tier 2: LLM-as-Judge

* Show a judge model the session transcript and ask: "Rate this session 1-5 on task completion, efficiency, and user satisfaction"
* Compare two sessions side-by-side: "Which skill produced a better outcome?"

#### Tier 3: Outcome-linked

* If using Linear: did the linked issue get closed?
* If doing PR review: was the review accepted without revisions?
* If doing code changes: did CI pass on the first push?

### Constraints

* **Human in the loop.** Candidates are proposed but never auto-applied. The user reviews and promotes.
* **Anti-overfitting.** Skills must remain general-purpose. No session-specific patches. The same anti-overfitting rules from Meta-Harness apply: no hardcoded knowledge about specific repos, tasks, or users.
* **Held-out split.** Always evaluate on sessions the proposer hasn't seen. Otherwise you're just memorizing failure modes.
* **Slow cadence.** Weekly or biweekly. Skills shouldn't churn — users need stability. A skill that changes every day is worse than one that's slightly suboptimal.

### Dependencies

Before building skill-evolve, we need:

1. **runtime\_wrapper** — programmatic Claude Code / pi invocation with structured logging (adapted from meta-harness `claude_wrapper.py`)
2. **Session scoring** — even a basic heuristic scorer for session JSONL files
3. **Candidate staging** — a directory structure for skill variants that doesn't interfere with live skills

### Future: Continuous Learning

The end state is a closed loop where bento gets better at its job automatically:

```
User works with pi → sessions logged → skill-evolve runs weekly →
better skills proposed → human reviews → skills updated →
next week's sessions are better → repeat
```

This is Layer 3 of the vision (Company Brain) applied to bento itself. The system doesn't just store knowledge — it improves its own ability to apply knowledge.

### References

* [Meta-Harness paper](https://arxiv.org/abs/2603.28052) — the framework this is based on
* [Meta-Harness repo](https://github.com/stanford-iris-lab/meta-harness) — reference implementation
* [VISION.md](./vision) — how this fits into the broader bento architecture


## Company Brain

### The Problem

The biggest blocker to AI automation of companies is no longer the models. Now the blocker is the **domain knowledge**.

Every company has critical know-how scattered everywhere. Some of it lives in people's heads. Some of it is buried in old email accounts, Slack threads, support tickets, and databases. The company works because humans vaguely remember where that knowledge is and how to apply it.

But AI agents can't operate like that. If we want every company to run on AI automation, we need a new primitive: **a company brain**.

A system that pulls knowledge out of all these fragmented sources, structures it, keeps it current, and turns it into executable skills for AI. This isn't a company-wide search or a chatbot over documents. It's a living map of how a company works: how refunds get handled, how pricing exceptions are decided, how engineers respond to incidents.

Then AI systems can use that knowledge to actually do the work — safely and consistently.

The company brain becomes the missing layer between raw company data and reliable AI automation.

### The AI Operating System

The best AI-native companies have figured out something most haven't: they've made their entire company **queryable**. Every meeting recorded, every ticket tracked, every customer interaction captured — all legible to an intelligence layer that learns from it.

This turns a company from an open loop into a closed loop. In an open loop, you make a decision and maybe check the results weeks later. In a closed loop, the system monitors what's happening, compares it to what should be happening, and adjusts.

The problem is building this today requires brutal integration work — stitching together Slack, Linear, GitHub, Notion, call recordings, and a dozen other tools with custom glue code. There's no product that connects all this context into a single intelligence layer that can reason across it, flag when engineering is building the wrong thing, or generate specs agents can execute on.

The opportunity is the connective layer that makes a company legible to AI by default. Not another dashboard. The system that turns a company's own artifacts into a self-improving loop.

### How Bento Fits

> See also: [Karpathy on company-level AI](https://x.com/karpathy/status/2039805659525644595)

Bento is the first implementation of this idea, starting small and growing out.

#### Layer 1: Agent Infrastructure

A daemon that manages persistent AI agents. Process supervision, scheduling, Telegram/Slack interface. The runtime.

#### Layer 2: Context Synthesis

Every session, meeting, ticket, and conversation gets tagged and indexed. Cross-channel recall — "what do we know about auth?" pulls from Slack, Linear, GitHub, Telegram, and shared sessions. The memory.

#### Layer 3: Company Brain

Ingest from all sources — Granola meetings, CRM (Attio), email, support tickets, code reviews. Organize by project, topic, team. Surface as executable skills and queryable knowledge via MCP. The intelligence layer.

```
Sources                    Bento                        Consumers
─────────                  ───────                     ─────────
Shared sessions    ──┐                           ┌──  Claude Code
Granola meetings   ──┤     ┌───────────────┐     ├──  Codex
CRM (Attio)        ──┼────>│  Tag + Index  │────>├──  pi
Email              ──┤     └───────────────┘     ├──  Slack bot
Linear issues      ──┤        by project /       ├──  Telegram
GitHub activity    ──┘        topic / team        └──  Dashboard
```

#### The MCP Interface

The brain is exposed as an MCP server. Any developer with any MCP-compatible agent connects and gets access to the company's accumulated knowledge and skills. They don't need to install anything, learn a new tool, or change their workflow. The knowledge just shows up in their agent's toolset.

A new engineer joins, connects to the MCP server, and their agent already knows how the codebase works, what decisions were made, and what the conventions are. Not because someone wrote docs — because the system learned from everyone's work.

### Access Control

Raw knowledge ingestion is one thing. What gets served out depends on who's asking.

#### Redaction

Strip sensitive data before it enters the KB or at query time. PII, API keys, credentials, customer data. Some things should never leave bento.

#### Scoping

Not everyone sees everything. An external contractor's agent shouldn't get context from internal strategy discussions. Scope by team, project, or role.

#### Projection

Shape output for the consumer. An agent doing code review gets technical decisions and architecture context. It doesn't need CRM history or HR discussions.

```yaml
access:
  layers:
    - name: internal
      tags: [strategy, hr, finance]
      visibility: team-only

    - name: redacted
      rules:
        - strip: [api_keys, credentials, pii]
        - mask: [customer_names, revenue_figures]

    - name: public
      tags: [engineering, architecture, conventions]
      visibility: anyone

projections:
  code-review:
    include_tags: [architecture, conventions, tech-decisions]
    exclude_tags: [finance, hr]

  onboarding:
    include_tags: [architecture, conventions, team-structure, processes]
```

The MCP server is the policy enforcement point. Raw data stays on bento, consumers get a filtered view.

### Architecture Reading Order

If you're exploring how Bento is built, start here and follow this sequence:

1. **[Workload Architecture](/architecture/workload-architecture)** — core execution model: workloads, invocations, security boundary, API surface
2. **[Event Matcher](/architecture/event-matcher-layered-architecture)** — planned multi-repo routing architecture for webhook-driven pipelines
3. **[MCP Protocol Surface](/architecture/mcp-protocol-surface)** — current MCP tools + the roadmap for richer agent-to-agent interaction
4. **[Prompt Composition](/architecture/prompt-composition)** — how agent prompts are assembled from SOUL + skill + context
5. **[Runtime Wrapper](/architecture/runtime-wrapper)** — normalised metric collection across pi, claude, and codex
6. **[Skill Evolution](/architecture/skill-evolve)** — automated skill improvement via session history

### References

* [Karpathy on company-level AI](https://x.com/karpathy/status/2039805659525644595)


## Workload Architecture

:::note
**Phase 1 (Hono server) is complete.** Phases 2–6 (workload lifecycle, task submission, streaming, secret store, KB integration) are planned but not yet implemented.
:::

### Overview

The daemon evolves from a webhook-driven pipeline runner into a **remote skill execution service**. Thin clients (CLI, CI runners, other services) dial in to submit workloads. The daemon acts as a **trusted execution boundary** — it holds secrets, knowledge base access, and privileged context that clients never see.

### Core Concepts

#### Workload

A workload is the full lifecycle container: auth context, secrets, KB references, one or more tasks, and their results. It replaces the concept of a "session" (reserved for agent/runtime use).

```ts
interface Workload {
  id: string;
  client_id: string;
  scopes: string[];                  // what this workload can do
  secrets: string[];                 // secret namespaces (e.g. ["github", "linear"])
  kb: string[];                      // knowledge sources (e.g. ["security-policy", "style-guide"])
  context: Record<string, unknown>;  // accumulated state across tasks
  ttl: number;                       // workload expiry (seconds)
  created_at: string;
  status: "active" | "completed" | "expired" | "cancelled";
}
```

A workload is opened by an authenticated client, accumulates context across multiple task submissions, and is eventually closed or expires.

#### Invocation

An invocation is a single unit of work within a workload. The `agent` and/or `skill` fields name what handles it; the `payload` is opaque to the transport layer — only the agent/skill interprets it.

```ts
interface InvocationInput {
  workload_id: string;               // the workload this invocation belongs to
  agent?: string;                    // agent persona to use (optional)
  skill?: string;                    // skill procedure to follow (optional)
  payload: unknown;                  // agent/skill-specific, opaque to transport
  options?: {
    runtime?: string;                // override default runtime
    model?: string;                  // override default model
    priority?: number;
    timeout?: number;
    redact?: string[];               // additional fields to strip from output
    ephemeral?: boolean;             // don't persist result (sensitive workload)
  };
}
```

At least one of `agent` or `skill` is required. When both are set, the agent's SOUL is composed with the skill's body to form the system prompt.

#### Agent and Skill Dispatch

The daemon resolves `agent` and `skill` against discovered registries (`agents/<name>/SOUL.md`, `skills/<name>/SKILL.md`). New agents or skills never require API changes — they only require a new directory under the corresponding tree.

### Security Model

#### Trusted Execution Boundary

```
Client (untrusted)                 Daemon (trusted)
──────────────────                 ────────────────
authenticate ─────────────────────→ create workload
                                    ↓ attach scopes, KB refs, secret namespaces

submit task (kind + payload) ─────→ hydrate from workload:
                                      • inject secrets (API keys, tokens)
                                      • attach KB context (docs, policies)
                                      • merge workload history (prior outputs)
                                    ↓
                                    execute skill
                                    ↓
                                    sanitize output (redact secrets, PII)
                                    ↓
stream result ←────────────────────← deliver sanitized result
```

The developer submits intent ("review this PR against our security policy"). The daemon knows where the policy lives, has the credentials to fetch it, and returns findings without leaking either.

#### Authentication

Bearer token auth on every HTTP request and WebSocket upgrade.

```yaml
# bento.yaml
auth:
  tokens:
    - id: cli-prod
      secret: "hsk_..."
      scopes: ["pipelines:*", "agents:*"]
    - id: ci-runner
      secret: "hsk_..."
      scopes: ["pipelines:review"]
```

Scopes control which skills, secrets, and KB sources a client can access within its workloads.

#### Secret Isolation

Secrets are stored in the daemon's secret backend, referenced by namespace — never by value in the API. A workload declares which namespaces it has access to (bounded by the client's scopes). Skills resolve secrets at execution time (e.g. `secrets.get("github.token")`).

If a skill output accidentally contains a secret value, the sanitizer strips it before streaming to the client.

#### Ephemeral Execution

Tasks marked `ephemeral: true` leave no trace in the event store. Results are delivered over the WebSocket and discarded. For workloads involving company secrets that shouldn't persist.

### API Surface

The daemon exposes three interfaces on the same Hono server and port. All share the same bearer token auth middleware.

#### CLI scope

The `bento` CLI is scoped to **system lifecycle management of the daemon process** — start, stop, restart, status, logs, install/uninstall (systemd), and queue ops. It is *not* a transport for domain operations. Workload submission, skill invocation, and agent operations are exclusively exposed through the daemon's network transports (REST, WebSocket, MCP) below.

#### REST (human / automation clients)

```
POST   /workloads                  → open workload
DELETE /workloads/:id              → close/teardown workload

POST   /workloads/:id/tasks        → submit task within workload
GET    /workloads/:id/tasks/:id    → poll task status/result
DELETE /workloads/:id/tasks/:id    → cancel task

GET    /health                     → liveness check
```

#### WebSocket (real-time streaming)

```
WS     /workloads/:id/stream       → real-time progress + results for all tasks
```

#### MCP (agent-to-agent interface)

```
GET    /mcp                        → SSE transport for MCP protocol
POST   /mcp                        → MCP message endpoint
```

The daemon exposes an MCP server at `/mcp` via SSE transport. Any MCP-capable client (Claude, pi, Codex, or any agent runtime) gets workload submission as standard tool calls — no custom SDK required.

**Tools:**

| Tool                | Description                                        |
| ------------------- | -------------------------------------------------- |
| `create_workload`   | Open a workload with scopes, KB refs, TTL          |
| `submit_invocation` | Submit an invocation to an agent and/or skill      |
| `get_invocation`    | Poll invocation status and result                  |
| `cancel_invocation` | Cancel a running invocation                        |
| `list_invocations`  | List invocations in a workload                     |
| `close_workload`    | Teardown a workload                                |
| `list_workloads`    | List active workloads for the authenticated client |

**Resources:**

| URI Pattern       | Description                            |
| ----------------- | -------------------------------------- |
| `kb://{source}`   | Read KB material (scoped by workload)  |
| `workload://{id}` | Workload state and accumulated context |

Secret injection and output sanitization apply identically — the MCP layer never exposes secret values in tool results or resources.

This also solves agent-to-agent composition: an agent running inside the daemon can submit a task to another skill on the same daemon via MCP tools, with the security boundary enforced at the workload level.

The WebSocket delivers structured frames:

```jsonl
{"type":"progress","task_id":"...","stage":"clone","pct":30}
{"type":"log","task_id":"...","level":"info","msg":"running agent: reviewer"}
{"type":"progress","task_id":"...","stage":"review","pct":75}
{"type":"result","task_id":"...","status":"completed","output":{...}}
{"type":"error","task_id":"...","code":"AGENT_FAILED","msg":"..."}
```

If a client disconnects and reconnects, it can re-attach to the stream. Missed events are buffered and replayed on reconnect (bounded by a configurable buffer size).

#### Webhook Ingress (unchanged)

The existing webhook routes (`/webhooks/github`, `/webhooks/linear`, etc.) remain on the same server. Incoming webhooks create internal workloads with preconfigured scopes from the pipeline config. Externally, they behave identically to today.

#### Interface Summary

```
:7890
├── /workloads/**          REST — human/CLI clients
├── /workloads/:id/stream  WS  — real-time streaming
├── /mcp                   SSE — agent-to-agent (MCP protocol)
├── /webhooks/**           REST — external event ingress
└── /health                REST — liveness
```

Single port, single auth layer, three consumption patterns.

### Execution Flow

```
1. Client authenticates (bearer token)
2. Client opens workload → POST /workloads
   - Daemon validates scopes, attaches available secrets + KB
   - Returns workload ID

3. Client opens stream → WS /workloads/:id/stream

4. Client submits task → POST /workloads/:id/tasks
   - Daemon validates kind against scopes
   - Enqueues via BullMQ
   - Returns task ID

5. Worker picks up job:
   a. Hydrate context (workload secrets + KB + accumulated context)
   b. Resolve kind → skill runner
   c. Execute skill
   d. Stream progress events → WebSocket manager → client
   e. Sanitize output (redact secrets/PII)
   f. Deliver result frame
   g. Update workload context with result (for subsequent tasks)

6. Client submits more tasks or closes workload
```

### Knowledge Base

KB sources are referenced by name in the workload. During hydration, the daemon resolves the reference and injects content into the skill's context. Clients never download KB material directly.

KB format is TBD — candidates:

* Markdown files on disk (simplest)
* Embeddings in a vector store (semantic retrieval)
* References to external systems (Notion, Confluence, etc.)

### Technology Decisions

#### Hono (HTTP framework)

Evaluated Hono, Elysia, h3, and raw `Bun.serve()`. Hono wins decisively:

* **MCP SDK ships Hono as a direct dependency** (not peer, not optional) with an official `WebStandardStreamableHTTPServerTransport` and a Hono example. Mounting MCP at `/mcp` is three lines.
* **Zero transitive dependencies** — the npm package is a single module.
* **First-class Bun adapter** (`hono/bun`) using Web Standard `Request`/`Response`.
* **Middleware chaining** for auth, CORS, error handling — critical as the API surface grows.
* **WebSocket support** via `hono/ws`.
* Elysia has only a community MCP plugin (v0.1.1, single maintainer). h3 has no MCP support. Raw `Bun.serve()` means reimplementing routing/middleware.

### Implementation Plan

#### Phase 1 — Hono Server ✅

Migrated `Bun.serve()` routing to Hono. Replaced `WebhookServer` class with `Server` class backed by a Hono app. All existing routes and tests preserved. Old `webhook.ts` removed.

#### Phase 2 — Workload Lifecycle

Implement workload creation, persistence, and teardown. Add `POST /workloads` and `DELETE /workloads/:id`. Workloads stored in SQLite alongside events.

#### Phase 3 — Task Submission + Execution

Add `POST /workloads/:id/tasks` and `GET /workloads/:id/tasks/:id`. Wire task submission through BullMQ to the existing pipeline/skill execution machinery.

#### Phase 4 — WebSocket Streaming

Implement `WS /workloads/:id/stream` with progress frames. BullMQ job progress events bridge to WebSocket connections. Handle reconnect + replay.

#### Phase 5 — Secret Store + Sanitization

Implement secret backend (start with encrypted SQLite). Add output sanitizer that strips secret values before delivery. Wire into the hydration/execution flow.

#### Phase 6 — KB Integration

Implement KB source resolution and injection during hydration. Start with markdown files on disk, extend to other backends as needed.

### To Evaluate

#### Sandbox Runtime

[anthropic-experimental/sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) — Anthropic's sandboxed execution environment. Potentially relevant for:

* **Task execution isolation** — run workload tasks in sandboxed containers rather than bare processes, enforcing the trusted execution boundary at the OS level
* **Secret containment** — secrets injected into a sandbox can't leak to the host or other workloads
* **Ephemeral execution** — sandbox teardown guarantees no residual state for `ephemeral: true` tasks
* **Multi-tenant safety** — workloads from different clients run in isolated sandboxes

Needs evaluation: runtime overhead, Bun compatibility, how it composes with BullMQ workers, whether it supports streaming output (needed for WebSocket progress frames).

### Open Questions

1. **Secret backend** — encrypted SQLite to start, or integrate Vault/SOPS from day one?
2. **KB format** — markdown files, vector store, or external system references?
3. **Workload persistence** — survive daemon restarts, or in-memory with TTL?
4. **Multi-tenancy** — single daemon serving multiple orgs, or one daemon per org?
5. **Rate limiting** — per-client, per-workload, or both?
6. **Sandbox runtime** — evaluate Anthropic's sandbox-runtime for task execution isolation (see above)