82 lines
3.6 KiB
Markdown
82 lines
3.6 KiB
Markdown
# Agent harness map
|
|
|
|
Source of truth for Jarvis runtime: `vendor/agent-harness/`, copied from
|
|
`/home/raven/dev/agent-harness` (`~/dev/agent-harness`). The original extracted
|
|
tree remains the upstream working source; the vendored directory is the copy
|
|
that ships with this repository.
|
|
|
|
## Layout and runtime
|
|
|
|
The harness is a standalone CommonJS package. Its public entrypoint is
|
|
`index.js`, with the CLI at `bin/cli.js`. The harness README says Node 20 is
|
|
enough for the package itself; QVAC inference on Node needs 22.17+. That
|
|
Node requirement applies to tests and `node vendor/agent-harness/bin/cli.js`,
|
|
not to production `jarvisd`. Jarvis runs the copied harness inside packaged
|
|
Bare.
|
|
|
|
Important modules:
|
|
|
|
- `index.js`: public `Agent.create()` / `Agent.load()`, session wrapper, engine and catalog exports.
|
|
- `agent/loop.js`: sample → tool call → tool result → repeat loop, permissions, plan mode, compaction, memory, and subagents.
|
|
- `agent/custom-tools.js`: per-session JSON-schema tool registry and in-process `execute` handlers.
|
|
- `agent/tools.js`: built-in host workspace, memory, planning, web, task, and MCP tools.
|
|
- `agent/sessions.js`: persisted session summaries, history, updates, and plan files.
|
|
- `agent/memory.js`: local short/long-term memory notes.
|
|
- `lib/qvac.js`: lazy `@qvac/sdk` import, model loading, completion streaming, vision attachments, cancellation, and lifecycle close.
|
|
- `lib/catalog.js`: friendly model ids mapped to QVAC SDK constants.
|
|
|
|
## Start and embed
|
|
|
|
CLI: `node vendor/agent-harness/bin/cli.js [options] [prompt]`.
|
|
|
|
Library integration uses CommonJS from the harness root:
|
|
|
|
```js
|
|
const Agent = require('./vendor/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',
|
|
tools: [{ name, description, parameters, execute }],
|
|
});
|
|
await session.prompt('hello');
|
|
await session.dispose();
|
|
await Agent.engine.close();
|
|
```
|
|
|
|
Sessions emit `agent_message_chunk`, `tool_call`, `permission`, `ask_user`,
|
|
plan, context, and related loop events. Jarvis adapts the message and tool
|
|
events to its D-Bus contract. `session.permit()`, `session.answer()`,
|
|
`session.cancel()`, and `session.addTool()` are the control points.
|
|
|
|
## Tool registry and permissions
|
|
|
|
Jarvis registers tools through `Agent.create({ tools })`. Each custom tool is a
|
|
JSON-schema object with an optional in-process `execute(args)` handler. The
|
|
harness caps custom tools at 32 and reserves its built-ins. Permission mode is
|
|
`ask` by default; write and dangerous desktop/computer-use tools remain behind
|
|
Jarvis confirmation gates.
|
|
|
|
## Session, memory, and planner
|
|
|
|
`agent/loop.js` owns the multi-turn agent loop and repeats completion/tool
|
|
execution until a final response. `sessions.js` persists conversation state.
|
|
`memory.js` provides local memory tools. `plan-mode.js`, `compaction.js`,
|
|
`goal.js`, and `tasks.js` provide planning, context management, goals, and
|
|
subagents. Jarvis does not create a second planner.
|
|
|
|
## Model connection
|
|
|
|
The harness does not use an OpenAI-compatible HTTP URL internally. Its
|
|
`lib/qvac.js` imports `@qvac/sdk` in-process and calls `loadModel()` and
|
|
`completion()`. Jarvis keeps the optional sibling `qvac serve --openai`
|
|
provider for external clients and diagnostics, while the cognition bridge
|
|
wraps the harness in-process as required by the extracted package.
|
|
|
|
## Computer use
|
|
|
|
The inspected harness has no first-class portal, AT-SPI, libei, or desktop
|
|
computer-use backend. Jarvis therefore supplies those as custom tools from
|
|
`computer-use/` and `skills/`, while keeping planning in `agent/loop.js`.
|