Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
84 lines (64 loc) · 4.47 KB

ARCHITECTURE.md

File metadata and controls

84 lines (64 loc) · 4.47 KB
Raw

中文

Maka Backend Architecture

Maka has one execution authority: Runtime Host. Desktop, TUI, CLI, bots, and evaluation clients ask Runtime Host to execute work; none owns a second Runtime.

flowchart LR
    C["Desktop / TUI / CLI / Bot"] --> H["Runtime Host"]
    H --> S["SessionManager"]
    S --> R["AgentRun + RuntimeKernel"]
    R --> T["Tool Runtime"]
    R --> L["Runtime Event Log"]
    S --> G["Agent Graph Control Plane"]
    G --> R
    L --> P["Context / Session / UI / Recovery projections"]

    E["@maka/eval\nExperiment → Cells → Attempts → Results"] --> H
    X["External subjects"] --> E
Loading

Runtime Host owns Session and Turn identity, agent lifecycle, continuation, tools, permissions, and events. @maka/eval owns benchmark experiment semantics only: subjects, tasks, repetitions, cells, immutable attempts, result selection, budgets, and verifier configuration. A Maka subject always crosses the public Runtime Host client/protocol boundary; an external competitor is a generic external subject.

Runtime layers

  1. Runtime Event Log is the canonical source for model messages, tool calls, tool results, and termination facts. Context pruning and compaction change provider input projections, not history.
  2. SessionManager and AgentRun own execution lifecycle. Runtime Host owns admission, client capabilities, interactions, and the public protocol.
  3. Agent Graph schedules dependent work using child Sessions and sends every activation back through the same Runtime.
  4. Storage owns interactive Runtime state. It has no Eval-specific root, TaskRun ledger, or experiment result authority.

Eval boundary

Experiment = benchmark + executor + subjects + tasks + repetitions
Cell       = task × repetition × subject

repetition   = a new experimental sample
infra retry  = a replacement attempt for the same cell
continuation = internal Runtime Host behavior within a Maka subject

One Experiment uses one fully expanded declarative spec. Every arm shares its executor, benchmark, tasks, budget, and verifier. A/B is simply a two-arm Experiment. Harbor and Pier are executor adapters, not independent workflows.

The result kernel contains only score, normalized usage, attributable cost, duration, status or failure reason, and artifacts. When a cell has multiple attempts, the earliest valid attempt is authoritative; operators cannot choose a preferred outcome.

Code boundaries

Area Responsibility
packages/core Pure Session, Runtime Event, AgentRun, permission, and protocol contracts
packages/storage Interactive Runtime stores and SQLite control planes
packages/runtime SessionManager, AgentRun, model adapters, tools, context, recovery, and Graph reconciliation
packages/runtime-host Sole hosted execution authority and public client/protocol
packages/eval Experiment cells, attempts, result selection, and subject/executor adapters
packages/cli TUI, maka run, and the public maka eval route
apps/desktop/src/main Electron composition and product-entry adapters

Reading paths

Historical designs remain under docs/archive. Current GitHub issues and source take precedence over older drafts.