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

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.

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:

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.

4.8 KiB Raw Blame History