104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# 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.
|