Section 00 / Architecture Decision Records 000

Architecture Decision Records

Append-only log of load-bearing decisions. One file per decision. Never deleted; superseded.

0001-in-front-not-in Accepted

ADR-0001: kaged sits in front of adjacent operator tooling, not within

0002-web-first Accepted

ADR-0002: Web-first; terminal is a capability, not the product

0003-doc-first-then-tdd Accepted

ADR-0003: Doc-first, then test-driven

0004-runtime-bun-typescript Accepted

ADR-0004: Runtime is Bun + TypeScript

0005-storage-sqlite-default Accepted

ADR-0005: Storage default is SQLite; PostgreSQL is optional

0006-dsl-format Accepted

ADR-0006: Project DSL is YAML with JSON Schema + Zod validation

0007-auth-oauth-sidecar Accepted

ADR-0007: Authentication is an OAuth proxy sidecar in front of the daemon

0008-plugin-model Accepted

ADR-0008: Plugins are subprocesses over JSON-RPC on stdio

0009-sandbox-technology Accepted

ADR-0009: Sandbox technology is bubblewrap; network allowlist is kaged-managed

0010-deployment-modes Accepted

ADR-0010: kaged supports per-user and system-wide deployment, equally

0011-project-portability Accepted

ADR-0011: Projects are portable; operator-local concerns live in local config

0012-agentic-substrate-mastra Accepted

ADR-0012: Agentic substrate is Mastra v1.x

0013-observability-langfuse Accepted

ADR-0013: Observability substrate is Langfuse, self-hosted, optional

0014-llm-providers-via-kaged-llm-shim Superseded by [ADR-0049](0049-provider-store-dynamic-loading.md) (partial — the "hand-written `@kaged/llm` adapters; no `@ai-sdk/` tree" stance is reversed; the "`LanguageModelV2` is the integration boundary" call is preserved and made more central)

ADR-0014: All LLM providers route through @kaged/llm; Mastra integrates via a LanguageModelV2 shim

0015-federated-project-config

ADR-0015: Federated Project Configuration & Resource Resolution

0016-streaming-first-ui Accepted

ADR-0016: Streaming-first UI — live data and operator abort are non-negotiable

0017-guest-principals Accepted

ADR-0017: Guests are first-class identities with daemon-managed credentials

0018-guest-project-grants Accepted

ADR-0018: Guest access to projects is granted via per-project permission sets, not project DSL

0019-workflows-dsl-block Accepted

ADR-0019: Workflows are operator-authored, parameterised DSL artifacts agents invoke

0020-issues Accepted

ADR-0020: Issues are daemon-stored work items routed through operator triage

0021-guest-ui-surface Accepted

ADR-0021: Guest UI lives at /g/* — segregated route tree, distinct app shell

0022-recursive-agents-per-agent-config Accepted

ADR-0022: Agents are recursive; tools and cage are per-agent

0023-project-plugin-lifecycle-hooks Accepted

ADR-0023: Project-plugin lifecycle hooks, per-agent declaration, isolation as a core principle

0024-context-compaction Accepted

ADR-0024: Context compaction is kaged-owned, layered, observable, and operator-tunable

0025-typecheck-orchestration Accepted

ADR-0025: Typecheck orchestrates per-package; root tsc is a marker

0026-cost-management-model-overrides-usage-tracking Accepted

ADR-0026: Cost management, model metadata overrides, and provider usage tracking

0027-linting-formatting-biome Accepted

ADR-0027: Linting and formatting via Biome

0028-oauth-provider-auth Accepted

ADR-0028: 3rd-party OAuth provider auth — token lifecycle and credential management

0029-structured-operational-logging Proposed

ADR-0029: Structured operational logging

0030-log-streaming-sse Accepted

ADR-0030: Log streaming via Server-Sent Events

0031-message-transcript-rendering Proposed

ADR-0031: An assistant turn is an ordered transcript of parts, not a flattened bubble

0032-monaco-editor Accepted

ADR-0032: Monaco Editor as the code editor for kaged UI

0033-tool-dot-namespace-convention Accepted

ADR-0033: Tool dot-namespace convention

0034-issue-bound-todos-and-session-binding Accepted

ADR-0034: Sessions bind to one issue; the issue owns the agent's todos and drives closure

0035-unified-operator-shell Accepted

ADR-0035: Unified operator shell — scope tabs, activity rail, route-driven chrome, and enforced UI primitives

0036-unified-user-identity-shared-sso Accepted

ADR-0036: Unified user identity — shared SSO, three-tier roles, and route-scope authorization

0037-compound-prompts-path-arrays Accepted

ADR-0037 — Compound prompts: every prompt field is string | string[]

0038-workflow-steps-model-overrides Accepted

ADR-0038 — Workflows: mandatory steps, no root prompt, per-level model override

0039-wire-contract-package Accepted

ADR-0039: @kaged/wire is the normative wire contract; daemon and UI must consume it

0040-multi-daemon-operator-ui Accepted

ADR-0040: Multi-daemon operator UI — runtime daemon registry, cross-origin hosting, bearer transport

0041-containerised-daemon Accepted

ADR-0041: Containerised daemon — single-binary build, distribution image, Kubernetes operation

0042-package-distribution-ci-release Accepted

ADR-0042: Package distribution, CI, and the release pipeline

0043-mcp-tool-source Accepted

ADR-0043: MCP as a tool source

0044-skills-integration Accepted

ADR-0044: Skills — declarative agent capabilities as prompt modules

0045-project-wiki Accepted

ADR-0045: Project wiki — markdown knowledge base as a DSL surface

0046-pwa-offline-strategy

ADR-0046: PWA Offline Strategy — Precache UI Shell, Exclude API, Operator-Gated Updates

only changed hashed files re-download; old precache is purged on `activate`. No manual cache-name bumps or `caches.delete()`.

0047-session-notifications

ADR-0047: Session Notifications — Event Routing, Channels, and the Service-Worker Bridge

0048-workflow-branching-loops-logic Accepted

ADR-0048 — Workflows: branching, loops, logic steps, and parameterised tasks

0049-provider-store-dynamic-loading Accepted

ADR-0049: Providers are dynamically-loaded modules from an operator-local store; catalog from a self-hosted models.dev mirror; @kaged/llm becomes resolver + loader + middleware

0050-operator-git-pane Accepted

ADR-0050: Operator-facing git pane for projects

0051-file-editing-overhaul Accepted

ADR-0051 — File-editing overhaul: browser interactions, breadcrumb navigation, and an agentic edit panel

0052-message-regeneration-and-frontend-retry Proposed

ADR-0052: Message regeneration and two-tier, operator-cancellable retry