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 Node.js CommonJS package. Its public entrypoint is index.js, with the CLI at bin/cli.js. The README says Node 20 is enough for the harness itself, while its QVAC inference dependency requires Node 22.17+; Jarvis therefore requires Node 22.17+.

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:

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.

3.5 KiB Raw Blame History