xr

01What this is, in one paragraph

xr is an agentic runtime for people who are tired of agents that act like they own your credit card. You give it a task; it plans, calls tools, and changes real things on your machine — under a policy gate, your approval for risky actions, a hard budget ceiling, and a tamper-evident log of everything it did. BYOK and local-first: your keys, optionally a local model, no middleman account.

02The problem I actually built for

In 2026 every demo agent is a loop calling a model. The interesting engineering isn't the loop — it's what bounds the loop. Most agent frameworks treat spend, egress, and approval as afterthought "guardrails" bolted onto the prompt, where a persuasive model can negotiate around them. I wanted the opposite: bounds enforced in deterministic TypeScript that the model can see but not touch. That single design decision — the budget lives outside the brain — shaped every module in the repo.

03Architecture

The core loop (src/core/agent.ts) is dependency-injected: it takes providers, tools, state, and the governor as constructor arguments, which is exactly what makes the guarantees testable — tests hand it a greedy fake provider and assert the run stops. Twenty-seven modules sit under src/ (cost, security, mcp, memory, plugins, providers…) and the release/version surface is stamped from a single release.manifest.json — if any drift, CI fails. Boring on purpose.

04The load-bearing decisions

• Enforce before generate. The governor's checkBeforeStep() runs every turn with an optimistic estimate of the next call — denial is proactive, not reactive bookkeeping.
• Typed decisions, no booleans. GovernorDecision is a discriminated union: a denial must carry a reason and a snapshot; there's no silent false to ignore in the UI layer.
• Egress allowlist, default deny. Network is an effect like any other; the agent doesn't get "helpful" outbound calls for free.
• MCP as a platform, not a plugin bolt-on. Server and client support are first-class (the repo's plugin marketplace treats MCP tools like any other skill).
• Deliberate non-decision: no LangGraph/CrewAI dependency. With the loop this small and this load-bearing, owning those ~400 lines beats inheriting someone else's abstraction.

05The exhibit: the ceiling that can't be negotiated

/**
 * XR — Cost Governor tests. The headline guarantee: the agent CANNOT
 * exceed the ceiling, enforced in deterministic code.
 */
test("governor blocks the next step before exceeding the token ceiling", () => {
  const g = new CostGovernor({ maxTokens: 1000 }, ...);
  g.record(400, 100); // 500 used
  expect(g.checkBeforeStep().allow).toBe(true);
  g.record(400, 100); // now 1000 used
  expect(g.checkBeforeStep().allow).toBe(false); // at ceiling
});

test("AGENT LOOP: a tiny token ceiling stops the run (the headline
guarantee)", async () => {
  // Provider that always wants to keep going…
  // …loop is asserted to stop. The budget wins over the model.

export type GovernorDecision =
  | { allow: true; warning?: string }
  | { allow: false; reason: string; snapshot: CostSnapshot; suggestLocal?: boolean };

export interface Budget {
  /** Hard ceiling in USD for this task (0 or undefined = no $ cap). */
  maxUsd?: number;
  /** Hard ceiling in total tokens for this task. */
  maxTokens?: number;
}

Three things I like about it: the boundary semantics are decided and tested (at-ceiling is denied), the local-model path is priced at zero explicitly instead of special-cased downstream, and the integration test proves the loop halts — not just the component.

06How it's shipped, not just written

Sixty-five PRs merged through branches, seven CI workflows (unit, cross-platform, nightly, provider canaries, supply-chain, release), published to npm as @rrrtx/xr — currently v3.x — with install scripts for Linux/macOS/Windows/Termux and a documented beta feedback loop. The footer of this site shows the CI status of the latest run whatever it is; when it's broken, this sentence is the proof I'm not cherry-picking.

07Lessons, kept

• Guarantees belong in code the model cannot edit, above the prompt.
• A passing integration test is worth more than a polished README paragraph.
• Ship on a registry early: versioning forces honesty about what "done" means.
• One source of truth (release manifest) deleted a whole category of drift bugs.