Desktop Agent Governance

The problem

Desktop AI agents — systems with access to the shell, browser, filesystem, and network — operate at machine speed. They generate proposals continuously, often in parallel, across multiple contexts. Human oversight alone cannot keep pace.

The failure modes are predictable: filesystem writes to paths the human never authorized; network requests to endpoints outside the intended scope; shell commands that make sense individually but compose into an unintended sequence.

The architectural response is a constitutional governance layer: separate from the acting system, deterministic in its authority, composition-aware across the session, and fail-closed by default. Vigil is that layer, implemented in TypeScript for the Node.js and desktop agent ecosystem.

Architecture

Vigil is a stateless HTTP oracle. The agent submits a proposed action as JSON. Vigil evaluates it against the constitutional policy and the session composition record. It returns a structured verdict. Nothing executes without a verdict.

The verdict contract

Fail-closed guarantee

When Vigil is unreachable, policy is ambiguous, or session state is uncertain, the default verdict is DENY.

The three laws

Vigil composes three Laws from the AgentVector Codex, each governing a distinct category of desktop agent action.

Proof of concept implementations

Two POCs implement the Stackmint.ai integration contract: JSON in / JSON out, three decision states, full violation reporting.

// Request
POST /evaluate
{
  "session_id": "sess_abc123",
  "action": {
    "type": "llm_inference",
    "estimated_tokens": 4200,
    "model": "claude-sonnet-4-6"
  }
}

// Response — DENY (budget exhausted)
{
  "verdict": "DENY",
  "law_ref": "Law 4 · Resource · budget_exhausted",
  "violations": [{
    "budget_remaining": 1800,
    "requested": 4200
  }],
  "replay_hash": "sha256:7f4a..."
}

// Request
POST /evaluate
{
  "session_id": "sess_abc123",
  "action": {
    "type": "network_request",
    "url": "https://api.github.com/repos/...",
    "method": "GET"
  }
}

// Response — ALLOW (domain on allowlist)
{
  "verdict": "ALLOW",
  "law_ref": "Law 0 · Boundary · url_allowlist",
  "matched_rule": "api.github.com · GET · read_only",
  "replay_hash": "sha256:3c9d..."
}

Stackmint integration

Flo at Stackmint.ai requested a Vigil integration for their AI development workflow platform. The integration contract specifies a pre-commit gate: JSON in / JSON out, three decision states, full violation reporting.

Cross-domain proof

Vigil composes Laws 0, 4, and 8 into a desktop agent jurisdiction. The same Laws compose differently in aviation and narrative contexts.