5.7. Runtime internals

What a contributor needs to know about who owns what inside the runtime. A user of SPEAR can skip this page; Architecture is the picture from the outside.

5.7.1. Task ownership

On the normative runtime, WorkingState is authoritative task truth. It changes only through typed, grounded events. Conversation, retrieved context, durable memory and compacted summaries are context sources, not alternative task-state stores.

TaskController owns the bounded synchronous lifecycle: optional planning, Main execution, verification, and checkpoint finalization by default. Explorer, Reviewer and their bounded repair cycle are explicit experimental opt-ins. It receives an already constructed AgentContext and injected callbacks for project bench execution, diff evidence, child sessions, and the remaining code-block compatibility path. It does not read terminal input, render output, choose a provider, or construct a filesystem persistence implementation.

5.7.2. Context and memory

On the normative runtime, ContextEngine composes the context. It accounts for system rules, project rules, WorkingState projection, conversation summaries, recent conversation, retrieval and tool evidence.

The coding core builds its own request from the selected rules, project metadata, skills, workspace knowledge and admitted capabilities, and reads the tree through its tools; it does not compact, it stops at half the window and asks for a summary. Each of its model responses is bounded by SPEAR_RESPONSE_MAX_TOKENS (Configuration reference).

Workspace knowledge is owned by workspace_knowledge.py and described in Workspace knowledge; external capabilities by capabilities.py, capability_gateway.py and mcp_provider.py, described in External capabilities.

5.7.3. Persistence and retention

Where each persistent artifact lives is listed in Directory layout. No automatic garbage collector runs. Closed session bundles may be archived or deleted manually as a unit once their checkpoint and result references are no longer needed. Deleting a trace or trajectory never repairs or invalidates a session; deleting referenced results or checkpoints makes the associated evidence unavailable.

5.7.4. Dependency direction

Lower runtime modules do not import rag_chat or the cli/ modules it is built from. The client owns backend construction, project selection, terminal commands, human confirmation and presentation. TaskController depends on provider-neutral policies and protocols; AgentRuntime does not depend on TaskController or on Explorer/Reviewer orchestration.

The training subsystem (Training and fine-tuning) is fed rather than called, and its coupling runs one way: AgentRuntime and TaskController emit trajectories, rag_chat owns the /finetune operator command, and training_handoff may stop the inference service, because on a single-GPU host the card that trains is the card that serves.

5.7.5. Model capability boundary

ModelBackend.complete is the intentionally small required protocol. Canonical ModelTurn carries stop reason and optional usage, while context and output limits are explicit AgentContext configuration. Cancellation is checked immediately before and after calls for every backend. There is no mandatory capability object: the adapters cannot truthfully promise transport-level cancellation or exact token counting, and making those flags mandatory would couple the runtime to provider behavior. An adapter may expose optional native capabilities without changing the canonical turn contract.

5.7.6. Default profile

Requests with no standard engaged run on the coding core. --fresh starts a session without its stored conversation; knowledge, rules and configuration still apply. Requests in a standard-bound session run on the normative runtime, or through the MIXED orchestration when they ask for a change in the standard’s terms. On the normative runtime, planning is deterministic and conservative; Explorer, Reviewer and reviewer repair are disabled unless the caller explicitly enables them.