gnome-jarvis/docs/harness-integration.md

Agent harness integration

The copied harness at vendor/agent-harness is the cognitive core. It is kept as a repository copy so releases are reproducible and do not depend on the machine at ~/dev/agent-harness after checkout. The original source remains the upstream reference described in agent-harness-map.

flowchart LR
  P[Prompt] --> B[harness-bridge.js]
  B --> S[Agent session]
  S --> L[agent/loop.js]
  L --> T{Tool call?}
  T -->|yes| R[Jarvis JSON-schema tool]
  R --> X[master / desktop / CU / files]
  X --> L
  T -->|no| O[Reply + HUD sidecar]
  S --> MEM[Local sessions + memory]

Harness responsibilities

• Multi-turn session state and compaction.
• Planner/tool-call loop and permission mode.
• Short- and long-term local memory.
• Tool schema validation and execution events.
• Streaming model messages adapted into daemon events.

Jarvis responsibilities

Jarvis registers domain tools from skills/, supplies the system prompt, maps tool permissions to confirmation gates, and translates harness events into the D-Bus protocol. Computer-use tools are custom harness tools backed by computer-use/; the computer-use layer never owns planning.

Adding a tool

1. Put the implementation in the appropriate skill module.
2. Export a JSON-schema tool with a stable name, description, timeout, and permission level.
3. Route QVAC work through the master facade.
4. Add a focused fixture test with a fake master or backend.
5. Update API, the capability matrix, and the roadmap if the tool is user-visible.

Destructive tools require explicit confirmation. Computer-use tools additionally require an active grant, a visible overlay, a live step budget, and a lock-screen check.