JARVIS Documentation

The Brain and Sidecars communicate via a single WebSocket connection using an asynchronous, event-oriented protocol. There is no request-response coupling at the transport level; instead, the WebSocket acts as a bidirectional pipe for typed messages.

• Brain → Sidecar: Uses RPC requests to trigger execution on the sidecar.
• Sidecar → Brain: Uses Events to send notifications, including RPC results.

All events from all sidecars are funneled into a central event scheduler on the Brain for ordered processing.

The Personality Engine is organized into several core modules that handle different aspects of the adaptive system:

• model.ts: Manages the personality state structure and how it is persisted.
• learner.ts: Responsible for signal extraction (detecting user preferences) and the learning logic.
• adapter.ts: Handles channel adaptation (e.g., adjusting for WhatsApp, Email, or Terminal) and generating the final LLM prompts.
• index.ts: The main entry point providing the public API exports.

The ServiceRegistry manages the lifecycle of all system services (such as observers, agents, and the WebSocket server). Services must implement the Service interface. You can register services and then trigger startAll() or stopAll() (which stops services in reverse order of registration).

import { ServiceRegistry } from './src/daemon/services.ts';

const registry = new ServiceRegistry();

// Register your service
registry.register({
  name: 'my-service',
  async start() {
    // Start logic
  },
  async stop() {
    // Stop logic
  },
  status() {
    return 'running';
  }
});

// Start all services
await registry.startAll();

// Stop all services (in reverse order)
await registry.stopAll();

Some templates attempt to use desktop_press_keys to perform actions like 'Create Page' or 'Enter Data'. This tool is an OS-level injector to the currently focused desktop window, not the browser session.

Risks and Constraints:

• Focus Dependency: If the browser is not the focused window, keystrokes will land in the wrong application, which can be destructive.
• Headless Failure: It breaks if the browser is running in headless mode (as there is no DISPLAY to receive keys).
• Chrome Shortcuts: Many common shortcuts are reserved by the OS or Chrome and will not work as intended (e.g., Ctrl+N opens a new browser window instead of a Notion page; Ctrl+1..9 switches browser tabs).
• Remote/Sidecar Issues: If the browser and desktop are running in different sidecars or remote environments, the tool may fail to target the correct window.

The npm launcher (npm/jarvis-sidecar/bin/jarvis) is designed to prefer the bundle-associated binary at bin/Jarvis.app/Contents/MacOS/jarvis when running on Darwin. If the bundle is not present, it falls back to a bare bin/jarvis binary.

Note that running the inner binary directly still associates the process with the bundle, allowing notifications to function.

Desktop templates are selected using the matchWebappTemplatesScored(message, context?) function. The matching logic uses an awareness system's context tracker to provide { foregroundProcess?, foregroundTitle? } to the matcher.

Scoring Rules:

• Foreground Process Match: +100 points (e.g., if the user is in VS Code and asks to "split the editor", the VS Code template is selected even without naming it).
• Window Title Match: +50 points.
• Message Keywords: Process names mentioned in the user's message (e.g., "open it in vscode") are matched using word boundaries.

Constraints:

• kind:desktop templates only match if a desktop-capable sidecar is currently connected. Otherwise, they are skipped to prevent the model from receiving unexecutable instructions.

JARVIS implements a built-in authority engine that gates every action at runtime.

Key security features include:

• Audit Trails: All tool executions are logged.
• Explicit Approval: Sensitive operations require manual approval via the dashboard, Telegram, or Discord.
• Emergency Controls: Emergency pause and kill controls are always available to halt operations.

The Role Engine uses a 1-10 scale to control agent capabilities. Higher levels unlock more sensitive action categories:

• Levels 1-2 (Read Only): read_data
• Levels 3-4 (Read & Write): write_data, send_message
• Levels 5-6 (Command Execution): execute_command, access_browser, control_app
• Levels 7-8 (Agent Management): spawn_agent, send_email, install_software
• Levels 9-10 (Full Access): make_payment, modify_settings, delete_data, terminate_agent