Objective: Kernel Interface

[JaimeStill]

Objective

Establish the kernel's HTTP interface — the sole extensibility boundary through which external services connect to the kernel. This objective expands beyond the original ConnectRPC scope to address foundational architecture decisions that must be resolved before the interface is set.

Scope

• Agent registry: Kernel-level named agent registration with capability querying (model-aligned names like qwen3-8b, gpt-5)
• Multi-session kernel: Refactor from single-session to multi-session runtime. Sessions as context boundary for all subsystem integrations
• Streaming-first: Add ToolsStream to Agent interface. Kernel loop uses streaming by default
• Observer pattern: Replace ad-hoc slog logger with orchestrate Observer. Absorbs Objective Objective: Local Development Mode #4 logger concern
• Pure HTTP + SSE: Standard net/http handlers with JSON + Server-Sent Events for streaming. OpenAPI for schema documentation
• Child session foundation: Session model includes parent ID and inheritance config (full subagent orchestration deferred)

HTTP API Surface

GET    /agents                         List registered agents and capabilities
POST   /sessions                       Create session (agent name, bootstrap context)
GET    /sessions/{id}                  Get session metadata and status
POST   /sessions/{id}/run              Submit prompt → SSE stream of events
GET    /sessions/{id}/memory           List memory keys
GET    /sessions/{id}/memory/{key...}  Get memory entry
PUT    /sessions/{id}/memory/{key...}  Save memory entry
DELETE /sessions/{id}/memory/{key...}  Delete memory entry
GET    /tools                          List registered tools

Subsystems

• agent/ — ToolsStream addition
• kernel/ — Agent registry, observer, multi-session refactor
• api/ — HTTP handlers, SSE streaming, OpenAPI (replaces rpc/)
• cmd/server/ — Server entry point
• scalar/ — Standalone Scalar UI (Bun project, dev-time only)

Dependencies

Depends on Objective: Kernel Core Loop (the interface wraps the runtime loop).

Architecture Decisions

• Pure HTTP + SSE replaces ConnectRPC — aligned with "simple, composable patterns over complex frameworks"
• Agent registry is kernel infrastructure (not memory namespace). memory/agents/ reserved for subagent profile content
• Sessions are the context boundary — all subsystem integrations scoped to sessions
• Observer replaces kernel logger, absorbs Objective Objective: Local Development Mode #4 logger concern
• HTTP handlers in api/ package, separate from kernel runtime