# agent-harness

Standalone grok-class coding agent on **QVAC**. Sample → tools → compact → repeat. No BridgeSwarm, no Chrome native messaging, no extension.

Inference is `@qvac/sdk` (Node worker). Only Hugging Face GGUFs that already exist as QVAC constants load. Arbitrary HF repos will not.

## Install

Node.js 20 or newer. `@qvac/sdk` itself wants **22.17+** for inference.

```bash
cd ~/dev/agent-harness
npm install
```

Weights download on first `load` into the QVAC cache (see `qvac.config.json` / `cacheDirectory`).

## CLI

```bash
node bin/cli.js --list-models
node bin/cli.js --cwd ~/src/myapp "list the workspace and summarize"
node bin/cli.js --model qwen3.5-4b --yes
```

`--yes` skips write/shell prompts. Default model is `qwen3.5-4b`. On a 16 GB card, `gemma4-4b` and `qwen3-8b` also fit.

Sessions and permission rules live in `~/.agent-harness` (or `$AGENT_HARNESS_HOME`).

## Embed

```js
const Agent = require('~/dev/agent-harness') // or require('/root/dev/agent-harness')

await Agent.engine.load({ model: 'qwen3.5-4b', tools: true, device: 'auto' })

const session = await Agent.create({
  cwd: process.cwd(),
  model: 'qwen3.5-4b',
  permissionMode: 'ask', // ask | allowlist | always-approve
  tools: [
    {
      name: 'get_time',
      description: 'Current unix time',
      parameters: { type: 'object', properties: {} },
      execute: () => Date.now(),
    },
  ],
})

session.on('agent_message_chunk', (ev) => process.stdout.write(ev.text || ''))
session.on('permission', (ev) => session.permit(ev.jobId, ev.toolCallId, 'allow'))

await session.prompt('List the workspace and summarize')
await session.dispose()
await Agent.engine.close()
```

`hostWorkspace: false` drops host FS/shell/memory so you can register your own `read_file` / `run_terminal_cmd` (same pattern Pip uses against a container).

## Tools

Host builtins (cwd-jailed): `read_file`, `write_file`, `search_replace`, `grep`, `list_dir`, `run_terminal_cmd`, `todo_write`, `web_search`, `web_fetch` (opt-in), `memory_*`, plan mode, `ask_user_question`, `update_goal`, subagents (`task`), MCP HTTP (`search_tool` / `use_tool`).

Custom tools with `execute` run in-process. Without `execute`, the loop emits `tool_request` and waits for `session` to call the loop resolver (embedder-owned handlers).

## Catalog

| id | tools | vision | ~weights |
|---|---|---|---|
| qwen3.5-0.8b | yes | yes | 0.7 GB |
| qwen3.5-2b | yes | yes | 1.6 GB |
| qwen3.5-4b | yes | yes | 2.8 GB |
| qwen3.5-9b | yes | yes | 5.5 GB |
| gemma4-2b | yes | yes | 3.5 GB |
| gemma4-4b | yes | yes | 5 GB |
| qwen3-8b | yes | no | 5 GB |
| qwen3vl-2b | yes | yes | 1.5 GB |
| qwen3.6-27b / gemma4-31b / gpt-oss-20b / … | yes | varies | larger card |

Not added: Qwen3-14B, Gemma 3 12B, Llama 3.1 8B, and similar chats with no QVAC constants.

## Layout

```
index.js          Agent.create / load / catalog
bin/cli.js        REPL and one-shot prompt
lib/qvac.js       @qvac/sdk load + completion
lib/catalog.js    id → QVAC constant
agent/loop.js     turn loop
agent/tools.js    sandbox execute
agent/*.js        compact, plan, goal, MCP, permissions, …
```

This is a port of the BridgeSwarm grok-class loop onto Node + `@qvac/sdk`. It is not the Pip panel client and does not speak native messaging.

## Test

```bash
npm test
```

Unit tests cover catalog, compaction, tools policy, and path jail. They do not download a GGUF.