Resources03 · Client architecture

CLIENT ARCHITECTURE / ONE AUTHORITY

One client. One replayable execution truth

Kyormar is a local-first Agent workspace and IM collaboration client. App owns the service lifecycle, Agent owns execution truth, and every other surface consumes typed contracts

APP COMPOSITION ROOT / CURRENTONE SERVICE AUTHORITY
PRODUCT SURFACE / 01IMpeople · messages · collaboration
MODULE HOSTKYORMAR APPowns lifecycle, not business truth
PRODUCT SURFACE / 02AGENTgoals · tools · execution · replay
NON-CLONE OWNERAgentService

owner thread · Tokio runtime · executor · store lease · recovery

CLONEABLE PORTAgentHandle

typed command · receipt · view · observation

IM / INDEPENDENTAGENT / IN-PROCESSDEVTOOLS / DEBUG READ ONLY
02

STARTUP / COMPLETE BINDINGS OR NOTHING

Start the complete service before handing a handle to the interface

The App shell can show login and IM before opening the Agent store; UI receives AgentRuntimeBindings only after the authenticated session generation is complete and every startup stage succeeds

  1. 01CONFIGRuntime configuration

    Resolve the approved local identity and runtime root without guessing external identity from defaults

  2. 02STOREStore and lease

    Create the canonical Agent store and hold the single cross-process store lease

  3. 03PROFILELocal identity binding

    Device, local profile, and namespace must match completely

  4. 04CAPABILITYCapability catalog

    Assemble the typed registry for tools, Skills, MCP, and host capabilities

  5. 05PROVIDERModel and tool composition

    Connect provider, context, tooling, and execution policy to the same service

  6. 06EXECUTORBackground executor

    Start the single Tokio runtime, executor, and owner thread together

  7. 07RECOVERYRecovery

    Restore tasks, processes, approvals, and visible views from durable commits

  8. 08MEDIA ROOTMedia cache root

    Install the app media-cache path last, then publish complete bindings to UI

03

CANONICAL CHAIN / HOT AND COLD

Every visible state begins with one durable commit

This chain serves both regular Agent and Coding Agent. Tools, approvals, workflows, multi-Agent execution, and managed processes create no parallel writer, projector, or replay truth

  1. ATYPED COMMAND

    UI and CLI submit only complete intents

    Commands must carry explicit identity, selectors, and closed payloads; current selection, titles, text, and array positions are not business identity

  2. BAGENT HANDLE

    The cloneable handle is the only business entry point

    App retains the non-Clone AgentService; UI, CLI, and DevTools receive only bounded typed handles from the same authority

  3. CCANONICAL TRANSITION

    All semantics converge inside Agent

    Regular Agent, Coding Agent, tools, approvals, workflows, and multi-Agent execution share the same transition without a second state machine

  4. DDURABLE COMMIT

    commit_seq exists only after the transaction succeeds

    commit_seq records commit order only and cannot replace complete business identity for sessions, tasks, turns, tools, or effects

  5. ESOLE PROJECTOR

    Each domain has exactly one projector

    Domains such as SessionView and Knowledge each have one reducer; hot updates and cold replay read the same durable facts

  6. FTYPED OUTPUT

    Receipts, views, replay, and observation come from the same commit

    Publication failures become typed Gap or Unavailable states; consumers cannot synthesize empty, completed, or compatibility fallback states

04

CONSUMERS / MECHANICAL ONLY

Every surface knows what it may read—and what it must never own

IM, Server, and DevTools are not backup storage or failure fallbacks for Agent; every cross-boundary path has explicit input, output, and prohibited ownership

SURFACEINPUTOUTPUTDOES NOT OWN
UItyped commandreceipt / session view

Owns only drafts, selections, expansion state, and other UI-only state

CLI / TUItyped commandreceipt / bounded view

Maintains no independent runtime transport, store, or state machine

DEVTOOLSobservation requestcommit / view / receipt

Read-only; owns no writer, projector, cursor, transport, or canonical cache

IMexplicit shareauthorized content copy

Consumes content-free control state by default and does not own Agent execution truth

SERVERverified bindingauth / catalog / billing / policy / relay

Stores no regular prompts, reasoning, timelines, tool arguments or outputs, or file content

05

TEN CRATES / ONE COMPOSITION ROOT

Ten specialized crates do not mean ten runtimes

crates/agent is only a physical grouping directory. The facade package kyormar-agent is the single composition API; App does not assemble implementation crates directly

facadecomposition root

The single assembly point for AgentService, AgentHandle, executor supervision, and host bindings

contract + pathstyped boundary

Commands, views, receipts, identity, failure codes, and controlled path policy

coredurable truth

store, transition, commit, per-domain projectors, replay, memory, and compaction truth

context + providermodel turn

Context assembly, memory consumption, provider loops, model capabilities, and streaming-response normalization

tooling + tools + mcpcapability execution

Policy, approval, scheduling, built-in tools, and the MCP lifecycle all return to durable receipts

workerdangerous isolation

Starts only for one dangerous action and owns no session, task, provider, projector, or replay truth

06

INVARIANTS / FAIL CLOSED

Use these invariants to detect architectural drift

These matter more than having many modules, using Rust, or presenting a consistent interface because they determine recoverability, trustworthy identity, and whether dangerous actions can repeat

ONE SERVICE
The App composition root owns exactly one AgentService lifecycle
ONE STORE LEASE
The service owner thread holds the single store lease until the runtime has fully stopped
COMMIT BEFORE PUBLISH
Receipts, views, and observations are published only after the transaction succeeds
SAME HOT / COLD PATH
Live updates and cold-start replay use the same facts and the same domain projector
FAIL CLOSED
Missing, conflicting, or gapped state returns a typed failure and is never inferred from text or cache
NO CONTENT SERVER
Regular local Agent content stays local; the remote side handles only the content-free control plane
Open Kyormar source Open Kyormar-DevTools