# Agent (grok-class harness)

`BridgeSwarm.agent` is a Bare JS agent loop modeled on Grok Build: sample → tool calls → results → repeat. Inference is QVAC (`tools: true`). Image/video tools are not implemented. The agent requires **Settings → Enable QVAC**; `create` / `prompt` fail until that toggle is on.

## Embed

```js
const session = await BridgeSwarm.agent.create({
  model: 'qwen3.5-4b',
  cwd: 'default',
  permissionMode: 'ask' // ask | allowlist | always-approve
})
session.on((ev) => { /* agent_message_chunk | tool_call | permission | end */ })
await session.prompt('List the workspace and summarize')
await session.cancel()
```

Always-approve is only honored for origins listed under **Settings → Agent always-approve**.

## Tools

Must-have: `read_file`, `write_file`, `search_replace`, `grep`, `list_dir`, `run_terminal_cmd`, `todo_write`

Also: `task` / `send_subagent_message` / `get_task_output` / `wait_tasks` / `kill_task` (subagents share the loaded model), `web_search`, `web_fetch` (opt-in), `memory_search` / `memory_get`, `enter_plan_mode` / `exit_plan_mode`, `ask_user_question`, `search_tool` / `use_tool` (MCP HTTP only; stdio requires a trusted origin and is not spawned by default)

Shell is cwd-jailed via `bare-subprocess` (host-internal, not a page pack). MCP HTTP tools must be public URLs (`net` policy).

## Custom tools from the page

Handlers stay in the tab (they are never sent to the host). The host only stores the JSON schema and, when the model calls the tool, waits for `toolResult`.

```js
const session = await BridgeSwarm.agent.create({
  model: 'qwen3.5-4b',
  tools: [
    {
      name: 'get_cart',
      description: 'Return the in-page shopping cart',
      parameters: { type: 'object', properties: {} },
      execute: () => window.cart,
    },
  ],
})
await session.addTool({
  name: 'highlight',
  description: 'Highlight a line in the page editor',
  parameters: { type: 'object', properties: { line: { type: 'number' } }, required: ['line'] },
  execute: (args) => { editor.highlight(args.line); return 'ok'; },
})
await session.prompt('Add a README.md then highlight line 1')
```

Built-in names (`read_file`, `write_file`, …) cannot be overwritten **while host workspace tools are on**. Max 32 custom tools per session. Events include `tool_request` when the page must run a handler.

## Disable host workspace (page / container agents)

By default the agent ships host-jail tools against `$BRIDGE_SWARM_STORAGE/agent/<origin-hash>/`. Embedders that own their own filesystem (a container, a panel, an in-page editor) should turn that off so the model never sees or shells the native host:

```js
const session = await BridgeSwarm.agent.create({
  model: 'qwen3.5-4b',
  hostWorkspace: false,          // or hostTools: false
  workspace: 'dlinux-container', // prompt label only — not a host path
  builtinTools: false,           // optional: drop todo/task/web/MCP builtins too
  tools: [
    {
      name: 'read_file',
      description: 'Read a file inside the container',
      parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
      execute: (args) => container.read(args.path),
    },
    {
      name: 'run_terminal_cmd',
      description: 'Run a command in the container',
      parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
      execute: (args) => container.exec(args.command),
    },
  ],
})
```

With `hostWorkspace: false`:

- Host `read_file` / `write_file` / `search_replace` / `grep` / `list_dir` / `run_terminal_cmd` / `memory_*` are **not** offered and will not execute on the host.
- Those names may be registered as page tools (handlers stay in the tab).
- `cwd` / `workspace` is a label for the system prompt, not a path under `$BRIDGE_SWARM_STORAGE`.
- Subagents do not get host filesystem tools.
- Session JSONL still lives under `$BRIDGE_SWARM_STORAGE/agent/sessions/` (harness metadata only).

`builtinTools: false` removes remaining host-executed builtins (`todo_write`, `task`, `web_search`, MCP, …). Pass an array of names to keep a subset.

Pages cannot grant extra host roots via `create` — extra absolute roots still come only from **Settings → Agent workspace roots**.

## Sandbox

Default cwd: `$BRIDGE_SWARM_STORAGE/agent/<origin-hash>/`. Extra absolute roots: Settings → Agent workspace roots (pushed to the host as grants).

## Sessions

JSONL under `$BRIDGE_SWARM_STORAGE/agent/sessions/`. History is compacted near 80% of the model context.

## ACP-shaped events

Host emits `cap-chunk` with `pack: 'agent'` and `type` in `agent_message_chunk`, `agent_thought_chunk`, `tool_call`, `tool_result`, `permission`, `ask_user`, `end`.

Models, devices, enable toggle, and `BridgeSwarm.qvac` chat (page-owned tools, no workspace shell) are documented in [QVAC.md](QVAC.md).