Actually vendor harness

2026-09-11 13:41:22 -04:00
parent 1acd371668
commit 04e013b090
52 changed files with 8550 additions and 1 deletions
@@ -0,0 +1,103 @@
+# 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.