engine

Overview ¶

agent_controller.go — AgentController interface and shared types for the agent-state API surface.

This file breaks the import cycle between the engine MCP layer (which exposes the tools) and the root package (which owns the actual *ServeAgent goroutine). The root package implements AgentController in a thin adapter (see root: serve_agents.go) and injects it into the MCP server via NewMCPServerWithAgentController.

Design rationale (see Agent T's design spike, cog://mem/semantic/surveys/2026-04-21-consolidation/agent-T-agent-state-design):

• Identities are static YAML (AgentProvider reconciles them; they don't run).
• Sessions are external-client conversational contexts (Agent P's lane).
• Agents are kernel-internal goroutines — the ServeAgent singleton today.

This interface surfaces the agent. It does NOT surface identities or sessions; those are separate APIs.

agent_state_query.go — query helpers for the agent-state API.

Pure functions that operate on the AgentController interface. Keeping them in a separate file makes it clear what logic lives in the engine layer (validation, clamping, tool/HTTP marshaling) versus the root package's adapter (which actually reads *ServeAgent state).

benchmark.go — foveated context benchmark runner

Measures context assembly quality against a set of prompts with known expected CogDoc matches. For each prompt it records:

• Recall: fraction of expected docs that appeared in the assembled context
• Precision: fraction of injected docs that were expected
• Assembly latency (ms)
• Total token count of assembled context
• Model response (for manual quality review)

Run with: cogos-v3 bench [--prompts path] [--model name] [--budget n]

blobs_cmd.go — CLI commands for blob store management

Usage:

cogos-v3 blobs list              — list all stored blobs
cogos-v3 blobs store <file>      — manually store a file
cogos-v3 blobs get <hash> <out>  — retrieve blob to file
cogos-v3 blobs verify            — check all pointers have matching blobs
cogos-v3 blobs gc [--dry-run]    — garbage collect unreferenced blobs
cogos-v3 blobs init              — initialize the blob store

blobstore.go — Content-addressed blob store for CogOS

Stores large binary content (PDFs, audio, model weights) outside of git in a content-addressed directory at .cog/blobs/. Files are addressed by SHA-256 hash and stored with a 2-character prefix directory for filesystem efficiency.

Layout:

.cog/blobs/
├── a1/
│   └── b2c3d4e5f6...    (blob content)
├── manifest.jsonl        (index of all stored blobs)
└── .gitkeep

The blob store is gitignored. CogDocs reference blobs via pointer files (type: blob.pointer) that carry the hash, size, and content type.

bus_consumers.go — consumer cursor registry for the bus surface.

Track 5 Phase 3: port of the consumer-cursor portion of root's bus_stream.go (ADR-061 server-side consumer position tracking). Kept in a separate file from the SSE broker for readability — the two surfaces cooperate but are decoupled.

Persistence layout:

{workspace}/.cog/run/bus/{bus_id}.cursors.jsonl   — append-only log, last
                                                    entry per consumer wins

bus_session.go — per-bus session manager + hash-chained event log.

Track 5 Phase 3: ported verbatim from the root package's bus_session.go so that the `/v1/bus/*` HTTP surface lives in engine. The storage layout is identical to root:

{workspace}/.cog/.state/buses/
  registry.json                     — bus metadata catalogue
  {bus_id}/events.jsonl             — append-only hash chain (one CogBlock/line)

Bus events use pkg/cogfield.Block as the wire type; the hash chain is per-bus (distinct from the ledger chain in ledger.go — do NOT merge).

Byte-compat with root: the canonical form used for hash computation and the event JSON shape must stay identical. The bridge at cog-sandbox-mcp/src/cog_sandbox_mcp/tools/cogos_bridge.py reads:

{v: 2, bus_id, seq, ts, from, type, payload, prev_hash?, prev?, hash}

bus_stream.go — bus-session-backed SSE broker (parallel to the ledger EventBroker in eventbus.go).

Track 5 Phase 3: library-only port of root's bus_stream.go broker so that AppendEvent can fan out to SSE subscribers. No HTTP route is registered in this phase — PR #16 already owns `/v1/events/stream` (ledger-backed). The broker exists here so future work (or a caller that wires its own SSE handler) can subscribe to per-bus events without re-running the port.

This surface is intentionally distinct from the ledger EventBroker:

EventBroker  (eventbus.go)      — ledger-append events, hash-chain over all events
BusEventBroker (this file)      — per-bus events from .cog/.state/buses/{id}/events.jsonl

Per I2 the two chains stay separate.

canvas_embed.go — embeds and serves the canvas-based dashboard

The canvas view is served at GET /canvas from the v3 daemon. It provides an infinite-canvas spatial interface with draggable nodes, real-time chat, and CogDoc visualization.

chat.go — interactive chat REPL

Two modes:

--direct  Calls OllamaProvider directly (no daemon needed). Useful for
          offline testing or when the daemon isn't running.
(default) POSTs to the running daemon at localhost:PORT/v1/chat/completions
          and streams the SSE response to stdout.

Usage:

cogos-v3 chat              # connect to daemon on default port 6931
cogos-v3 chat --port 6931  # explicit port
cogos-v3 --port 6931 chat  # flags must precede subcommand name
cogos-v3 chat --direct     # bypass daemon, talk directly to Ollama

chunk.go — Turn-aware document chunking for CogOS v3

Splits CogDoc content into chunks suitable for embedding. Conversations (ChatGPT exports, Claude sessions, etc.) are chunked by turn boundaries so that no chunk splits mid-turn. Non-conversation content falls back to paragraph/character-based chunking.

The target chunk size is in characters (~500 tokens at 4 chars/token). A single oversized turn becomes its own chunk regardless of target.

main.go — CogOS v3 kernel entry point

Starts the continuous process daemon. Three goroutines run concurrently:

1. process.Run(ctx) — the cognitive loop (field updates, consolidation, heartbeat)
2. server.Start() — the HTTP API

Flags:

--port        API port (default 6931; v2 is 5100)
--workspace   path to workspace root (auto-detected from cwd if omitted)
--config      (reserved for future use)

cli_emit.go — `cogos emit` subcommand: ledger-append for hook-fired events.

Supports two invocation shapes, both historically dispatched by the root package's `case "emit":` (cog.go:5625 → cmdEmit at cog.go:2621).

Hook-style (the live form, used by .cog/hooks/* via lib/cog_emit.py):

cogos emit --json '{"type":"SESSION_START","session_id":"…","data":{…}}' \
           --identity system --source hook

Handler-style (historical, used by SDK event client and manual invocations):

cogos emit <event-name> [--dry-run]

Phase 1 of Track 5 (per Agent I2's revised dead-code plan): this engine implementation exists alongside the root `cmdEmit`. The root binary still dispatches to root's path today; once Phase 4 flips the Makefile default build target to cmd/cogos/, the engine path takes over for the installed `cogos` binary. Hook invocations must continue to succeed at every step of the cutover.

Engine-side behavior vs root:

• Hook-style (--json path): engine ACTUALLY writes the event to the per-session ledger via AppendEvent (hash-chained). Root silently accepted these flags but treated "--json" as the event name and fired no handlers — so on-disk effect was zero. This is a strict improvement: hooks always returned 0 under root, and they continue to return 0 here, but now the event actually lands in the ledger.
• Handler-style (<event> [--dry-run] path): engine emits a noop for now (no handler index port in Phase 1; events dir is empty in live workspaces). Root's path is retained until Phase 5 sweep.

cli_mcp.go — `cogos mcp serve` subcommand: run the engine MCPServer on stdio.

Phase 2 of Track 5 (per Agent I2's revised dead-code plan): this engine implementation exists alongside the root-package `cmdMCP` (mcp.go). The root-linked `cogos` binary still dispatches to its own path today. Once Phase 4 flips the Makefile default build target to cmd/cogos/, `cogos mcp serve` will naturally route through here.

Byte-compat and feature diff vs root:

• Transport: both use stdio with newline-delimited JSON-RPC 2.0. Root implements the JSON-RPC loop by hand (mcp.go:515 Run); engine uses the upstream modelcontextprotocol/go-sdk StdioTransport which speaks the same wire format.

• Tool catalogue: root's cmdMCP registers the 4 kernel-native tools (memory_search / memory_read / memory_write / coherence_check) plus the bridge-mode external-tool loader. Engine's MCPServer registers the FULL engine tool catalogue (20+ tools including ledger, traces, config, agent-state, kernel-slog, tool-calls, conversation, event- bus) via registerTools in mcp_server.go.

  This is a strict super-set; every root tool has an engine equivalent. When the Phase 4 Makefile switch lands, `cogos mcp serve` users get the richer surface without any additional work.

• Bridge mode: root's --bridge flag (OpenClaw gateway) is not mirrored in Phase 2. It is scoped for a follow-up if/when needed; bridge mode is not used by the kernel-native workflow.

Lifecycle:

cogos mcp serve [--workspace PATH]

Workspace resolution mirrors other engine subcommands (auto-detected via findWorkspaceRoot when --workspace is absent). The server runs until the client closes stdin (EOF) or SIGINT/SIGTERM is received, then returns 0.

cogdoc_service.go — Unified CogDoc write path

CogDocService is the ONLY write path for CogDoc mutations. It ensures that every write synchronises all kernel state: file write, index refresh, attentional field boost, and ledger event emission.

Before this service, three MCP tool handlers (toolWriteCogdoc, toolPatchFrontmatter, toolIngest) each performed an inconsistent subset of these steps. CogDocService centralises the contract.

coherence.go — CogOS v3 coherence validation

Simplified from apps/cogos/validation.go (v2.4.0). Provides the 4-layer validation stack as callable functions. The continuous process runs this on a cadence; it is not session-triggered.

Layers:

1. Schema — frontmatter structure valid
2. Invariants — system invariants hold (nucleus loaded, workspace intact)
3. Policy — kernel boundary not violated
4. Consistency — cross-artifact coherence

config.go — CogOS v3 configuration loading

config_write.go — kernel.yaml mutation plumbing for CogOS v3.

Implements the Config Mutation API per Agent O's design (`cog://mem/semantic/surveys/2026-04-21-consolidation/agent-O-config-mutation-design`).

Core exports consumed by MCP / HTTP surfaces:

ReadConfigOnDisk(root)         — parse kernel.yaml into kernelConfig
WriteConfigPatch(root, patch,) — validate + atomic-write with rotating backups
RollbackConfig(root, name)     — restore a prior .bak-<ts>
ResolveFromKernelConfig(kc)    — project kernelConfig → effective *Config
DefaultKernelYAML()            — hardcoded defaults for diff surfaces

Merge semantics follow RFC 7396 (JSON Merge Patch): explicit null deletes the key (restoring LoadConfig's default on next boot); missing keys are preserved.

Concurrency: package-level writeConfigMu serializes all mutating operations. v1 intentionally writes-to-disk + `requires_restart: true` — we never mutate live *Config pointers under the hot path.

context_assembly.go — foveated context assembly for chat requests

The engine owns the full context window. It accepts the client's messages[], decomposes them, scores conversation turns alongside CogDocs, and renders everything into a stability-ordered token stream within the configured budget.

Stability zones (ordered for KV cache optimization):

Zone 0: Nucleus (identity card) — most stable, always present
Zone 1: CogDocs + client system prompt — shifts slowly per query
Zone 2: Conversation history — scored by recency + relevance, evictable
Zone 3: Current message — always present
[Reserve: OutputReserve tokens for model generation]

Token budget is approximated as chars/4. Default budget: 32768 tokens (matches provider context_window from providers.yaml).

Any OpenAI-compatible client works transparently — the engine intercepts the standard messages[] array and manages what the model actually sees.

context_blocks.go — builder functions for well-known context blocks

Each build* function produces a single ContextBlock (or nil when the source data is unavailable). The foveated context pipeline calls these builders, collects non-nil results into a ContextFrame, and renders the frame.

context_frame.go — structured output type for the foveated context rendering pipeline

ContextFrame is the intermediate representation between context assembly and rendering. Each block is named, tiered by priority, annotated with a stability hint (for KV cache optimization), and carries its rendered content.

The rendering pipeline (serve_foveated.go) can compose, prioritize, and budget-fit blocks before emitting the final HTML comment block stream.

conversation_query.go — Reader for the turn.completed ledger stream.

Thin wrapper that scans .cog/ledger/<sid>/events.jsonl for turn.completed events and optionally hydrates each with the full text from the per-session sidecar .cog/run/turns/<sid>.jsonl.

When Agent L's QueryLedger API lands this wrapper will collapse to a 5-line shim over QueryLedger(event_type="turn.completed"); until then we do the (small) ledger scan locally. The scan is O(events-in-session) — cheap for typical sessions of <100 turns.

dashboard_embed.go — embeds and serves the web dashboard

The dashboard is a single HTML file served at GET / from the v3 daemon. No build step, no external dependencies, no separate process.

debug.go — introspection endpoints for the foveated context engine

Provides real-time visibility into engine state:

GET /v1/debug/last    — full pipeline snapshot from the most recent chat request
GET /v1/debug/context — current context window as zones with ordering and token counts

No external dependencies. Just curl it.

docs_generate.go — Auto-documentation pipeline

Walks the CogDoc corpus, parses frontmatter, groups by type/status/sector, and generates deterministic documentation outputs:

• DASHBOARD.md — inbox health (raw/enriched/integrated counts)
• INDEX.md — research index grouped by tags
• CATALOG.md — tool/skill inventory
• README.md — per-directory summaries

This is the efferent pathway: knowledge flows OUT of the CogDoc substrate as human-readable documentation. No LLM calls — purely deterministic.

Usage: cogos-v3 docs [--workspace PATH]

eventbus.go — in-process event broker for the kernel ledger.

The broker is the live fan-out companion to the hash-chained ledger. Every call to AppendEvent publishes the envelope here; subscribers get filtered, non-blocking deliveries via a buffered channel. A small ring buffer retains recent events so that reconnecting subscribers can replay the tail without re-reading the JSONL ledger.

Design constraints (from Agent N's design survey):

• Broker hook lives INSIDE AppendEvent (the single write sink) so that consolidate.go, cogblock_ledger.go, process.go — all of which call AppendEvent directly — feed the live bus without extra wiring.
• Publish is fire-and-forget: the ledger never blocks on a slow SSE consumer. Full subscriber channels drop events and increment a counter.
• A package-level currentBroker is set once by NewProcess; tests that want isolation use SetCurrentBroker(nil).
• Close unblocks all waiting subscribers so servers can shut down cleanly.

events_query.go — observability-flavored wrapper around QueryLedger.

The hash-chained ledger (ledger.go / ledger_query.go) is the source of truth. This file exists so the event-bus surface (MCP cog_read_events, HTTP GET /v1/events) can reuse that read path without dragging audit semantics (verify_chain, seq pagination) into a debugging tool.

Differences vs. QueryLedger:

• Accepts a Source filter in addition to SessionID/EventType.
• Since/Until accept either RFC3339 or duration shorthand ("5m"), resolved by the caller via ParseSinceDuration before construction.
• Order toggles asc/desc (QueryLedger is always asc within a session). Default is desc (newest first — "what's happening right now?").
• No verify_chain, no NextAfterSeq. Paging is via next_before (time- based) for the multi-session case.

experiment.go — autoresearch experiment runner

An experiment is a CogDoc (YAML frontmatter + markdown body) that specifies:

• Which benchmark prompts file to use
• Model, budget, and method
• Optional comparison against a baseline run

Usage:

cogos-v3 experiment run <path-to-experiment.md>

The runner:

1. Loads the experiment config from YAML frontmatter
2. Loads the benchmark prompts
3. Runs the benchmark suite
4. Saves results as a new experiment log CogDoc
5. If a previous run exists, computes and prints the recall/precision delta
6. Flags regressions (recall drop > threshold)

field.go — CogOS v3 attentional field

The attentional field is the continuous salience map over the memory corpus. Every memory file gets a float64 score. The "fovea" is the top-N files by score that fit in the context window.

In v2, salience was computed once per session at context assembly time. In v3, the field is updated continuously by the process loop, decoupled from any external request.

gate.go — CogOS v3 attentional gate

The gate receives events (perturbations) and routes them into the fovea. It decides:

• Which memory files should be elevated in salience as a result of this event
• Whether the event triggers a state transition in the process

Stage 1: minimal routing — gate accepts events and records them. Stage 2+: gate will perform semantic matching against the attentional field.

index.go — CogDoc index for CogOS v3

BuildIndex walks .cog/mem/ and constructs an in-memory lookup table for all CogDoc files (Markdown files with YAML frontmatter). The index provides O(1) lookups by URI, type, tag, and status, plus forward and inverse reference graphs for coherence validation.

Index lifecycle:

1. Built on startup (best-effort; errors are non-fatal).
2. Rebuilt by Process.runConsolidation() on each consolidation tick.
3. Served via /v1/resolve for URI resolution queries.

ingest.go — Core types and interfaces for the deterministic ingestion pipeline.

The ingestion pipeline decomposes heterogeneous input (URLs, conversations, documents) into normalized IngestResult records suitable for the inbox/memory lifecycle. Format-specific logic lives in Decomposer implementations; this file defines the shared vocabulary and the pipeline orchestrator.

ingest_url.go — URL decomposer for the ingestion pipeline.

Fetches a URL, extracts structured metadata from HTML (title, meta tags, Open Graph, Twitter cards), classifies content by domain, and returns a normalized IngestResult.

init.go — cogos init command

Scaffolds a new CogOS workspace with the minimum structure needed for the daemon to start: config files, memory directories, a default identity card, and an empty ledger.

Idempotent: does not overwrite existing files. Safe to run on an existing workspace to fill in missing structure.

kernel_log_query.go — Read-side of the kernel slog API.

Implements Part (b) of Agent U's kernel-slog-api design — the surface half. Exposes QueryKernelLog, which reads the JSONL sink produced by the teeHandler (see log_capture.go) and returns the most recent entries in newest-first order, optionally filtered by level, substring, and time range.

Filter shape mirrors Agent L's QueryLedger and Agent Q's QueryTraces (from their respective in-flight PRs) so the three observability surfaces — ledger, traces, kernel slog — present a consistent query grammar to Claude:

• ledger: hash-chained events (Agent L)
• traces: client-originated metabolites (Agent Q)
• slog: operator/debug diagnostic text (this file)

The on-disk format is one slog.NewJSONHandler record per line. Top-level fields "time", "level", "msg" are extracted into typed fields; anything else becomes an entry in the Attrs map. Malformed lines are skipped silently (matches the readLastJSONLEntries tolerance used by the proprioceptive endpoint) — corrupted lines are a data-quality signal, not an API error.

Scan strategy: forward-scan into a bounded ring with a 1 MiB bufio buffer (same primitive as serve.go:readLastJSONLEntries). For v1 file sizes (sub-GB for years of uptime on active workspaces) this is fast enough; a reverse-scan optimization can land in v1.5 alongside rotation.

ledger.go — CogOS v3 hash-chained event ledger

Ported from apps/cogos/ledger_core.go (v2.4.0). CLI command functions removed; EventEnvelope, hash chain, and append logic preserved.

Every significant cognitive event is recorded as an append-only JSONL entry. Entries are hash-chained (RFC 8785 canonical JSON + SHA-256) to provide tamper-evidence and causal ordering.

ledger_query.go — read-side query API for the hash-chained event ledger.

The write side (AppendEvent, CanonicalizeEvent, HashEvent) lives in ledger.go. This file exposes filtered reads for MCP tools and HTTP endpoints without reimplementing any of the canonicalization or hashing logic.

log_capture.go — Kernel slog capture: tee stderr text output to a JSONL file sink.

Implements Part (a) of Agent U's kernel-slog-api design — the file-sink/capture half. The default logger installed by setupLogger() keeps writing key=value text to os.Stderr (backwards-compatibility lock for service managers that capture stderr); this file adds a fan-out so the same records are simultaneously emitted as structured JSON into <WorkspaceRoot>/.cog/run/kernel.log.jsonl.

Why a teeHandler instead of io.MultiWriter: the two sinks have different encodings (text on stderr, JSON in the file). A single slog.Handler cannot emit two formats; wrapping two sub-handlers in a Handle() fan-out lets us keep the human-readable terminal output while also getting machine-parseable on-disk output for the cog_tail_kernel_log MCP tool / GET /v1/kernel-log.

Call order: setupLogger() runs at process start (stderr-only text handler); upgradeLoggerWithFileSink(cfg) runs AFTER LoadConfig once the workspace root is known. Anything logged between the two goes to stderr only — that window is microseconds in practice and those early lines are re-emitted after the upgrade via the "config loaded" Info call.

The file handle is opened with O_APPEND and left open for the kernel's lifetime; the OS flushes on process exit. If the open fails (disk full, permission denied, read-only mount) we log a Warn to stderr and fall back to the stderr-only handler. The kernel never crashes over log-sink setup.

mcp_server.go — MCP Streamable HTTP server for CogOS v3

Embeds the MCP server into the existing HTTP server at /mcp. Registers 11 MCP tools and 3 MCP resources. Four former tools (resolve_uri, get_trust, get_nucleus, get_index) are no longer registered as MCP tools but their implementations remain — used by the internal tool loop (tool_loop.go).

Resources (read-only addressable data):

• cogos://state — kernel process state
• cogos://nucleus — identity context
• cogos://field — attentional field (top-20)

Transport: Streamable HTTP (MCP spec 2025-03-26) Endpoint: POST/GET /mcp

mcp_sessions.go — 8 native MCP tools over the kernel session/handoff registries. Complement (not replacement) to the 8 `cogos_*` Python bridge tools that live in cog-sandbox-mcp: per amendment #5 both surfaces coexist by design — bridge tools keep MCP-level ergonomics for agents already wired to the Python sandbox; these expose the same kernel truth with no Python dependency so a future native client (Wave widget, desktop app, direct `cog` CLI) can just speak MCP.

Tool naming mirrors the rest of the kernel MCP surface: snake_case under the `cog_*` prefix. Input/output types live in this file so mcp_server.go stays focused on registration.

mcp_stubs.go — Internal API stubs for MCP tools

These functions bridge MCP tool calls to the v3 kernel internals. Some delegate to existing functionality, others are stubs awaiting full implementation. Each stub documents what it should eventually do.

memory.go — CogOS v3 memory system interface

Thin interface over the CogDocs memory layout (.cog/mem/). Delegates search to the cog CLI wrapper (scripts/cog memory search). In stage 5, this will be replaced with local embedding-based retrieval.

nucleus.go — CogOS v3 nucleus

The nucleus is the always-loaded identity context: the runtime object that is never evicted from memory. It replaces the v2 pattern of loading the identity card from disk at session start.

In v3, the nucleus is loaded once at daemon startup and held in memory for the lifetime of the process. It is the "floor" of the attentional field.

observer.go — CogOS v3 observer loop (Field → Observer → Model → Field)

Implements the trefoil closed loop that makes the daemon a true observer:

Loop 1 (Field → Observer): Each consolidation tick reads attention signals
from the attention log and current field scores — the raw percept.

Loop 2 (Observer → Model): TrajectoryModel updates attention momentum via
EMA, computes Jaccard prediction error against the previous cycle, and
generates a new prediction. Both error and prediction are recorded in the
ledger (hash-chained, irreversible — this is the arrow of time).

Loop 3 (Model → Field): Predictions pre-warm the field (salience boost).
Paths that drop out of the prediction are attenuated. Prediction errors
above the surprise threshold emit an observer.surprise coherence signal.

The consolidation CogDoc written each cycle is the model's trace in the field — a legible record that the observer existed and acted.

process.go — CogOS v3 continuous process state machine

Implements the always-running cognitive process described in the v3 spec. The process has four states and an internal event loop that runs independently of external HTTP requests.

States:

Active       — processing an external perturbation
Receptive    — idle, listening for input
Consolidating — running internal maintenance (memory, coherence)
Dormant      — minimal activity, heartbeat only

The select loop is the core architectural difference from v2: v2 is request-triggered; v3 has internal tickers that fire regardless.

procmgr.go — Process lifecycle manager for Claude Code subprocesses.

Tracks all spawned claude processes (foreground, background, agent). Handles:

• Client disconnect / cancellation (SIGTERM → SIGKILL escalation)
• Background process lifecycle (outlive the HTTP request)
• Concurrent process limits (per-identity and global)
• Process inventory for observability
• Callback delivery when background tasks complete

Process kinds:

• Foreground: tied to an HTTP request. Killed on client disconnect.
• Background: fire-and-forget. Has its own timeout. Reports via callback.
• Agent: runs in a Docker container. Trust-bounded. Future implementation.

proprioceptive.go — Proprioceptive logging for TRM prediction-vs-reality tracking.

After each chat request, the TRM predicts which chunks will be referenced. This logger records predictions alongside actual references extracted from the response, enabling continuous calibration of the light cone.

Log format: JSONL at .cog/run/proprioceptive.jsonl

provider.go — CogOS v3 inference provider interface

Adapted from the workspace PROVIDER-SPEC.md contract. All LLM backends satisfy the Provider interface. The kernel never calls a model API directly — it always routes through a Provider.

Key design decisions:

• Models are organs, not the organism. Swappable, upgradeable.
• CompletionRequest carries foveated context, not raw strings.
• Router implements the sovereignty gradient: local-first, cloud-escalate.
• ProcessState uses string (maps to ProcessState.String() from process.go).

provider_anthropic.go — AnthropicProvider

Implements Provider against the Anthropic Messages API (POST /v1/messages). Auth: x-api-key header, read from the env var named by config.APIKeyEnv. Streaming: SSE (text/event-stream), reading typed events (message_start,

content_block_start, content_block_delta, message_delta, message_stop).

Tool calls: streamed incrementally as ToolCallDelta chunks; non-streaming

responses decode tool_use content blocks directly.

Context items are prepended to the system string as labelled sections.

provider_claudecode.go — ClaudeCodeProvider

Implements Provider by spawning `claude -p` subprocesses. Unlike the Anthropic and Ollama providers, ClaudeCodeProvider is agentic: the subprocess owns its own tool loop (filesystem, MCP, etc.).

Authentication: uses the host's Claude Max subscription via OAuth (keychain). Does NOT use --bare mode, which would require API keys.

Process lifecycle:

• Foreground: tied to HTTP request context. Cancelled on disconnect.
• Background: outlives the request. Reports back via callback.
• Agent: runs in Docker container. Trust-bounded, resource-limited.

Output: parsed from `--output-format stream-json --include-partial-messages` which emits NDJSON with Anthropic streaming events.

provider_codex.go — CodexProvider

Implements Provider by spawning `codex exec` subprocesses (OpenAI Codex CLI). Parses the NDJSON event stream (--json flag) and extracts agent_message items.

Authentication: uses the host's ChatGPT Pro subscription via codex CLI auth.

provider_ollama.go — OllamaProvider

Implements Provider against a local Ollama server (http://localhost:11434). Uses /api/chat for multi-turn conversations (not /api/generate). Streaming: Ollama returns newline-delimited JSON chunks. think=false: disables qwen3's thinking mode to avoid silent token burn.

provider_openai.go — OpenAICompatProvider

Implements Provider against any OpenAI-compatible API server: LM Studio, vLLM, llama.cpp server, text-generation-webui, or the OpenAI API itself. Uses /v1/chat/completions for both streaming (SSE) and non-streaming. Discovery: GET /v1/models to enumerate available models.

SSE format: "data: {...}\n\n" lines with "data: [DONE]" sentinel. No CGO dependencies — standard library net/http only.

provider_pi.go — PiProvider

Implements Provider by spawning `pi -p` subprocesses for local agentic inference. Pi handles the tool loop (read, bash, edit, write) against local models via Ollama, while the kernel handles context assembly.

This is the local counterpart to ClaudeCodeProvider:

• ClaudeCodeProvider: cloud agentic inference (Claude Max via OAuth)
• PiProvider: local agentic inference (Ollama via Pi)

The kernel assembles foveated context and injects it via --system-prompt. Pi runs the agent loop. Ollama runs the model.

Output: parsed from `--mode json` which emits NDJSON AgentSessionEvents.

provider_stub.go — StubProvider for testing

In-memory provider with configurable responses, error injection, and latency simulation. Used in unit tests and for offline development.

router.go — SimpleRouter + BuildRouter

SimpleRouter implements the Router interface with rule-based provider selection:

1. Check process-state routing overrides
2. Try preferred provider first, then fallback chain
3. Filter by availability + required capabilities
4. Score local > cloud (sovereignty gradient)
5. Record every routing decision for future sentinel training

BuildRouter reads .cog/config/providers.yaml and instantiates enabled providers. Falls back to a default Ollama config when no providers.yaml is present.

salience.go — CogOS v3 git-derived salience scoring

Ported from apps/cogos/salience.go (v2.4.0). CLI command functions removed; core computation preserved.

Implements ADR-018: Salience System (Git-Derived Attention). Performance target: <5ms per file via go-git (vs 80ms in shell version).

serve.go — CogOS v3 HTTP API

Core endpoints:

GET  /health                           — liveness + readiness probe
GET  /v1/context                       — current attentional field (debug)
GET  /v1/resolve                       — resolve a cog:// URI to a filesystem path
POST /v1/chat/completions              — OpenAI-compatible chat (streaming + non-streaming)
POST /v1/messages                      — Anthropic Messages-compatible chat
POST /v1/context/foveated              — foveated context assembly for Claude Code hook
GET  /v1/proprioceptive                — last 50 proprioceptive log entries + light cone status
GET  /v1/ledger                        — query the hash-chained event ledger
GET  /v1/lightcone                     — light cone metadata (placeholder)
GET  /v1/kernel-log                    — tail kernel slog (diagnostic text) JSONL sink; filter by level/substring/time

Constellation / attention endpoints (Phase 3, see serve_attention.go):

POST /v1/attention                     — emit attention signal
GET  /v1/constellation/fovea           — current fovea state
GET  /v1/constellation/adjacent?uri=… — adjacent nodes by attentional proximity

The chat endpoint routes through the inference Router when one is set, otherwise returns 501.

serve_blocks.go — HTTP endpoints for block sync protocol

Phase 3 of the block sync protocol: remote blob exchange.

GET  /v1/blocks/{hash}     — retrieve a blob by hash
PUT  /v1/blocks/{hash}     — store a blob by hash
GET  /v1/blocks/manifest   — list all stored blobs (manifest exchange)
POST /v1/blocks/verify     — verify a list of hashes, return missing ones

These endpoints enable workspace-to-workspace blob sync:

1. Workspace A gets B's manifest
2. Diffs against local manifest
3. GETs missing blobs by hash
4. Stores them locally

Content is verified by hash on both read and write — the hash IS the address.

serve_bus.go — HTTP surface for the per-bus event store.

Track 5 Phase 3: ported verbatim from the root package's bus_api.go + serve_bus.go. The response shapes are byte-compat with the live v3 daemon so cog-sandbox-mcp's bridge (tools/cogos_bridge.py) keeps working when the installed binary flips to engine in Phase 4.

Routes owned by this file:

POST   /v1/bus/send                       — append event to a bus
POST   /v1/bus/open                       — create/register a bus
GET    /v1/bus/list                       — list all registered buses
GET    /v1/bus/events                     — cross-bus event search
GET    /v1/bus/{bus_id}/events            — per-bus events, filtered
GET    /v1/bus/{bus_id}/events/{seq}      — single event by seq
GET    /v1/bus/{bus_id}/stats             — bus statistics
GET    /v1/bus/consumers                  — list consumer cursors (ADR-061)
DELETE /v1/bus/consumers/{consumer_id}    — remove a consumer cursor

serve_compat.go — v2 compatibility endpoints for Phase 0 cutover.

These endpoints allow v3 to replace v2 as the production kernel on port 5100. Consumers: OpenClaw cogos plugin, CogBus plugin, launchd service.

DEPRECATED: These compatibility routes exist only for migration from v2. They will be removed once all clients migrate to standard endpoints. Standard endpoints: /v1/chat/completions, /v1/messages, /mcp, /health

Endpoints:

GET  /v1/card            — kernel capability card (OpenClaw auth flow)
GET  /v1/models          — OpenAI-compatible model list
GET  /memory/search      — memory search (was missing from v2 too)
GET  /memory/read        — memory read (was missing from v2 too)
GET  /coherence/check    — coherence check
GET  /v1/providers       — provider list with health
GET  /v1/taa             — TAA context visibility stub

Removed in the event-bus PR (were always stubs):

GET  /v1/events/stream   — replaced by the real broker-backed handler in serve.go
POST /v1/bus/{bus_id}/ack — dropped; no consumer, new SSE uses Last-Event-ID

serve_config.go — HTTP surface for the Config Mutation API (Agent O design).

GET   /v1/config             — read effective + raw + defaults
PATCH /v1/config             — RFC 7396 merge-patch (validated, atomic, backed up)
POST  /v1/config/rollback    — restore from a .bak-<timestamp> file

All handlers return JSON on success and on structured-error paths.

serve_events.go — HTTP surface for the kernel event bus.

Two endpoints:

GET  /v1/events         — historical read. Thin wrapper around QueryLedger
                          with observability-flavored defaults (no
                          verify_chain, "since" accepts durations).
GET  /v1/events/stream  — live SSE stream backed by the EventBroker. Emits
                          `event: ledger.appended` frames with `id: <hash>`
                          for standard Last-Event-ID resume.

Internal invariant: both endpoints source from AppendEvent's ledger (the single write sink). There is no duplicate storage — QueryLedger reads disk, the SSE stream reads the broker's ring + live fan-out.

serve_foveated.go — POST /v1/context/foveated

Bridge endpoint matching the v2 foveated context API so that the Claude Code hook (foveated-context.py) can point at the v3 kernel.

Input: {prompt, iris: {size, used}, profile, session_id} Output: {context, tokens, anchor, goal, iris_pressure}

The "context" field is a rendered string of CogBlock HTML comment blocks that get injected into Claude's context window via the hook's additionalContext.

serve_sessions.go — per-session context observability endpoints.

Track 5 Phase 3: ported from root's serve_context.go (handleListSessions + handleSessionContext). Preserves the byte-compat response shape:

GET /v1/sessions           → { count, sessions: [sessionSummary ...] }
GET /v1/sessions/{id}      → SessionContextState (full detail)
GET /v1/sessions/{id}/context → SessionContextState (alias)

The store is kept as a struct field on Server so tests can instantiate isolated instances; root's singleton-style map is equivalent in single- server deployments.

serve_sessions_mgmt.go — kernel-native HTTP surface for session & handoff management. The 8 routes below are the "invariance layer" of the hybrid design: they validate inputs, enforce the state machine via SessionRegistry / HandoffRegistry, and only then append to the bus.

Routes registered here:

POST /v1/sessions/register                — register (or idempotently
                                            update) a session
POST /v1/sessions/{id}/heartbeat          — bump last_seen + optional
                                            status fields
POST /v1/sessions/{id}/end                — mark ended; optional
                                            handoff_id hand-off-ref
GET  /v1/sessions/presence                — roster of tracked sessions
                                            (optional active_within_seconds)

POST /v1/handoffs/offer                   — post an offer (kernel mints
                                            handoff_id if missing)
GET  /v1/handoffs                         — list handoffs, optional
                                            state / for_session filters
POST /v1/handoffs/{id}/claim              — atomic first-wins claim;
                                            emits handoff.claim_rejected
                                            on failure (amendment #4)
POST /v1/handoffs/{id}/complete           — mark claimed offer completed

Note: the existing routes `/v1/sessions` and `/v1/sessions/{id}[/context]` registered by serve_bus.go are preserved untouched (they serve per-turn TAA inference context, a different concern). Go 1.22 pattern precedence resolves `POST /v1/sessions/register` before `GET /v1/sessions/` because the method+pattern is more specific.

sessions.go — kernel-native session & handoff registries.

This is the "invariance layer" of the hybrid design sketched in cog://mem/semantic/surveys/2026-04-21-consolidation/agent-P-session-management-evaluation. The bus (BusSessionManager) remains ground truth; everything in this file is a derived view rebuilt from bus replay at startup. The registries' job is to enforce the state-machine invariants the bridge-only implementation was doing by convention:

• session_id format validation (regex) on register
• idempotent re-register = update-semantics (re-register a live session updates the in-memory row; re-register after end is allowed only if the prior session is ended or its heartbeat is outside the active window)
• heartbeat/end refused against unknown sessions
• end refused against already-ended sessions
• handoff.offer → claim → complete state machine with:
• first-wins claim (atomic check under handoff mutex)
• TTL enforcement (offer rejected if now - created_at > ttl_seconds)
• claim-before-offer rejection (phantom offers) as 404
• complete-before-claim rejected as 409
• on every rejected claim, emit a handoff.claim_rejected event on bus_handoffs so operators have an audit trail (amendment #4 of the user-approved plan).

Everything is flushed to the bus via BusSessionManager.AppendEvent so the seq/hash chain remains the authoritative ledger. The in-memory maps only speed up reads and guard writes against out-of-order transitions.

telemetry.go — OpenTelemetry tracing and metrics for the v3 kernel

Initializes a tracer and meter provider with OTLP HTTP exporters. Degrades gracefully to no-op when no collector is available.

Environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT — collector endpoint (default: http://localhost:4318)
OTEL_SERVICE_NAME           — service name (default: cogos-v3)

Usage:

shutdown := initTelemetry(ctx)
defer shutdown(ctx)
// Use otel.Tracer("cogos-v3") and otel.Meter("cogos-v3") anywhere.

tool_calls_query.go — Query layer for tool.call / tool.result ledger events.

Agent S (survey-2026-04-21-agent-S-tool-bridge-design §4.4) specifies a call+result stitching view over the hash-chained ledger. The query layer is a thin wrapper: it scans .cog/ledger/{sessionID}/events.jsonl (optionally across all sessions), picks out tool.call and tool.result entries, pairs them by call_id, applies filters, and returns a first-class row shape.

The stitched view is the ergonomic win: a caller asking "show me the 10 most recent tool invocations and did they succeed?" gets one row per call with both timestamps and the status already joined — no two-round-trip client- side pairing like the generic event-read surface would require.

When upstream lands Agent L's QueryLedger, this file can become a thin wrapper over that API (Agent S §5.1). For now it reads the ledger JSONL files directly — the same pattern process.go and cogblock_ledger.go use.

tool_loop.go — Internal tool execution loop for the v3 kernel

When the inference provider returns tool_calls, the kernel: 1. Checks if each tool is a kernel-owned tool 2. Executes kernel tools internally (no HTTP round-trip) 3. Injects tool results into the conversation 4. Re-calls the provider until it produces text or hits max iterations

Client-owned tools are passed back to the client in the response. The kernel acts as a tool call router: execute what it owns, forward what it doesn't.

tool_observer.go — Tool-call observability: emission + pending-call correlation.

Agent S (survey-2026-04-21-agent-S-tool-bridge-design) specifies that every tool invocation observed by the kernel should emit a "tool.call" ledger event and — when the result is known — a paired "tool.result" event. The gate recognizer at gate.go:94 has accepted those types since day one but nothing emitted them. This file fills that gap and activates the scaffolded-but-never- wired per-tool-call observation surface identified in issue #22.

The kernel observes two kinds of tool invocation:

1. Kernel-ownership (MCP handlers, internal tool-loop executions). The kernel runs the tool inline; call and result are both emitted by withToolObserver right around the handler invocation. No correlation cache is needed — the result is known the moment the handler returns.

2. Client-ownership (provider returned a tool_call the client must execute). The kernel emits the tool.call immediately, registers a pending entry, and emits tool.result later when the client sends a matching role=tool message back. The pending-call cache lives for a bounded TTL and is swept periodically; entries that exceed the TTL get a tool.result{status=timeout} event so the audit trail never leaves a tool.call dangling forever.

All emission flows through process.emitEvent → AppendEvent, i.e. the same hash-chained ledger Agent L's read tools query and Agent N's event bus tails. No orphan writer. The root-package tools_bridge.go is explicitly NOT the model for this file — that file bypasses AppendEvent and is slated for deletion with Agent I's purge.

transition_hooks.go — ADR-072 state-transition hook dispatch.

Implements the per-transition handler layer described in ADR-072 ("State-Transition Hooks for Node Lifecycle"). On every state change, `transition()` invokes a per-state enter handler. Each handler:

• Runs the minimum-viable per-ADR work inline (small, bounded).
• Dispatches any matching declarative StateHook definitions loaded from `.cog/hooks/transitions/*.yaml`. Only the `shell:` form is implemented at this revision — agent-form hooks (ADR-072 Phase 3) are loaded and matched but logged as pending instead of executed.

Non-goals of this file:

• Event-bus emission of transition records (owned by a sibling track).
• Full agent-subprocess spawning with budget/timeout (ADR-072 Phase 3).
• Condition evaluation beyond the scaffold (ADR-072 Phase 4).

Concurrency: all handler bodies and hook executions run on goroutines spawned by `transition()`. They must not take `p.mu`; they may read immutable fields (cfg, sessionID) directly.

trm.go — Pure Go implementation of MambaTRM inference.

The TRM (Temporal Retrieval Model) uses Mamba selective state spaces to process temporally ordered session events and predict which workspace chunks are most relevant. It maintains a "light cone" — compressed SSM hidden state representing the observer's trajectory through the workspace.

This is a zero-dependency inference engine: no gonum, no CGO. All math is done with raw float32 slices and manual loops. The model is tiny (~1.7M params), so this is efficient enough.

Binary weight format (TRM1):

4 bytes: magic "TRM1"
4 bytes: uint32 number of tensors
Per tensor: name_len(4) + name(N) + ndim(4) + shape(4*ndim) + data(4*numel)
All values little-endian. Data is float32, row-major.

trm_context.go — TRM integration into the context assembly pipeline.

Provides:

• OllamaEmbed: embed a query via the local Ollama /api/embeddings endpoint
• trmScoreDocs: score CogDoc candidates using MambaTRM + embedding index
• loadTRMAtStartup: one-shot loader called from main.go

When the TRM is available, it replaces keyword+salience scoring as the primary CogDoc ranking signal. When unavailable (no weights, Ollama down, etc.), the pipeline falls back to the existing scoring transparently.

trm_index.go — Embedding index for TRM cosine pre-filtering.

Loads the binary embedding index (EMB1 format) and chunk metadata (JSON) exported by trm_export.py. Provides fast cosine similarity top-K search over the full embedding corpus.

Binary format (EMB1):

4 bytes: magic "EMB1"
4 bytes: uint32 num_chunks
4 bytes: uint32 dim (384)
num_chunks * dim * 4 bytes: float32 data (row-major, little-endian)

trm_lightcone.go — Thread-safe per-conversation light cone state manager.

Each conversation maintains its own light cone — the SSM hidden state that compresses the observer's trajectory through the workspace. The LightConeManager provides concurrent-safe access keyed by conversation ID.

turn_storage.go — Chat-history turn persistence (Agent R hybrid design).

Closes Agent F gap #4 and cogos#20 (RecordBlock data-loss bug). RecordBlock at cogblock_ledger.go is persistence-theatre: it writes a metadata-only event and drops the full CogBlock payload on the floor. Instead of mutating RecordBlock (its call-site pattern is used elsewhere for metadata-only ingest events), we add a parallel RecordTurn path that captures the prompt/response pair — a first-class "turn" — via:

1. A sidecar JSONL file at .cog/run/turns/<sessionID>.jsonl carrying the full turn (prompt, response, tool-call transcript, usage, model).
2. A hash-chained `turn.completed` ledger event with TRUNCATED previews (defaults: 8 KB prompt / 16 KB response) + pointer to the sidecar.

Readers (cog_read_conversation, GET /v1/conversation) hydrate from the sidecar. Agent N's broker, once it lands, will fan out turn.completed on the live event bus for free — no extra code in this file.

uri.go — cog:// URI projection system for CogOS v3

A cog:// URI has the form:

cog://type/path[#fragment]

"type" selects a Projection that maps to a filesystem location under the workspace root. "path" is the resource name within that projection. "fragment" (optional, after '#') identifies a section within the file.

Examples:

cog://mem/semantic/insights/eigenform.cog.md        → .cog/mem/semantic/insights/eigenform.cog.md
cog://mem/semantic/insights/eigenform.cog.md#Seed   → same path, anchor "Seed"
cog://conf/kernel.yaml                              → .cog/config/kernel.yaml
cog://crystal                                       → .cog/ledger/crystal.json

uri_v2_stub.go — stub for URIRegistry when coguri library is unavailable.

mcp_server.go references URIRegistry under the mcpserver build tag. When the coguri library isn't present (no coguri build tag), this stub provides a nil-valued placeholder so the package compiles cleanly. The nil check in mcp_server.go (if URIRegistry != nil) ensures the Resolve method is never actually called.