# boccchi2993/locus-browser-agent-runtime architecture

> Architecture diagram of the GitHub repository boccchi2993/locus-browser-agent-runtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boccchi2993/locus-browser-agent-runtime
- Repository: https://github.com/boccchi2993/locus-browser-agent-runtime

## Overview

Locus is a browser-local execution runtime for AI agents. A user submits a task through the workspace UI; the presentation store hands it to the agent harness, which coordinates model requests, approvals, and tool execution. The principal local execution path is bash through the compatibility shell into the VFS, Python worker, or network runtime. Workspace files, downloads, conversations, capabilities, and model replay state are handled by distinct subsystems. The README documents several capabilities beyond the sampled excerpts; links for those are included where the architecture is explicit, but uncertain internal wiring is omitted.

Main entry points: [`src/agent.js`](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/agent.js) (Agent session), [`src/ui/store.js`](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/ui/store.js) (UI store), [`src/shell.js`](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/shell.js) (Compatibility shell), [`src/model-adapters.js`](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/model-adapters.js) (Provider adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Workspace UI"]
  node_ui["Workspace interface<br/>[App.vue]"]
  node_store["UI store<br/>[store.js]"]
  node_projector["Event projector<br/>[projector.js]"]
end

subgraph group_harness["Agent harness"]
  node_agent["Agent session<br/>[agent.js]"]
  node_model["Model protocol<br/>[model.js]"]
  node_adapters["Provider adapters<br/>[model-adapters.js]"]
  node_approval["Approval control<br/>[approval.js]"]
  node_attachments["Image attachments<br/>[attachments.js]"]
  node_tools["Tool registry<br/>[tools.js]"]
end

subgraph group_execution["Browser substrate"]
  node_shell["Compatibility shell<br/>[shell.js]"]
  node_vfs["Virtual filesystem<br/>[vfs.js]"]
  node_workspace["Workspace access<br/>[workspace.js]"]
  node_python["Python worker<br/>[shell.js]"]
  node_network["Network runtime<br/>[network.js]"]
  node_telemetry["Execution telemetry<br/>[telemetry.js]"]
end

subgraph group_state["State and extensions"]
  node_capabilities["Capability composition<br/>[capabilities.js]"]
  node_extensions["Plugins and skills<br/>[extensions.js]"]
  node_persistence[("Browser persistence<br/>[persistence.js]")]
end

subgraph group_services["External services"]
  node_fetchrelay["Public-resource relay<br/>[fetch.js]"]
  node_proxy["Model API relay<br/>[proxy.js]"]
end

node_user(("User"))
node_modelprovider(("Model provider"))
node_browser(("Browser APIs"))
node_pyodide(("Pyodide"))

node_user -->|"submits task"| node_ui
node_ui -->|"invokes actions"| node_store
node_store -->|"starts task"| node_agent
node_agent -->|"requests response"| node_model
node_model -->|"selects provider"| node_adapters
node_adapters -->|"sends request"| node_modelprovider
node_modelprovider -->|"returns response"| node_adapters
node_adapters -.->|"relays request"| node_proxy
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"runs bash"| node_shell
node_shell -->|"reads and writes"| node_vfs
node_vfs -->|"mounts folder"| node_workspace
node_workspace -->|"uses file access"| node_browser
node_shell -->|"executes Python"| node_python
node_python -->|"runs code"| node_pyodide
node_shell -->|"runs curl"| node_network
node_network -.->|"relays request"| node_fetchrelay
node_agent -->|"requests approval"| node_approval
node_approval -->|"updates pending state"| node_store
node_agent -->|"uses image input"| node_attachments
node_attachments -->|"provides image input"| node_model
node_store -->|"enables capability"| node_capabilities
node_capabilities -->|"composes extensions"| node_extensions
node_agent -->|"records execution"| node_telemetry
node_store -->|"projects events"| node_projector
node_store -->|"stores session state"| node_persistence
node_persistence -->|"uses IndexedDB and OPFS"| node_browser

click node_ui "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/App.vue"
click node_store "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/ui/store.js"
click node_projector "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/ui/projector.js"
click node_agent "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/agent.js"
click node_model "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/model.js"
click node_adapters "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/model-adapters.js"
click node_approval "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/approval.js"
click node_attachments "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/attachments.js"
click node_capabilities "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/capabilities.js"
click node_extensions "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/extensions.js"
click node_tools "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/tools.js"
click node_shell "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/shell.js"
click node_vfs "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/vfs.js"
click node_workspace "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/workspace.js"
click node_python "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/shell.js"
click node_network "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/network.js"
click node_telemetry "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/telemetry.js"
click node_persistence "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/persistence.js"
click node_fetchrelay "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/functions/fetch.js"
click node_proxy "https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/functions/proxy.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_store,node_projector,node_user,node_browser toneBlue
class node_agent,node_model,node_adapters,node_approval,node_attachments,node_tools toneAmber
class node_shell,node_vfs,node_workspace,node_python,node_network,node_telemetry toneMint
class node_capabilities,node_extensions,node_persistence toneRose
class node_fetchrelay,node_proxy,node_modelprovider,node_pyodide toneIndigo
```

## Components

### Workspace UI

- [Workspace interface](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/App.vue): `src/App.vue`
- [UI store](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/ui/store.js): `src/ui/store.js`
- [Event projector](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/ui/projector.js): `src/ui/projector.js`

### Agent harness

- [Agent session](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/agent.js): `src/agent.js`
- [Model protocol](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/model.js): `src/model.js`
- [Provider adapters](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/model-adapters.js): `src/model-adapters.js`
- [Approval control](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/approval.js): `src/approval.js`
- [Image attachments](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/attachments.js): `src/attachments.js`
- [Tool registry](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/tools.js): `src/tools.js`

### Browser substrate

- [Compatibility shell](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/shell.js): `src/shell.js`
- [Virtual filesystem](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/vfs.js): `src/vfs.js`
- [Workspace access](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/workspace.js): `src/workspace.js`
- [Python worker](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/shell.js): `src/shell.js`
- [Network runtime](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/network.js): `src/network.js`
- [Execution telemetry](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/telemetry.js): `src/telemetry.js`

### State and extensions

- [Capability composition](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/capabilities.js): `src/capabilities.js`
- [Plugins and skills](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/extensions.js): `src/extensions.js`
- [Browser persistence](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/src/persistence.js): `src/persistence.js`

### External services

- [Public-resource relay](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/functions/fetch.js): `functions/fetch.js`
- [Model API relay](https://github.com/boccchi2993/locus-browser-agent-runtime/blob/main/functions/proxy.js): `functions/proxy.js`

### Other components

- **User**
- **Model provider**
- **Browser APIs**
- **Pyodide**

## Connections

- User → Workspace interface: submits task
- Workspace interface → UI store: invokes actions
- UI store → Agent session: starts task
- Agent session → Model protocol: requests response
- Model protocol → Provider adapters: selects provider
- Provider adapters → Model provider: sends request
- Model provider → Provider adapters: returns response
- Provider adapters → Model API relay: relays request
- Agent session → Tool registry: dispatches tools
- Tool registry → Compatibility shell: runs bash
- Compatibility shell → Virtual filesystem: reads and writes
- Virtual filesystem → Workspace access: mounts folder
- Workspace access → Browser APIs: uses file access
- Compatibility shell → Python worker: executes Python
- Python worker → Pyodide: runs code
- Compatibility shell → Network runtime: runs curl
- Network runtime → Public-resource relay: relays request
- Agent session → Approval control: requests approval
- Approval control → UI store: updates pending state
- Agent session → Image attachments: uses image input
- Image attachments → Model protocol: provides image input
- UI store → Capability composition: enables capability
- Capability composition → Plugins and skills: composes extensions
- Agent session → Execution telemetry: records execution
- UI store → Event projector: projects events
- UI store → Browser persistence: stores session state
- Browser persistence → Browser APIs: uses IndexedDB and OPFS