# API reference

## Session D-Bus

Bus name: `io.qvac.Jarvis`  
Object path: `/io/qvac/Jarvis`  
Interface: `io.qvac.Jarvis.Session`

The canonical XML contract is [io.qvac.Jarvis.Session.xml](../dbus/io.qvac.Jarvis.Session.xml).

| Method | Purpose |
| --- | --- |
| `Arm()` / `Sleep()` / `Shutdown()` | Control daemon voice lifecycle |
| `PushToTalk(bool)` | Begin/end typed or microphone turn |
| `Say(string)` | Speak text through local TTS |
| `Ask(string)` | Submit typed text to the harness |
| `ReloadSettings()` | Re-read `config.json` and return a status string |
| `PreviewVoice(string)` | Speak preview text without adding a chat turn |
| `StopSpeech()` | Interrupt TTS playback |
| `ResetContext()` | Clear the current conversation context |
| `Confirm(jobId, toolCallId, decision)` | Answer a confirmation gate |
| `Cancel()` | Cancel active request/job |
| `SetMode(string)` | Set capability mode (not HUD layout) |
| `GetState()` | Return serialized daemon state |
| `EnrollWake(string)` | Configure wake phrase |
| `IngestPath(string)` | Add a local path to RAG ingestion |
| `ComputerGrant(bool)` / `ComputerRevoke()` | Start/stop computer-use grant |
| `ComputerStatus()` | Return computer-use status JSON |
| `GetRuntimeStatus()` | Return voice/runtime component status JSON |
| `AssessModelFit(string)` | Report whether a model fits the GPU profile |
| `DownloadModel(string)` | Start a model download |
| `CancelModel(string)` | Cancel a model download |
| `WipeComputerTraces()` | Wipe computer-use frames; returns whether wipe ran |

| Signal | Purpose |
| --- | --- |
| `StateChanged` | Voice/daemon state string |
| `ContextReset` | Conversation context was cleared |
| `WakeHeard` | Wake phrase detected |
| `PartialTranscript` / `FinalTranscript` | ASR text |
| `Token` / `Reply` | Streamed and final assistant text |
| `SpeakingLevel` / `ListeningLevel` | Audio RMS. The HUD no-ops these; there is no waveform |
| `ChipOffered` | Suggestion sidecar |
| `JobProgress` | Background job progress |
| `ComputerStep` / `ComputerHighlight` | CU step text and target highlight rect |
| `ConfirmationRequired` | Tool permission prompt |
| `Thinking` | Planner thought tokens |
| `ToolCall` / `ToolResult` | Tool activity JSON |
| `Error` | Code and message |

Payloads stay small; PCM and image bytes do not travel over D-Bus.

## Computer-use tools

Tools are registered with the harness and exposed through the daemon. The
observable contract includes `cu.grant`, `cu.revoke`, `cu.status`,
`cu.observe`, `cu.zoom`, `cu.tree`, `cu.find`, `cu.click`, `cu.drag`,
`cu.scroll`, `cu.type`, `cu.key`, and `cu.act`. Every action is checked against
the active grant and safety policy. The HUD shows visible CU chrome (target
highlight and agent cursor), not a waveform overlay.

## Search tools

Implemented in `vendor/agent-harness/agent/web-search.js` for Bare (fetch plus
regex/JSON, no extra npm, no SearXNG):

| Tool | Behavior |
| --- | --- |
| `web_search` | Public search. Default `engine=auto` walks duckduckgo → ddg_lite → jina → bing → bing_rss → google → wikipedia → ddg_instant. Pin `engine` to retry one backend. |
| `google_search` | Google HTML first, then the auto chain |
| `fetch_page` | Readable text via Jina Reader, then HTML strip |
| `web_fetch` | Raw stripped text, including IP lookup pages (do not send those through Jina) |
| `wiki_search` | Wikipedia MediaWiki JSON |
| `hn_search` | Hacker News via Algolia |
| `code_search` | GitHub, npm, and MDN in parallel |

These are public reads and do not require extra API keys. Shell HTTP
(`curl`/`wget` over public hosts) remains blocked; use these tools instead.

## Local HTTP

QVAC's optional OpenAI-compatible server is localhost-only at port `11434`.
It is a diagnostic surface, not a second Jarvis runtime. Native QVAC-only
operations use `/qvac/v1/*` where supported by the installed QVAC version.