Skip to main content

Architecture & Protocol

Locus combines a native client and an agent service, with optional independent execution:

  • The SwiftUI application owns native presentation, workspace access, permission surfaces, platform integrations, and feature view models.
  • The Python service owns model and provider I/O, orchestration, tools, sessions, schedules, persisted runs, and the authenticated local API.

They communicate over authenticated loopback HTTP and WebSocket contracts. The independent supervisor can own service workers beyond the desktop lifetime, and SSH deployment can place them on an owned host.

Native app​

AppModel is the composition root. It connects features, translates events, and derives cross-feature presentation, but new feature state and actions belong in a feature-owned observable model.

In 2.1, provider accounts, agent teams, run history, the live run card, extensions and MCP, workspace knowledge, evaluations, schedules, the Activity Center, transcript search, background services, the AGENTS.md editor, landing flow, and toasts moved to their own tested models. GitWorkspaceModel and WorkspaceFileModel own Git and file behavior, while BrowserService, TerminalSession, ApplicationContextService, and SimulatorControlService retain independent platform lifetimes.

Feature views observe their model directly. Dependencies flow toward feature models; a feature model must not retain AppModel. The composition root supplies narrow callbacks for shared presentation such as toasts or session activity.

Bundled agent​

server.py is the service composition root. create_app builds isolated FastAPI instances, and request-time dependencies resolve from the concrete application.

Chat runtime lives in chat_service.py. Domain modules own ordinary request behavior: workspace and evaluations; system and providers; knowledge, sessions, and continuity; schedules; runs and usage; extensions; and authenticated chat/Codex transport. Request-neutral runtime helpers live beside those modules.

API modules resolve services through the dependency layer and do not import a module-global application. New routes belong in the matching domain module. The server.app symbol remains only as the uvicorn and import compatibility entry point.

Communication​

The app and service communicate over authenticated REST and WebSocket endpoints bound to 127.0.0.1. The service rejects browser-origin requests. Browser, Notes, Terminal, and Computer Control capabilities appear dynamically only when their native broker and permissions are available.

ChatGPT-plan requests use a pinned Codex App Server child over local JSONL and stdio. Direct builds resolve it from the verified downloaded component; development builds can embed it. Team workers use a launch-token-authenticated internal broker and never receive OAuth state.

Locus Mobile uses a separate private TLS gateway with certificate pinning and a one-use pairing code. It never exposes the agent's loopback port.

Persistence​

  • append-only session JSONL plus organizer metadata and recoverable trash;
  • local SQLite for durable runs, schedules, usage, and team events;
  • encrypted saved-chat cache envelopes with in-memory full-text search, separate from raw session JSONL;
  • private Git worktrees and immutable evaluation fixtures;
  • hashed local note ownership, formatting archives, Notebook labels, Browser profiles, and Keychain-backed Autofill;
  • AES-256-GCM memory and continuity with a user-only local memory/master.key file; and
  • versioned shared Mac/mobile protocol fixtures.

Credentials, secure fields, provider signatures, and hidden reasoning are excluded from run records and exports by default.

Reviewable changes​

Keep a refactor and a behavior change separate when either can stand alone. Route moves retain contract snapshots; feature ownership moves retain characterization tests until consumers use the new boundary directly.

Tools/ReviewabilityReport.py reports large production files, large diff slices, architecture-boundary drift, new published state or view-facing actions in AppModel, and registered route handlers added to server.py. Findings are advisory: a large file is not itself a defect, but another unrelated responsibility is a signal to choose a clearer owner.

Feature ownership​

Persistent goals keep durable objective state, cumulative usage, continuation reservations, and action recovery in the existing run store. The native Goal model coordinates continuation through the ordinary chat worker.

Task Capsules use a workspace-scoped SQLite store for saved plans, immutable revisions, baseline validation, and run links. Each stage resolves the exact account from its selected profile.

Library coordinates document extraction, citation locations, and immutable output snapshots with separate metadata. Identity Vault keeps its own encrypted storage and edition-specific Keychain key; its restricted task path is separate from ordinary tool dispatch.

Saved agents in 3.0 are reusable profiles with persistent project chats and optional schedules or event/price triggers. Their definitions, trigger records, and shared connections remain separate from open chats. Receipt, occurrence, attempt, and execution identities remain distinct in the inspector and activity views.

Your companion reuses the same canonical agent ID, display name, portrait store, and project-scoped conversation bindings. Versioned appearance references and animation preferences remain presentation data. The existing onboarding model owns the versioned draft; a reserved ID and recoverable creation intent make final confirmation idempotent. In 4.1, the panel and menu-bar popover share the normal session-bound draft and background worker. The companion's saved default project preference selects its folder independently of the central chat. These surfaces do not introduce another agent database, chat engine, scheduler, or permissions system.

The independently maintained, hash-pinned Locus Runtime package owns process supervision, remote transport, reviewed results, and service recovery. Locus retains the existing profile and public-protocol boundaries. Agent Worlds owns its renderer in a separate repository; Locus supplies the version-2 host bridge and remains authoritative for profiles, chats, permissions, and tasks. This world protocol is separate from the generic version-1 plugin-panel protocol used by the independent Social Studio plugin. See Agent Worlds compatibility before using a legacy package.

The bundled Locus Memory 0.3.0 package owns memory records, retrieval scopes, encrypted submission references and cache envelopes, episodes/procedures, and ledger reconciliation. Locus supplies authenticated identity, model calls, actual task verification, approved evaluation execution, native review UI, and signed macOS Keychain custody. Native Codex memory is explicit per-agent opt-in; memory remains lower-priority reference data. Optional local embeddings keep keyword fallback. Approval of a learned procedure does not install instructions.

Packaging selects wallet-free Locus or the separate LocusX backend and native source set. Wallet support cannot be activated in a standard staged build by changing a setting or environment variable.

Managed provider sessions in 3.0​

Claude plan is a distinct provider from Claude API. Its pinned SDK and managed runtime maintain isolated account homes and resumable sessions. Locus exposes its tools through the managed adapter and disables implicit provider execution tools so permissions remain in the existing dispatch boundary. Account, model, workspace, instructions, and tool schemas participate in safe session reuse. Forks rebuild from copied transcripts.

Saved-agent instructions use the system channel rather than becoming replayed user history. Interrupted managed calls preserve uncertainty; they are not silently replayed. Claude distribution approval and broader authenticated verification remain preview gates. Standard portable candidate packages include Codex only; Claude capability requires the explicit optional verified helper.

Independent execution and remote control​

The supervisor owns workers, durable events, schedules, goal claims, and connector execution. Controllers reconnect with an event cursor and pending-decision snapshot. Current decision fingerprints prevent stale approval reuse. Ordinary work pauses after controller disconnect; explicitly opted-in work continues.

Native actions require a broker lease and an action claim. Requests wait without the desktop, and a lost connection after a claim can leave an uncertain outcome. Private native results are kept out of event history. Runtime credentials live in a separate user-only private store; selected credentials reach remote hosts through authenticated SSH tunnels.

Remote installation validates target architecture, package hashes, helpers, and startup identity. Update journals and database backups make rollback explicit. Candidate startup blocks mutations and new work until activation succeeds. Failed updates restore the previous service and databases; interrupted recovery remains blocked until reconciled.

Task records, evidence, and accounting​

A logical task links sessions, runs, goals, capsule attempts, helpers, and immutable approved-plan references. Tool receipts record actual outcomes, task revision, execution location, and relevant file fingerprints. Completion evidence becomes stale when its requirements or inputs change. Task details are a read-only projection until an explicit permitted action is requested.

Task-history migrations are additive: schema 14 supplies verified-task records and capsule attempts, 15–17 add independent-runtime accounting and reusable checks, 18 links tasks, immutable plans and milestones, 19 adds task usage and spans, and 20 adds captured content and restoration journals. Legacy step kinds remain sequential writes; absent evidence stays unverified, and missing costs stay unknown. Older database clients use their read-only compatibility path.

The persistent invocation ledger records pending calls before dispatch and settlement afterward, with price provenance and deduplication. The logical-task usage projection overlaps those calls; the two views are not additive. Frozen evaluation configurations include the route, model, prompts, tools, permissions, budgets, approved checks, and fixture baseline. Execution and grading outcomes remain separate.

Captured changes support bounded preview/apply/undo restoration with revision and fingerprint checks, conflicts, atomic writes, and durable recovery records. Private Identity tasks and external actions are excluded. Existing mobile endpoints remain compatible with additive fields; runtime administration and the richer task controls remain desktop features.