Skip to content

Latest commit

 

History

History
163 lines (161 loc) · 23.9 KB

README.md

File metadata and controls

163 lines (161 loc) · 23.9 KB

Architecture decision records

Each record states one accepted decision: its context, the decision, the alternatives rejected and the consequences. Records are not edited after acceptance; a later record supersedes an earlier one.

# Decision
0001 Settings are typed sections owned by the crates that use them
0002 Item commands are GPUI actions dispatched to the command item
0003 Terminals reach saved credentials through a port
0004 Persisted files share one bounded write queue
0005 The agent runtime is a service crate reached through a client port
0006 The side panel is a state machine; tabs open through a session factory (side-panel slot superseded in part by 0081)
0007 One bootstrap for the application and its GUI tests
0008 Function size and complexity limits shrink a grandfathered list
0009 A chat's composer state is kept apart from its conversation
0010 A chat's session is a pure state machine, connected when shown
0011 A chat owns its configuration, and every shown chat connects
0012 Architectural debt is an exact inventory that may only shrink
0013 Ordered persistence and quit capture belong to a service
0014 Vendored sources replay from authenticated archives and ordered patches
0015 Private file publication shares one staged, atomic mechanism
0016 Vault format and rules are independent of storage and lifecycle
0017 Native filesystem capabilities are injected through pure session ports
0018 Transfer execution is an adapter over held filesystem and retryable publication ports
0022 Agent storage adapters and private lifecycle owners share persistence execution (numeric history ceilings superseded by 0164)
0025 External local programs have an explicit bounded native owner
0026 Workspace transitions belong to private state owners with explicit shared layout (Sidebar and RightPanelSlot superseded in part by 0081)
0027 Pure connection observation contracts and network I/O adapter
0028 Pure theme domain model, adapter registry and theme service
0029 Bounded append persistence and output recording
0031 Hydrated archive and history permit state belong to a single owner (numeric resident ceiling superseded by 0164)
0032 Separate terminal ports bind approvals and secret answers to original Item/session/prompt epochs
0033 Inject native workspace preparation and fail-closed sandbox launch capabilities
0034 Per-chat configuration and composer transitions have private feature owners
0035 Inject bounded native image codecs and bind preview delivery to request generations
0036 Connection documents and native values use explicit domain ports
0037 Durable chat revisions, pending candidates and capture have separate ownership
0038 Private terminal state owners commit input and presentation after captured session admission
0039 Remote OS observation uses checked identities and an injected bounded adapter
0040 Native chat identity and timestamps use explicit host capabilities
0042 Terminal sessions retain explicit installed providers and settings across windows
0043 Connection views retain explicit owners, settings and subscription lifetimes
0044 Private chat owners return named coordination effects
0045 Private panel view owners retain controls and original completion authority
0046 Shared error causes retain the original concrete error in standard source chains
0047 Connection publication service preserves committed profile authority histories
0048 Original-source guarded raw facts and bounded connection jobs
0049 Private panel membership, notice tasks and finite presentation operations
0050 Snippet views retain their original installation and private draft controls
0051 Keymap pages and directory actions retain supplied ownership across windows
0052 Agent views retain runtime, policy and host installation authority
0053 Settings UI retains its supplied settings installation
0054 Native settings text owns checked publication receipts
0055 Native snippet documents and viewless publication have separate owners
0056 Settings controls and pure schemas live with their actual owners
0057 Checked ordered settings catalogs and explicit settings composition (page list and navigation superseded in part by 0086, Appearance sections by 0087)
0058 Agent protocol types stop at the ACP adapter
0059 Architecture rules are applied through committed procedure skills and guards (orchestration/resources superseded by 0132; procedures refined by 0135)
0060 SSH jump-host routes are resolved from saved profiles before opening and established by the SSH adapter
0061 Agent profiles, an injected catalog and one directory of available agents
0062 Terminal and connection contracts live below the window shell
0063 Agent chats live in a service crate below the panel
0065 Context surfaces retain their native dock and original callback authority (whole-window selection superseded by0067)
0066 Scoped chat authority precedes payload discovery in versioned storage
0067 Workspaces are outer connection tabs with independent inner terminal surfaces (footer order superseded in part by 0083)
0069 Workspace chat scope preserves the existing local agent launch lifecycle
0070 Workspace authentication belongs to its inner terminal
0071 Workspace locations retain provider identity and session authority
0072 Directory selection shares read-only rules, adapters and controls
0073 Terminal-free workspace creation uses explicitly injected local authority
0074 Image search and language versions retain captured host authority
0075 Workspace tool changes retain explicit environment authority
0076 Container files use a scoped session filesystem capability
0077 Resource monitoring follows the selected workspace environment
0078 Explicit workspace container actions precede checked metadata removal
0079 Project terminal contracts live below the shell with captured typed placement
0080 Project resource, environment and filesystem adapters have separate owners
0081 Panel groups own the window's side panels
0082 Built-in shell contributions are core or belong to a system plugin in one checked catalog
0083 The status bar is zoned and drawn from a layout resolved against the plugin catalog
0084 Layout presets are app-wide settings that every window follows
0085 System and user plugins share one contribution and settings model, with separate trust tiers
0086 Plugin enablement is app-wide and the Plugins page lists plugins with their own pages nested under it
0087 The status bar and panels are edited in Appearance through the layout rules
0088 The wall clock is a foundation contract read by a local adapter, and the Clock is a plugin
0089 User plugins are declarative packages over a closed, isolated contract (the label inside a panel superseded by 0154)
0090 The plugin host brokers every effect, and providers only read what the UI already shows
0091 User plugin code runs in-process on wasmi behind the runtime port
0092 The plugin SDK is a guest-only crate, and a developer session keeps its plugin and settings in memory
0093 User plugins start off, safe mode beats the switch, and the API surface stays compatible (a held run without the install button superseded by 0153; the separate User section superseded by 0154)
0094 Panels stand alone or in groups the user makes, and the bar preview is the editor
0095 Attached sessions restore their screen and detach on close
0096 The hub contract lives outside the workspace and only the hub adapter speaks it
0097 A window belongs to one environment, local or one hub (superseded by 0099)
0098 Windows and their environments are restored after a restart (superseded by 0099)
0099 Windows have no environments: hub sessions live in the ordinary window (supersedes 0097 and 0098; superseded by 0104)
0100 The hub is a route step: the first connection of an SSH route can be a relay (relay node superseded by 0148)
0101 Profiles synchronize through a replica beside the local document (scopes superseded by 0149)
0102 SSH keys are kept in the vault; the editor receives them through VaultSshKeys
0103 Account data is sealed on the device: the hub keeps ciphertext, and one chosen server keeps the vault and the profiles
0104 A window shows one environment: this computer or the account of one hub (supersedes 0099)
0105 Provider usage reaches Nocterm only through ACP (partially supersedes 0061)
0106 Terminal byte state and command execution have shared headless owners
0107 Cloud run authority and effects have pure owners and host-controlled ports (superseded by 0148)
0108 Cloud API engines expose completed turns to the host (superseded by 0148)
0109 Cloud commits and retained effects share one native durable journal (superseded by 0148)
0110 Local history captures its device or account environment
0112 Purpose-bound SSH login and captured connection sources (superseded by 0148)
0113 A native journal belongs to one account/runner and authenticates its complete chat catalog (superseded by 0148)
0114 Native account workers and displayed confirmations retain their original recipient
0115 Physical terminals outlive immutable run views (superseded by 0148)
0116 Cloud retention activates a stored signed baseline before deleting its native prefix (superseded by 0148)
0117 Cloud local tools receive an explicit contained process capability (superseded by 0148)
0118 Cloud hub trust bootstraps from the normal encrypted account (superseded by 0148; earlier: device-flow freshness and work leases superseded by 0144)
0119 A personal SSH CA lets cloud agents reach the user's servers (superseded by 0148; earlier: single principal superseded by 0145; desktop CA signer and document by 0147)
0120 The Cloud agent catalog lives in the new-chat menu (superseded by 0148)
0121 Managed pools are a trusted gateway with per-lease broker tokens (superseded by 0148)
0122 Cloud chats are created on the device and claimed by the runner on key admission (superseded by 0148)
0123 The managed runner reads per-chat broker tokens from a framed control channel (superseded by 0148)
0124 Managed execution runs tools in nested containment behind the host broker (superseded by 0148)
0125 Account-key lock port, journal v6 horizon and own-runner placement (journal version rule superseded by 0143; journal horizon and own runner superseded by 0148)
0126 A device leases a personal agent's key to the own runner (superseded by 0148)
0127 The managed runner enforces the agent definition policy from boot v2 (superseded by 0148)
0128 Agents transfer files through the shared transfer runtime, relaying between servers
0129 The device allows a queued Cloud run to use the model (superseded by 0148; earlier: projection placement superseded by 0144)
0130 Cloud agents are offered only in the window of their hub (superseded by 0148)
0131 One container watch per host connection, relisted only for listing changes
0132 Agent procedures scale to impact and machine resources remain local (supersedes process/resource rules of 0059; document organization refined by 0135)
0133 Cloud chats are listed in the history column, and a prompt wakes its seat (superseded by 0148; earlier: row titles and projection superseded by 0144)
0134 One composer for every conversation, and pending prompts in the transcript (superseded by 0148; earlier: projection placement superseded by 0144)
0135 Agent procedures verify responsibility and runtime cost; gate owns the detailed check matrix
0136 Bounded byte collection and terminal-tool result formats have shared owners
0137 Settings and profiles reject publication against an externally changed owned document
0138 Resource monitoring shares one raw collection per captured executor and scope
0139 SFTP authorized-keys editors coordinate with a fixed no-clobber remote lock
0140 Displayed key confirmations await bounded native publication
0141 Plugin records select immutable package versions and await actual completion
0142 Live transcript and image preparation admit aggregate growth before expensive work (numeric transcript byte ceiling superseded by 0164)
0143 The runner publishes signed chat summaries to its directory; journal v7 (superseded by 0148; earlier: journal version rule superseded by 0145)
0144 The device side of Cloud chats runs on the contract's device core; hub-io is a thin adapter (superseded by 0148; earlier: request signer, outbox and first-freshness rule superseded by 0146)
0145 Per-server CA principals, chat SSH bindings and runner certificate sessions; journal v8, boot v3 (superseded by 0148; earlier: SSH row class, boot host-key rule and journal version superseded by 0147)
0146 Cloud effects go through the hub client; commands resume after a restart (superseded by 0148)
0147 The desktop binds chats to servers and answers their certificate requests; prompts run on bound servers; journal v9 (superseded by 0148)
0148 Hub chats run on the hub and use the agent chat UI; the Cloud runner, organizations and administrator keys are removed (Agent access without an open session superseded by 0149; the web panel's credential used once superseded by 0150)
0149 Agent access connects with the saved credentials, rows show the agents' state, and profiles have one space (supersedes parts of 0101 and 0148)
0150 An account's servers keep their secrets in its vault: the web panel saves what it connects, the editor keeps a typed password, no list of unsaved agent servers (supersedes part of 0148)
0151 A saved password signs in to the servers it lists; records are renamed and passwords shared without their secret
0152 Every window lists every chat; a resting chat moves to the window that opens it, a working or shown one is shown in its own window
0153 Toolbars along the tab area; user plugins send requests to an address the user typed with a secret they never read, set timers and own terminal tabs an AI chat can attach to; the Plugins page installs from a button or the plugins folder (supersedes part of 0093; its two switches superseded by 0154)
0154 Plugin views are built from the application's components and glyphs, the shell writes a panel's provenance beside its title, effects apply after the host's update, and external plugins share the Plugins list with one switch (supersedes parts of 0089, 0093 and 0153)
0155 A plugin's terminal tab can serve files: the file browser and attached AI chats use them through the session's file system, requests and answers are checked both ways, and bytes travel as base64
0156 Agents read and change the files of attached terminals that serve files but run no programs, through MCP file tools a chat offers only while such a terminal is attached
0157 A plugin's terminal tab carries the plugin's bar along one edge (terminals.bar), drawn by the contribution the tab reports to with the snapshot naming the terminal; the ABI stays 1
0158 A plugin's toolbar keeps to its own tabs unless it names tabs = "all", shown only suggests where it starts, and the user moves or hides it under Toolbars (amends 0153 and 0157)
0159 Plugin views draw charts of recent values (chart, ABI stays 1), a toolbar's calls name its axis in the zone (cx.is_column()), toolbars use the status bar's small text, and moving a toolbar is a layout edit
0160 CI compiles each kind of build once (lint checks, build and tests), tests user-plugins only in the packages that declare it, saves caches from dev and master, and builds installers only for releases
0161 User plugins ship in every build: the user-plugins cargo feature and the compile-out rule are gone, the [plugins] user_plugins switch and --safe-mode still decide whether a run loads them (supersedes the compile-out part of 0093)
0162 Windows strict local filesystem capabilities hold every ancestor's handle without delete sharing and refuse reparse points, so new v3 chats save on Windows; a failed save names its class (amends 0110; acquisition/publication guarantees superseded by 0165)
0163 Windows agents start without a console window, the agent environment matches Windows names without case, and bare commands such as npx are also looked for in the usual Node.js locations
0164 Installation history capacity is separate from a single document; larger byte and row ceilings supersede numeric limits in 0022, 0031 and 0142
0165 Windows pins native ancestry, preserves full file identity and guards publication against reparse conversion (supersedes the guarantees in 0162)