ARCHITECTURE.md

Routing and tool execution, client and profile runtimes, Satellite and computer use, agent loop, context, memory, and reliability. Leon-native skills are layered as Skills -> Actions -> Tools -> Functions (-> Binaries).

ARCHITECTURE

• Generated at: 2026-09-10T02:23:41+08:00
• Leon-native layer model: Skills -> Actions -> Tools -> Functions (-> Binaries).
• Routing model: smart mode auto-selects the best path; controlled mode runs deterministic Leon-native skills/actions; agent mode runs the continuous agent loop and can follow selected agent skills.
• Core runtime: core/brain/brain.ts, llm-duties/react-llm-duty.ts, toolkit-registry.ts, tool-executor.ts.

Core Principles

• Explicit tools over implicit behavior: Leon calls declared tools/functions instead of free-form shell logic whenever possible.
• Progressive grounding: Leon prefers context and memory tools first, then shell only when no dedicated tool can satisfy the request.
• Auditable steps: Leon keeps plan/execution traces, token usage logs, and tool observations so decisions remain inspectable.
• Tools own their dependencies, settings and device behavior. Core and bridge hosts manage execution and transport; shared SDK capabilities stay equivalent across Node.js and Python.

Client Interfaces

• Leon exposes a client-agnostic Socket.IO interface so built-in and custom clients can connect through the same live dialogue contract.
• HTTP APIs remain request/response support surfaces; live profile-scoped utterances should use the Socket.IO client interface.
• External HTTP plugins can extend Leon's HTTP contract without patching the core API for each integration.
• Custom clients can read profile-owned extension JSON files through a generic redacted HTTP endpoint, covering skill memory, skill settings, and tool settings without exposing secrets.

Profile Runtimes

• One Leon server can serve multiple profiles concurrently, with each request and agent turn bound to one profile for its full asynchronous lifetime.
• Runtime services are created lazily per profile, while config, secrets, sessions, memory, context, skills, tools, settings, and logs remain isolated in profile-owned paths.
• A <profile>:<token> credential selects and authenticates the profile across Socket.IO clients, HTTP integrations, and Leon Satellite.

Leon Satellite

• Leon Satellite is an optional process on a user device that connects its enabled and available profile tools to a remote Leon server.
• Eligible tool calls are routed through Satellite and executed on that device; those tools become unavailable when Satellite disconnects.
• Satellite provides generic transport only. Device-, application-, and company-specific behavior stays in tools and skills instead of Leon Core.

Browser & Computer Use

• The browser_use toolkit uses Browser Use CLI for direct browser inspection and actions in the configured browser session. Cua handles graphical application control locally or through Leon Satellite, retaining its session and cleaning up native resources through the worker host.
• Computer use respects owner app preferences and permissions, adapts to platform capabilities, and uses observed results to verify actions and recover from ineffective attempts.

Agent Loop

• One continuous provider tool-calling transcript carries the owner request, assistant tool calls, matching tool results, recovery decisions, and final answer.
• Tool schemas load progressively from the toolkit catalog as the task needs them.
• The baseline prompt keeps stable behavioral instructions before volatile runtime state and exposes one-line context summaries; full context files and Agent Skill instructions load only when relevant.
• The model-facing transcript has a fixed input budget: large tool results stay in artifact logs with bounded previews, and inactive toolkit schemas plus older completed tool exchanges are compacted progressively only when needed.
• Checkpoints and summaries preserve task state as transcripts grow or work resumes.
• Tool state is separated: installed tools exist in the registry, enabled tools are not disabled by the owner, and available tools have the required settings to run.
• Deterministic runtime guards validate and repair arguments, block duplicate calls, execute tools, and return every success or failure as a structured observation to the same loop.
• Plans track scope, collection coverage and verified outcomes; their worklists persist through checkpointing and continuation.
• The agent can share progress updates alongside tool calls during longer tasks.
• Clarification pauses preserve the transcript, plan and execution state so the owner reply can resume the same task.
• Each profile can configure the total agent iteration budget. Reaching the limit preserves progress and reports incomplete work without requesting renewed approval.
• Completion review checks task evidence and plan progress before accepting a final answer; unfinished work continues when possible.
• Model failures use bounded recovery before reporting an unresolved blocker.
• Leon has a living personality and a changing mood that influence its tone and behavior.
• A bounded private self-model/diary is updated after turns, promotes repeated habits into stable behavioral principles, and injects only a compact snapshot into the first agent request.
• A periodic pulse manager can generate autonomous agent matters from memory, context deltas, and the private self-model, persist them to PULSE.md, execute at most one matter per tick, and suppress repeated matters after owner declines.

Context Intelligence

• Leon maintains runtime context files (system, activity, browser, network, workspace, habits, inventory, media, architecture, identity).
• Leon uses structured_knowledge.context.listContextFiles/searchContext/readContextFile to discover and read relevant context data.
• Leon uses structured_knowledge.sessions.searchSessions to search raw prior turns by concrete concepts and inspect nearby messages without replaying the full archive.
• Context-first policy: for runtime/environment questions (VPN, system state, apps, browsing), Leon inspects context before memory/shell.
• Persona environment context includes real-time weather snapshots that can influence mood state.

Memory System

• Memory is layered into persistent, daily, and discussion stores, with context files available as a separate grounding source.
• OWNER.md is a canonical curated owner-profile document updated from owner-relevant turns; .owner-profile.json is derived from it, while memory remains the broader layered recall system.
• Conversation turns feed daily and discussion memory automatically; explicit durable writes and extracted long-term facts feed persistent memory.
• Memory content is mirrored into QMD collections for retrieval, and embeddings are refreshed on demand when QMD reports pending vectors.
• Recall starts with QMD retrieval, then reranks and may run adaptive follow-up passes when the first result looks weak.
• Read priority stays grounded: context for environment/runtime facts, memory for personal history/preferences, raw session search for exact prior evidence, and shell as a last resort.
• Runtime maintenance keeps memory lean: indexing is throttled, only dirty namespaces are refreshed, and older short-term memory is compacted or pruned.

Reliability

• Schema-guided tool calls and argument repair reduce malformed executions.
• Duplicate-input guards and observation-driven recovery reduce repeated bad calls while preserving successful progress.
• Leon prefers dedicated tools over shell commands to keep behavior stable and auditable.