107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
# 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).
|