Kernel Internals

⚫ A document for those who write or modify the kernel code itself. The full specification is in SPEC.md (English, source of truth); here is a brief map. Semantics come from the sources agent_os_core.

14.1 Model

The kernel is a single async runtime (Tokio) with an event loop that:

1. maintains a process table (DashMap<Pid, AgentProcess>);
2. calls the scheduler (schedule() → ScheduleDecision) on every tick;
3. dispatches turns (run_turn(pid)), invoking the provider and running the tool-call loop;
4. limits resources (budgets, groups, concurrency limit) before dispatch;
5. routes IPC;
6. mediates every tool call;
7. emits events to listeners;
8. manages sessions (SessionRegistry).

The kernel holds optional service handles, wired in once at load time by the host (message_store, state_store, provider, pricing, etc.) — if a handle is not wired in, the corresponding syscalls respond "not configured".

Modularity. Features (cron, workflow, connectors, memory, model_router, channels, …) have been moved out of the kernel into modules and are wired in as host ports. Instead of the typed fields cron_service/workflow_service/connector_service on Kernel, there is now a single neutral seam kernel::KernelServices, which the host fills from the ports agent_os.Cron / agent_os.Workflow / agent_os.Connectors (kernel.services().set_*). The kernel does not depend on any single feature; details are in docs/27-core-modularization.md §5 and 32-building-a-module.

Load cycle:

loop {
    decision = schedule()
    match decision {
        Run(pid)       → run_turn(pid)
        Idle           → sleep(50ms)
        AtConcurrencyLimit → sleep(50ms)
        Shutdown       → break
    }
}

14.2 Core Abstractions

Process State Machine

spawn → Created → (init) → Ready ⇄ Running → (exit) → Terminated
                              │
                              └→ Blocked{reason} → (unblock) → Ready

• Created — allocated, not initialized.
• Ready — waiting for the scheduler (is_runnable()).
• Running — consuming inference.
• Blocked { reason } — waiting for an external event (tool result, IPC, input).
• Terminated { exit_code } — finished (0) or killed (≠0).

Turn and Tool-Call Loop

1. The kernel selects process P.
2. It sends P's context + the latest tool results to the provider.
3. The provider streams tokens.
4. If the LLM requests a tool call, the kernel pauses the stream, validates the call, executes the handler (with a deadline), adds the result as a tool message, and resumes inference.
5. The turn ends when the agent yields, blocks, its quantum expires, or its budget is exhausted.

Concurrency is metered by Semaphore only around provider.stream — tool calls and hooks run without a permit, so a slow tool does not "starve" other sessions.

Context Window

ContextWindow { max_tokens, messages, eviction, summary }. Eviction policies: Fifo (drop old ones), SummaryFirst { keep } (collapse old ones into a summary, default keep=8), SlidingWindow { n }. Eviction also cleans up orphaned tool results whose parent assistant message has been removed.

Budgets

TokenBudget { max_per_turn, bucket: TokenBucket, max_total, … }. TokenBucket — a classic leaky bucket (capacity + refill_rate). A group BudgetGroup adds two optional layers: per-user (a sub-bucket per user_id) and per-session. Check before dispatch: group → per-user → per-session (can_consume_for); an exhausted layer — BudgetLevel::{Group,User,Session}.

IPC and Syscalls

MessagePayload: Text, Json, Signal (Terminate/Pause/Resume/Interrupt), SpawnRequest, SpawnResult.

Syscalls: Spawn, Fork, Kill, Yield, Send/Recv, ToolCall, SetState/GetState/DeleteState, Checkpoint/Restore.

Hooks

HookHandler with points: before_user_message (transform/inject/suppress/reply/ notice), before_tool_call (rewrite args / deny / short-circuit), after_tool_result (redact/transform), before_inference (request mutation; deny → block, response → synthetic response), before_retry (allow/deny retry + backoff), before_syscall (syscall/IPC filter, deny), after_turn, after_assistant_message (output guardrail), on_token (streaming moderation), before_context_evict (custom compaction), after_loop, on_spawn/on_terminate/on_error, on_session_created/on_session_closed, on_budget_threshold. Plus merge_user (identity merging), memory_inspect (inspection), apply_feedback (like/dislike).

Composition: Hook.priority (higher — earlier), enabled, activation conditions when { templates, agents, users, sessions }, global (directory config/hooks/*.yaml). Every call goes through Kernel::run_hook (catch_unwind + timeout hook_secs) and is accounted for in HookMetric per pair (hook, point) (GET /v1/hooks/metrics). HookOutcome { inject, replace_message, reply, notice, suppress }.

14.3 Scheduler

SchedulingPolicy: RoundRobin (default), PriorityPreemptive, FairShare, DeadlineDriven. Scheduler { policy, time_slice, max_concurrent }. ScheduleDecision: Run(pid) | Idle | AtConcurrencyLimit | Shutdown.

14.4 Inference Provider

trait InferenceProvider {
    fn provider_type(&self) -> &str;
    async fn stream(&self, request) -> Result<Box<dyn Stream<Item=Result<InferenceEvent, InferenceError>>>>;
}
enum InferenceEvent { Token(String), ToolCall(ToolCallRequest), Done(InferenceStats) }

The concrete implementation is OpenAiProvider (reqwest + SSE). Pricing estimates cost from statistics.

14.5 Storage Subsystems

14.6 Events and Listeners

The kernel emits typed ProcessEvent through the bus: TurnStart, Token, ToolCall, ToolResult, ToolProgress, TurnEnd, StateChange, Error, Spawned, Terminated, BudgetConsumed, BudgetExhausted, RateLimited, ScheduleBlocked, session lifecycle events, Cost, workflow steps. Listeners implement ProcessListener (all methods are no-op by default).

14.7 Loading

1. The host loads the config and builds Kernel.
2. ToolRegistry registers built-in and user tools; HookRegistry — hooks.
3. InferenceProvider connects to the LLM.
4. Service handles are connected (message_store, state_store, cron_service, workflow_service, pricing).
5. Agent templates are loaded (built-in + YAML).
6. Bootstrap agents are spawned (or lazily on the first session request).
7. The scheduler loop starts.
8. The host listens for external requests (HTTP + SSE).

14.8 Design decisions

1. Cooperative multitasking by default; preemption is optional.
2. spawn and fork — both supported; fork always inherits the budget group.
3. Cost accounting at the tool level — each ToolResult carries ToolCost.
4. I/O through the core — agents never call tools directly.
5. Opt-in subsystems — when not connected, they respond "not configured" rather than crashing.

14.9 Non-goals

Multi-tenancy (one instance = one tenant), distributed scheduler, fine-tuning, graph workflows in the core (that's the server layer), real-time guarantees.

14.10 Source map

14.11 Build and tests

Cargo workspace of three crates:

cargo build                       # debug-сборка всех бинарников
cargo run --bin agent-os -- serve # запуск сервера (грузит config/server.yaml)

cargo test -p agent_os_core       # юнит-тесты ядра/инструментов/хуков
cargo test -p agent_web_bot       # тесты сервера, auth, proxy, login, sessions
cargo test -p agent_web_bot --lib # HTTP-слой (роутинг, auth, login, access-лог)

The widget in widget/ is built automatically build.rs at agent_web_bot (via npm) — a separate npm run build is not needed. Integration tests crates/host/tests/ require a live LLM key and are not run by default.