savant-code 0.0.19 → 0.0.21

package/docs/reports/Thinker Agent Architecture Research.md

@@ -1,284 +0,0 @@
-# **Savant-Code Thinker Architecture: An Exhaustive Conceptual Research Report and Perfection Loop Analysis**
-
-## **1\. Executive Summary**
-
-The orchestration of autonomous coding agents requires a transition from open-loop, heuristic-based generation to closed-loop, fail-safe determinism. The Savant-Code Orchestrator currently delegates complex reasoning tasks to a specialized Thinker agent designed to execute structured sequential-thinking calls. However, significant architectural vulnerabilities have surfaced in production. Most notably, the system occasionally returns a successful structured output with a null value, experiences the silent loss of reasoning context across multiple thought steps, and suffers from conflicting sources of truth among streaming deltas, message histories, and tool results.  
-This analysis provides an exhaustive investigation into the optimal architecture for a custom Thinker agent. Drawing upon empirical research spanning the official Model Context Protocol (MCP) Sequential Thinking server, alternative state-of-the-art agent runtimes, and extensive public user feedback, the investigation isolates the root cause of these failures. The fundamental vulnerability lies in the conflation of the Large Language Model (LLM) generative message history with the agent's authoritative operational state, exacerbated by the cognitive degradation induced by strict JSON formatting constraints.  
-To resolve these systemic issues, the research proposes a complete architectural overhaul based on Command Query Responsibility Segregation (CQRS) and Event Sourcing. By decoupling the provider-specific generative stream from a strict, durable, append-only state machine, the Thinker guarantees monotonic state progression. This design enforces strict invariants that make premature finalization, lost thoughts, and null outputs structurally impossible, establishing a highly robust, provider-agnostic foundation for Savant-Code’s multi-agent framework.
-
-## **2\. What Sequential Thinking MCP Actually Provides**
-
-An analysis of the official Model Context Protocol Sequential Thinking server reveals that it is fundamentally a dynamic state-tracking utility exposed as a tool to the LLM1. It is designed to solve the problem of context degradation and premature convergence in complex reasoning tasks by allowing an LLM to break problems into manageable steps, evaluate its own progress, and adjust its planning dynamically as new information emerges.  
-The architectural boundary is strictly defined between the tool and the host. The MCP tool itself owns the schema validation, the tracking of the numerical sequence, the management of branch identifiers, and the calculation of the total thought history length3. It validates that inputs match the expected types and coerces ambiguous inputs, such as stringified booleans, into their proper primitive types to prevent runtime crashes3. Conversely, the host agent (the client) retains ownership of the execution loop, prompt construction, LLM provider integration, context window management, and the ultimate authoritative decision to halt or continue execution based on the tool's outputs.  
-The tool operates on a precise semantic vocabulary. The thought field contains the substantive analytical text for the current step, while the thoughtNumber serves as the sequence identifier3. The totalThoughts parameter acts as a dynamic, mutable estimate of the required steps, allowing the LLM to signal an expanding scope to the host3. The nextThoughtNeeded flag dictates whether the model believes it has reached a conclusion3.  
-The sequence is best understood as a directed acyclic graph (DAG) of reasoning events rather than a flat, linear transcript. Revisions and branches do not mutate or delete historical data. The isRevision and revisesThought parameters indicate that the current thought conceptually overwrites a prior node, appending a new node with a logical pointer to the superseded one, thereby preserving the immutable history3. Similarly, the branchFromThought and branchId fields facilitate parallel exploration, allowing the model to explore multiple hypotheses originating from a single historical thought node without corrupting the primary sequence3.  
-In this paradigm, convergence is achieved exclusively when the LLM submits a valid tool call setting nextThoughtNeeded to false while providing a conclusive answer3. A sequence cannot legitimately converge without a final answer thought. If the model incorrectly flags convergence without an answer, or enters an infinite loop by continually requesting more thoughts without progressing, the host agent must intervene. The host assumes the responsibility of injecting an error correction prompt or terminating the loop based on a maximum iteration threshold. The tool is not intended to expose every thought to the user by default; rather, the raw sequence is primarily for the model's own context, while the parent agent or user receives the synthesized conclusion.
-
-## **3\. Public User Feedback and Common Requests**
-
-Real-world usage of sequential thinking tools and structured agent outputs highlights several critical failure modes and user requests that must directly inform the Savant-Code architecture.  
-A highly prevalent bug involves models, specifically the Claude 3.5 Sonnet and Qwen families, outputting stringified integers instead of native JSON integers for the thoughtNumber and totalThoughts fields5. Strict schema validation subsequently rejects these payloads, causing the entire agent loop to crash6. The design implication is that the tool adapter must implement permissive type coercion before applying strict schema validation, ensuring that minor serialization quirks do not derail the reasoning process3.  
-Furthermore, empirical research into structured output indicates that forcing an LLM to emit highly constrained JSON significantly degrades its reasoning capabilities, a phenomenon termed the "Format Tax"7. The cognitive overhead of balancing syntax with complex logic causes a measurable drop in accuracy, with lexical constraints reducing comprehensiveness by up to forty-eight percent8. The design implication is clear: the architecture must decouple reasoning from rigid formatting, allowing the primary thought field to remain free-form text while only enforcing strict JSON structure on the final output artifact7.  
-Developers also frequently note that providing a rigid output schema alongside native tool definitions breaks the agent loop. Models often fail to emit tool calls entirely when an output schema is present, or they output an empty schema, resulting in silent failures10. Additionally, within the MCP specification, ambiguity exists between the content and structuredContent fields in the tool result, leading to misaligned client implementations where data is either dropped or duplicated unnecessarily12. This indicates that the Thinker must not rely on provider-native structured output modes for the intermediate loop, instead utilizing standard tool-calling exclusively and reserving structured output parsing for a final, dedicated synthesis step.  
-The cancellation of agent execution, such as via an AbortController, frequently leads to corrupted state. If a tool call is in flight, abruptly terminating the stream leaves dangling connections or incomplete state projections, which confuses the orchestrator upon subsequent retries or resumptions14. The state machine must natively handle explicit cancellation events, ensuring partial tool calls are discarded and the snapshot remains pure.  
-Finally, users frequently report agents getting stuck in analysis paralysis, repeatedly analyzing identical context without progressing, which leaks raw, repetitive chain-of-thought data to the user17. This necessitates the host enforcing a hard iteration cap and implementing a state-based mechanism to detect and break cyclical reasoning before it exhausts the token budget.
-
-## **4\. Comparison of Existing Agent Designs**
-
-A comprehensive review of state-of-the-art agent architectures reveals a wide spectrum of approaches to state management, planning, and tool execution, each with distinct advantages and vulnerabilities.
-
-| System | Reasoning model | State owner | Tool-call protocol | Thought persistence | Final output contract | Retry behavior | Privacy model | Strengths | Weaknesses |
-| :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- |
-| **Claude Code** | ReAct (while loop) | Message History | JSON Tool Calls | Conversation context | Implicit (Text output) | Escalation (3 retries) | Mixed (visible CoT) | Simple, highly context-rich implementation19. | Highly vulnerable to context drift; implicit finalization leads to parsing errors19. |
-| **OpenCode (GraphAgent)** | DAG / Planners | CQRS Projection | JSON Events | Durable SQLite log | Strict State Transition | Event replay / replan | Hidden CoT | Immutable state, complete crash recovery21. | High complexity overhead in DAG orchestration. |
-| **Gemini CLI (Ralph)** | Self-referential loop | Persistent Buffer | Custom commands | In-place file state | Explicit string match | Clears history per turn | Hidden CoT | High reliability, aggressively avoids context flooding22. | Requires heavy file access to track state. |
-| **CAAF** | Recursive Atomic | Harness / Asset | Unified Assertion | Monotonic State Lock | Verified Assertion | Closed-loop fail-safe | Isolated | Eliminates stochastic oscillation entirely24. | Heavy overhead for simple reasoning tasks. |
-| **Zeroshot** | Executor/Verifier | SQLite Ledger | Native / Provider | Durable Ledger | Verifier Approval | Reproducible failure | Opaque | Strict separation of concerns27. | High latency due to independent verifier overhead. |
-
-The analysis indicates a stark divide between architectures that rely on the message history as the primary state store, such as Claude Code, and those that utilize explicit state machines or event ledgers, such as OpenCode and CAAF. Systems relying on message history frequently suffer from attention decay and state corruption during tool failures. Systems utilizing explicit event ledgers provide superior reliability and determinism, ensuring that the final output contract is strictly honored.
-
-## **5\. Diagnosis of the Current Conceptual Failure**
-
-The observed failures in the Savant-Code system, specifically the generation of successful structured outputs with null values and the failure of individual thoughts to stack reliably, are symptoms of a fundamental architectural flaw: the conflation of the generative message history with the operational state of the agent.  
-Currently, the system attempts to derive its authoritative state directly from the sequence of messages and streaming tool calls emitted by the LLM. This design inherently leads to severe race conditions. The LLM's streaming text, the parsed tool arguments, and the accumulated message array act as competing sources of truth. If a provider's streaming parser yields an incomplete argument, or if a network latency issue delays a chunk, the system might finalize the state prematurely based on incomplete information.  
-The specific anomaly of a successful structured output yielding a null value occurs when the LLM signals completion, perhaps by omitting a tool call or triggering a generic stop sequence such as end\_turn, but fails to populate the required schema fields20. Because the host adapter treats the absence of further tool calls as implicit success, it attempts to parse the final assistant message into the expected schema. If the model outputs free-text instead of the expected JSON, the parser yields null. However, the state machine erroneously advances to a completed status because no explicit programmatic errors were thrown during the execution loop.  
-Furthermore, relying on mutable arrays for thought accumulation means that if a tool call is interrupted, cancelled, or retried, partial objects remain in the history. This state contamination corrupts subsequent LLM prompts, causing the model to hallucinate or repeat previous thoughts, leading to infinite loops and the degradation of the sequential thinking process. To resolve these deeply embedded issues, the architecture must completely abandon implicit state derivation. The message history must be treated solely as an ephemeral communication medium, while the Thinker's state must be maintained in an isolated, strictly validated engine.
-
-## **6\. Candidate Architectures**
-
-Evaluating the potential design paradigms for the Thinker yields several candidate architectures, each measured against the requirements of determinism and reliability.  
-The first candidate is maintaining the message history as the source of truth, mirroring the current approach. This relies entirely on the LLM's transcript. This is rejected because it is highly brittle, susceptible to token truncation, and fundamentally vulnerable to the null output race condition.  
-The second candidate treats the tool results as the source of truth, updating the state only when a tool returns successfully. This is rejected because pre-tool thoughts and intermediate reasoning are permanently lost if a tool crashes, making debugging impossible and severely limiting the LLM's ability to self-correct based on its own documented planning.  
-The third candidate involves a dedicated, mutable ThoughtSession singleton object updated in memory. While better than relying on the transcript, this is rejected because it remains highly susceptible to race conditions during asynchronous streaming and is difficult to safely roll back upon cancellation or timeout.  
-The fourth candidate is a full planning graph, similar to OpenCode's GraphAgent21. This is rejected specifically for the Thinker agent because it is overly complex for a single child reasoning process, being better suited for the higher-level Orchestrator layer.  
-The final and recommended candidate is a hybrid Event Log combined with a derived state snapshot, implementing Command Query Responsibility Segregation (CQRS) and Event Sourcing. In this design, state changes are recorded as an append-only log of immutable events, and the current operational state is deterministically projected by folding the events. This establishes a single, unassailable source of truth that is immune to streaming race conditions and state corruption.
-
-## **7\. Recommended Custom Architecture**
-
-The recommended architecture for Savant-Code implements an Event-Sourced CQRS State Engine. This approach isolates the unpredictable nature of LLM generation from the rigorous requirements of agent state management.
-
-### **A. Agent Responsibilities**
-
-The parent Orchestrator retains ownership of the overarching task definition, dependency injection, and overall execution budgets. It spawns the Thinker, awaits a definitive resolution, and handles terminal failures without concerning itself with the child's internal reasoning loop.  
-The Thinker agent loop manages the ReAct execution cycle. It handles the prompt context window, communicates with the LLM, and translates the model's outputs into explicit commands dispatched to the State Engine.  
-The State Engine serves as the authoritative core of the system. It strictly owns the Event Log, enforces the lifecycle State Machine, validates all transitions against predefined invariants, and projects the current Thought Snapshot.  
-The LLM Provider Adapter is responsible for normalizing provider-specific streaming, tool-calling formats, and role assignments into standard Savant-Code internal events, executing necessary type coercion before the data reaches the core engine6.  
-The Tool Executor strictly processes authorized capabilities. It receives commands from the State Engine, executes the underlying native code, and returns raw results back to the engine.  
-The Final-Output Adapter synthesizes the final Read Model into the strict, parent-facing output contract, while the UI/Client is restricted to reading from the Event Log via subscriptions, ensuring it never mutates state directly.
-
-### **B. Single Source of Truth**
-
-The append-only Event Log is established as the exclusive source of truth. When the LLM provider streams a tool call, the adapter translates it into a Command. The State Engine validates this Command against the current State Machine. If valid, the Engine commits an Event, such as ThoughtAppended, to the log. The Snapshot, which is the data structure sent back to the LLM as context, is strictly derived by reducing the Event Log.  
-This mechanism structurally prevents lost or duplicate thoughts because events are assigned monotonic sequence identifiers, making it impossible to append the same sequence twice. Premature finalization and null outputs are prevented because the state machine strictly requires a ConvergenceValidated event, containing a fully validated schema payload, before it permits the state to become completed. Furthermore, stale state after cancellation is eliminated; a CancellationRequested event freezes the engine, causing any subsequent in-flight tool results to be instantly rejected because the state is no longer actively running.
-
-## **8\. Typed Data Model**
-
-To enforce absolute determinism across the architecture, vague types, dynamic arbitrary records, and nullable success states are strictly prohibited. The domain is modeled using explicit, rigid interfaces.
-
-| Category | Field | Type | Attributes | Description |
-| :---- | :---- | :---- | :---- | :---- |
-| **Identifiers** | sessionId | String (UUID) | Required, Immutable | Bounds the full orchestrator task and provides security isolation. |
-| **Identifiers** | runId | String (UUID) | Required, Immutable | Unique identifier for the specific Thinker instantiation. |
-| **Identifiers** | sequenceId | Integer | Required, Immutable | Monotonically increasing counter tracking absolute event order. |
-| **Identifiers** | eventId | String (UUID) | Required, Immutable | Unique identifier for the specific state event. |
-| **State** | thoughtId | String (UUID) | Required, Immutable | Unique identifier for the individual thought node. |
-| **State** | thoughtNumber | Integer | Required, Mutable | The logical sequence number assigned by the LLM. |
-| **State** | branchId | String | Optional, Mutable | The identifier of the active reasoning branch. |
-| **State** | revisesThoughtId | String (UUID) | Optional, Immutable | Logical pointer to the historical node being superseded. |
-| **Content** | thoughtText | String | Required, Immutable | The free-form reasoning text generated by the model. |
-| **Execution** | status | Enum | Required, Mutable | The current operational status of the state machine. |
-| **Execution** | timestamp | ISO String | Required, Immutable | Absolute time of event committal. |
-
-Visibility classifications must be strictly enforced. Provider-specific tool call IDs, raw error stack traces, and intermediate JSON parse states are internal-only and never exposed to the parent agent. The raw thought graph constitutes private Chain-of-Thought; to prevent confusing the user or leaking internal planning, it is suppressed from the primary user-visible output, though it remains available for debugging17. Only the synthesized final result, task metadata, and elapsed duration are deemed safe for parent and user consumption.
-
-## **9\. Lifecycle State Machine**
-
-The Thinker's lifecycle is governed by a strict deterministic state machine designed to trap and handle all failure modes securely.  
-The lifecycle begins in the created state, awaiting the start signal from the orchestrator. Upon initialization, it enters the running state, which serves as the primary loop awaiting LLM generation. When the LLM emits a sequential-thinking tool call, the engine transitions to the thinking state to process and append the thought node, immediately returning to running upon successful committal. If a native tool execution is requested, the system enters the awaiting\_tool\_result state, remaining suspended until the promise resolves.  
-The critical phase occurs when the LLM signals completion, transitioning the system to the evaluating\_convergence state. Here, the output adapter validates the payload. If successful, the machine reaches the terminal completed state. Terminal failure states include failed, triggered by budget exhaustion, maximum retries, or fatal schema validation, and cancelled, triggered by an explicit halt from the orchestrator.  
-The exact invariant that prevents a successful structured output with a null value is enforced during the evaluating\_convergence transition. This transition may only proceed to completed if the payload perfectly matches the FinalOutputSchema. If the payload is null, undefined, or malformed, the transition is explicitly blocked. The engine automatically reverts to the running state, appending a SchemaValidationError event to the log, forcing the LLM to self-correct its output before termination is permitted.
-
-## **10\. Tool Contract**
-
-To circumvent the cognitive degradation associated with the Format Tax7, the sequential-thinking tool contract intentionally avoids forcing the LLM to write complex nested JSON for its analytical reasoning.  
-The input schema sent to the model dictates that the thought field remains free-form text. It includes necessary metadata fields such as thoughtNumber, isRevision, revisesThought, and branchId. The LLM signals its intent to conclude the process by setting the nextThoughtNeeded boolean to false. Crucially, the domain-specific final output schema is nested within a conclusion object, which the model is instructed to populate only when nextThoughtNeeded is false.  
-Upon receiving the tool call, the tool returns a concise metadata payload to the LLM rather than a complete session snapshot, thereby conserving the context window. The result schema acknowledges the appended thought number, confirms the active branch, and provides an instruction to either continue reasoning or correct a validation failure.  
-The LLM determines when it wishes to attempt convergence, but the host State Engine retains ultimate authority over whether that convergence is valid. If the tool call is malformed, the adapter attempts permissive type coercion. If coercion fails, a tool result containing the exact JSON parsing error is returned to the LLM, prompting immediate self-correction. If the model continually submits valid tool calls that do not converge, the host monitors the iteration count, ultimately distinguishing between a model requiring extended thought and a systemic loop by enforcing a strict maximum iteration ceiling.
-
-## **11\. Final Output Contract**
-
-To decisively solve the null-output bug while addressing privacy concerns regarding exposed Chain-of-Thought, the architecture adopts a dual-output model. A valid run must yield a strict artifact, and it is structurally impossible for a successful completion to return a null value.  
-The parent agent receives a guaranteed, typed FinalArtifact. This artifact contains a status indicating success, a synthesis string providing a concise explanation of how the conclusion was reached, the payload containing the non-null structured output demanded by the orchestrator, and operational metrics such as total thoughts and duration.  
-The user interface receives real-time status updates, such as notifications that the Thinker is evaluating specific branches, but it does not render the raw thought graph by default. Upon completion, the UI displays the concise synthesis.  
-In the event of bounded non-convergence, where the Thinker hits the iteration limit without converging, it transitions to the failed state and returns an artifact indicating exhaustion, providing whatever partial synthesis was achieved alongside the error reason. If the model outputs nextThoughtNeeded: false but omits the conclusion payload, the State Engine blocks the completed transition, appends a warning to the LLM, and forces the loop to continue. If the final output schema validation fails, the exact error is similarly fed back to the model for correction.  
-Example of a Successful Multi-Thought Convergence Object:
-
-JSON  
-{  
-  "status": "success",  
-  "synthesis": "Analyzed three approaches for the database migration. Selected the hybrid approach due to zero-downtime constraints.",  
-  "payload": {  
-    "recommendedStrategy": "hybrid",  
-    "estimatedDowntimeSeconds": 0,  
-    "riskLevel": "medium"  
-  },  
-  "metrics": {  
-    "totalThoughts": 4,  
-    "durationMs": 12450  
-  }  
-}
-
-Example of Bounded Non-Convergence:
-
-JSON  
-{  
-  "status": "exhausted",  
-  "synthesis": "Analysis halted. Evaluated initial parameters but failed to isolate the root cause within the allocated step budget.",  
-  "payload": null,  
-  "metrics": {  
-    "totalThoughts": 20,  
-    "durationMs": 45000  
-  },  
-  "error": "Maximum iteration limit of 20 reached without valid convergence payload."  
-}
-
-## **12\. Streaming and Provider Boundary**
-
-The architecture must operate seamlessly across Anthropic, OpenAI, Gemini, and local models, requiring a robust and independent provider boundary.  
-The minimum provider adapter contract requires the implementation of a unified StreamParser. This parser buffers byte deltas and yields complete ProviderMessage objects. To support real-time UI rendering, the adapter implements abstract syntax tree (AST) based partial parsing to extract text as it streams29. However, this partial stream is strictly quarantined from the State Engine, which only acts on ToolCallCompleted events emitted when the underlying promise fully resolves.  
-Ordering is guaranteed via a strict mutex lock on the event bus. If a model emits multiple parallel native tool calls, they are enqueued and processed sequentially by the State Engine, guaranteeing that appended events remain ordered and monotonic.  
-Cancellation safety is paramount. If a stream is cancelled, the adapter aborts the network request utilizing standard AbortController mechanisms15 and emits a StreamAborted event. Because the State Engine only writes state upon completed tool calls, the partial text is safely discarded without rolling back or contaminating the operational state.  
-Furthermore, the provider boundary manages prompt caching strategies. In systems like Anthropic, utilizing cache\_control markers provides significant cost and latency reductions32. However, mutating tool arrays or system prompts between calls automatically busts the prefix cache, driving up costs33. Therefore, the adapter guarantees that the tool definitions and static system instructions remain absolutely deterministic across the duration of the run.
-
-## **13\. Parent/Child Event Contract**
-
-Communication between the Orchestrator and the Thinker is strictly mediated over a typed asynchronous Event Bus, preventing tight coupling and unhandled promise rejections.  
-The flow initiates with a SpawnRequest from the parent to initialize the Thinker, acknowledged by a ChildStartEvent. The internal operations, including ThoughtEvent, ToolCallEvent, and ToolResultEvent, remain isolated within the Thinker's sandbox and are specifically not forwarded to the parent to prevent context window flooding.  
-Upon successful validation, the Thinker issues a ConvergenceEvent containing the final payload. Terminal states are communicated via a FinalResultEvent for success or a FailureEvent containing specific error codes for orchestrator handling. If the orchestrator determines the task is no longer necessary, it issues a CancellationEvent, which triggers a graceful termination sequence within the Thinker, followed by a CleanupEvent confirming the release of resources.
-
-## **14\. Security and Privacy Model**
-
-The security and privacy model addresses the exposure of internal reasoning and unauthorized tool execution.  
-LLM reasoning traces frequently contain hallucinations, abandoned hypotheses, and verbose, unstructured text. Consequently, the raw thought graph is classified as highly sensitive internal state. It is systematically stripped from the final artifact sent to the parent orchestrator, preventing the parent from being contaminated by irrelevant or contradictory context17.  
-Tool isolation is enforced through a restricted capability sandbox. The Orchestrator passes a strict whitelist of tools to the Thinker upon instantiation. The Thinker physically cannot route a call to a parent tool because the schema is never exposed to its LLM instance. Any LLM attempt to request unauthorized tools results in a deterministic UnauthorizedToolError being returned to the model, completely preventing execution36.  
-To mitigate context window overflow and attention decay in exceptionally long reasoning chains, the State Engine implements automatic context compaction. It seamlessly summarizes branches of the thought graph that have been marked obsolete by revision events, ensuring the model remains focused on the active hypothesis26.
-
-## **15\. Testing Strategy**
-
-The event-sourced architecture enables a rigorous, deterministic testing protocol.  
-Unit tests for the State Engine will assert stacking and ordering, verifying that events appended out of order are categorically rejected by the sequence ID check. Tests will validate revisions and branches, asserting that revising node two updates the active branch pointer without mutating or deleting the original node two data. Crucially, convergence invariants will be tested by submitting a ConvergenceRequested event with a null payload, asserting that the engine throws a SchemaViolationError and firmly remains in the running state. Type coercion logic will be tested to ensure stringified integers are successfully cast prior to state integration.  
-Integration tests will mock provider streams yielding partial JSON, asserting the State Engine remains un-mutated until the stream is explicitly finalized. Null prevention will be tested by mocking an LLM that perpetually returns nextThoughtNeeded: false without a payload, verifying the system halts with an exhausted status rather than a false success. Live Command Line Interface (CLI) tests will execute scripted tasks against live Anthropic and OpenAI endpoints to verify cross-provider compatibility and payload extraction integrity under real network conditions.
-
-## **16\. Perfection Loop — RED**
-
-An adversarial critique of the proposed architecture identifies several potential vulnerabilities.  
-First, event sourcing introduces significant complexity and boilerplate code. Implementing a full CQRS pattern for a localized reasoning loop could be considered over-engineering, potentially complicating maintenance for future developers unfamiliar with the pattern.  
-Second, if the Thinker rejects a null payload and prompts the LLM to correct it, the model might stubbornly repeat the exact same invalid response. This creates an infinite loop risk, burning tokens endlessly without ever triggering the formal exhaustion limit if not explicitly tracked.  
-Third, testing asynchronous, late-arriving tool results presents a gap. If a network request hangs and resolves after the state machine has already transitioned due to a timeout or cancellation, it could cause unhandled promise rejections or attempt to mutate a frozen state.  
-Finally, there is a risk of accidentally recreating the original bug. If the Final-Output Adapter is implemented such that it uses standard parsing on the raw LLM text rather than exclusively extracting data from the validated ConvergenceValidated event, the null bug will immediately resurface, bypassing the state machine entirely.
-
-## **17\. Perfection Loop — GREEN**
-
-The defense and refinement of the architecture address these critiques systematically.  
-The complexity of Event Sourcing is entirely justified. The current system's reliance on mutable arrays and implicit message history is the direct cause of the unfixable race conditions. Event sourcing is the only mathematically proven methodology to guarantee distributed state consistency across asynchronous streams, as demonstrated by robust architectures like OpenCode21. We mitigate the boilerplate overhead by utilizing a lightweight, in-memory reducer rather than integrating a heavy database backend.  
-To address the infinite loop risk, we introduce a hard consecutive\_error\_cap within the state machine. If the LLM fails schema validation a consecutive number of times (e.g., three), the State Engine forcefully transitions to the failed state, preventing catastrophic token burn.  
-Regarding late-arriving tool results, the State Machine's guard logic inherently solves this. Any late event is validated against the current state. If the state is cancelled or has advanced past awaiting\_tool\_result, the event is categorically rejected and safely dropped, preventing corruption.  
-To ensure the null bug is not recreated, the Final-Output Adapter will be strictly typed to accept only the Read Model snapshot as input. By physically isolating the adapter from the raw LLM text stream, it becomes impossible for it to parse unvalidated data.
-
-## **18\. Perfection Loop — AUDIT**
-
-The proposed design is stress-tested against eighteen specific adversarial scenarios:
-
-> 1. **One valid thought and immediate convergence:** Handled effortlessly. The system transitions from running to evaluating\_convergence to completed.  
-> 2. **Three sequential thoughts:** Handled by monotonically appending events to the log.  
-> 3. **A revision after thought three:** The event log records isRevision: true and revisesThought: 3\. The Read Model updates the active pointer accordingly.  
-> 4. **Two branches from thought one:** The DAG correctly maps multiple active tips, tracking them via unique branch identifiers.  
-> 5. **A provider sends {} before the real arguments:** The StreamParser handles these empty streaming chunks but only emits the Command to the State Engine when the provider signals tool\_call\_completed, rendering the anomaly harmless.  
-> 6. **A provider truncates the final argument:** The JSON parser within the adapter fails, and the State Engine returns a parsing error message directly to the LLM for correction.  
-> 7. **Two concurrent Thinker runs use the same model:** Fully isolated by unique UUID runIds. Their event buses do not share memory space.  
-> 8. **A tool result arrives late:** Rejected by the State Machine's guard logic, as the system is no longer in the awaiting\_tool\_result state.  
-> 9. **The model repeats the same tool-call ID:** The event log detects the duplicate Command ID and idempotently drops it.  
-> 10. **The model says nextThoughtNeeded: false without a useful conclusion:** Fails the convergence invariant check. Transitions back to running with error context provided to the model.  
-> 11. **The model never sets nextThoughtNeeded: false:** The exhaustion limit (e.g., 50 iterations) is triggered, transitioning the state to failed.  
-> 12. **The parent cancels the child during a tool call:** The Cancelled event freezes the State Engine. The tool executor is aborted via the injected AbortController15.  
-> 13. **The finalizer crashes after state convergence:** Handled by the parent orchestrator's try/catch wrapping the promise; yields a failed status gracefully.  
-> 14. **Output validation fails:** Safely rejected at the evaluating\_convergence state, prompting LLM correction.  
-> 15. **The child returns to the parent after cleanup:** Impossible; the completed state emits exactly once and immediately closes the event bus.  
-> 16. **The model attempts an unauthorized tool:** Filtered out at prompt construction. If hallucinated, the adapter returns a ToolNotFound error to the model.  
-> 17. **The provider emits raw XML instead of a structured call:** The adapter fails to parse and emits a FormatError event back to the LLM.  
-> 18. **The parent receives a result while the child still has pending work:** The ConvergenceValidated event is the final permitted action. Work is synchronously drained before the event emission, making this impossible.
-
-## **19\. Perfection Loop — SELF-CORRECT**
-
-Based on the audit, the architecture requires one specific, critical adjustment: the formalization of an explicit ErrorHandlingPolicy within the State Engine.  
-To definitively address scenarios 10 and 11, the State Engine cannot merely rely on the LLM to eventually fix its own mistakes, as this invites infinite loops. The Engine must maintain an internal consecutiveErrorCount. If the LLM provides an empty conclusion on convergence, or outputs malformed XML instead of JSON, the Engine increments this counter. If the counter exceeds the predefined threshold, the Engine preemptively terminates the run with status: failed. This self-correction ensures that the system is entirely protected against silent, token-burning loops, folding robust operational safety directly into the final architecture.
-
-## **20\. Perfection Loop — COMPLETE**
-
-The final converged architecture provides a mathematically sound, fail-safe environment for the Thinker agent. It is built on four core principles. First, CQRS Event Sourcing ensures the total separation of the unpredictable LLM stream from the authoritative operational state. Second, Strict State Guardrails guarantee that the completed state is gated by a synchronous validation of the final conclusion schema, preventing null outputs. Third, Decoupled Formatting avoids the Format Tax by allowing the LLM to reason in free-form strings, reserving strict JSON mapping solely for the final output step. Finally, Fail-Safe Termination utilizes hard budgets and consecutive error counters to prevent infinite stochastic loops.
-
-## **21\. Migration Strategy**
-
-Transitioning Savant-Code from the brittle legacy Thinker to the Event-Sourced architecture must be executed in a phased approach to prevent regressions.  
-Phase 1 involves deploying the Shadow State Engine. Implement the State Engine and Event Log, running the existing Thinker alongside it. Pump the old tool-call events into the new engine and assert that the new Read Model matches the expected outcome without disrupting the live system.  
-Phase 2 focuses on UI Detachment. Refactor the UI client to render exclusively from the new Read Model rather than parsing the volatile message history.  
-Phase 3 is the Hard Cutover. Swap the core execution loop to rely entirely on the State Engine transitions, officially deprecating and removing the legacy message-parsing logic.  
-Phase 4 entails Schema Hardening. Introduce the strict final output invariants and activate the consecutive error limits, finalizing the transition to a fully deterministic system.
-
-## **22\. Five ECHO Questions**
-
-> 1. **Will it work for all valid thought sequences, not just linear happy paths?** Yes. The event log seamlessly represents complex DAG structures, including revisions and branches, by storing relational node references rather than relying on brittle array indices.  
-> 2. **Will it scale to 1,000 concurrent agents?** Yes. Because operational state is isolated per unique runId and requires no shared database locking, scaling concurrency is limited only by node process memory and external API rate limits.  
-> 3. **Will it survive hostile or malformed model output?** Yes. Malformed output fails validation, increments the isolated error counter, and is fed back for correction without ever mutating the core snapshot.  
-> 4. **Will it remain maintainable in two years?** Yes. Event sourcing is highly auditable. Debugging a failed agent run involves simply replaying the event array to see exactly where the state machine rejected a transition, making long-term maintenance straightforward.  
-> 5. **Does it establish an industry-quality standard rather than merely patching the current bug?** Yes. This architecture moves Savant-Code away from script-like orchestration and aligns it with enterprise-grade deterministic distributed systems architecture, echoing the rigorous design philosophies of frameworks like CAAF and OpenCode21.
-
-## **23\. Remaining Risks**
-
-While the architecture resolves the primary vulnerabilities, certain risks remain. Context window pressure is a persistent challenge; because the Thinker does not return the full snapshot to the LLM on every turn to save tokens, the LLM must rely on its own message history to remember its thoughts. In exceptionally long reasoning chains, attention decay may occur26. This must be mitigated by implementing periodic prompt compaction that injects a synthesized summary of the active thought graph back into the context.  
-Furthermore, provider API drift poses an ongoing risk. Changes to how OpenAI, Anthropic, or Gemini handle native tool calls, specifically regarding prompt caching mechanisms and streaming formats, could break the Provider Adapter. This risk is mitigated by strictly adhering to abstract interface boundaries, ensuring provider-specific quirks do not bleed into the State Engine.
-
-## **24\. Final Recommendation**
-
-**Build.**  
-The legacy Thinker's reliance on message history and implicit state finalization is a structural dead end. It cannot be patched to achieve absolute reliability because streaming text and asynchronous tool execution are inherently subject to race conditions and token degradation.  
-The proposed Event-Sourced CQRS State Machine fundamentally eliminates the possibility of a successful output containing a null value by elevating schema validation to a strict, impassable state-transition gate. It provides absolute determinism, protects the orchestrator from private Chain-of-Thought leakage, bypasses the cognitive degradation of the Format Tax, and establishes a robust, extensible foundation for Savant-Code's multi-agent future. Implementation of Phase 1 of the migration strategy should commence immediately.
-
-### **Works cited**
-
-> 1. Sequential Thinking MCP Server \- Forked to Support SSE · GitHub, [https://github.com/light4/mcp-server-sequentialthinking](https://github.com/light4/mcp-server-sequentialthinking)  
-> 2. servers/src/sequentialthinking/README.md at main · modelcontextprotocol/servers \- GitHub, [https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/README.md)  
-> 3. servers/src/sequentialthinking/index.ts at main · modelcontextprotocol/servers \- GitHub, [https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/index.ts](https://github.com/modelcontextprotocol/servers/blob/main/src/sequentialthinking/index.ts)  
-> 4. hyokunkwak/Sequential-thinking-ultra-mcp \- GitHub, [https://github.com/hyokunkwak/Sequential-thinking-ultra-mcp](https://github.com/hyokunkwak/Sequential-thinking-ultra-mcp)  
-> 5. sequentialthinking: Invalid totalThoughts: must be a number · Issue \#2473 \- GitHub, [https://github.com/modelcontextprotocol/servers/issues/2473](https://github.com/modelcontextprotocol/servers/issues/2473)  
-> 6. Claude Code Sonnet 4.5 randomly crash with sequentialthinking (MCP) \#2792 \- GitHub, [https://github.com/modelcontextprotocol/servers/issues/2792](https://github.com/modelcontextprotocol/servers/issues/2792)  
-> 7. The Format Tax \- arXiv, [https://arxiv.org/html/2604.03616v1](https://arxiv.org/html/2604.03616v1)  
-> 8. One Token Away from Collapse: The Fragility of Instruction-Tuned Helpfulness \- arXiv, [https://arxiv.org/html/2604.13006v1](https://arxiv.org/html/2604.13006v1)  
-> 9. Thinking Before Constraining: A Unified Decoding Framework for Large Language Models, [https://arxiv.org/html/2601.07525v2](https://arxiv.org/html/2601.07525v2)  
-> 10. \[BUG\] generateVNext with Structured Output and Tools · Issue \#7662 \- GitHub, [https://github.com/mastra-ai/mastra/issues/7662](https://github.com/mastra-ai/mastra/issues/7662)  
-> 11. Structured Output (output schema) \+ Tool Call · Issue \#701 · google/adk-python \- GitHub, [https://github.com/google/adk-python/issues/701](https://github.com/google/adk-python/issues/701)  
-> 12. What is the expected usage of structuredContent vs content in CallToolResult ? \#1563, [https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1563](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1563)  
-> 13. SEP-1624: Clarify \`structuredContent\` vs \`content\` Usage Guidance \- GitHub, [https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1624](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1624)  
-> 14. Support passing AbortSignal in query() · Issue \#2774 · brianc/node-postgres \- GitHub, [https://github.com/brianc/node-postgres/issues/2774](https://github.com/brianc/node-postgres/issues/2774)  
-> 15. Feature Request: Enhanced Run Lifecycle Management \- Interrupt Active Runs · Issue \#729 · openai/openai-agents-js \- GitHub, [https://github.com/openai/openai-agents-js/issues/729](https://github.com/openai/openai-agents-js/issues/729)  
-> 16. Tool unregistration design · Issue \#130 · webmachinelearning/webmcp \- GitHub, [https://github.com/webmachinelearning/webmcp/issues/130](https://github.com/webmachinelearning/webmcp/issues/130)  
-> 17. Gemini 3 Pro: Model stuck in a loop of leaked CoT content · Issue \#18520 \- GitHub, [https://github.com/google-gemini/gemini-cli/issues/18520](https://github.com/google-gemini/gemini-cli/issues/18520)  
-> 18. Feature Request: Enhanced Agentic Planning Mode for Gemini CLI · Issue \#7383 \- GitHub, [https://github.com/google-gemini/gemini-cli/issues/7383](https://github.com/google-gemini/gemini-cli/issues/7383)  
-> 19. VILA-Lab/Dive-into-Claude-Code \- GitHub, [https://github.com/VILA-Lab/Dive-into-Claude-Code](https://github.com/VILA-Lab/Dive-into-Claude-Code)  
-> 20. architecture.md \- claude-code-ultimate-guide \- GitHub, [https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md)  
-> 21. LeXwDeX/OpenCode-GraphAgent: Extends the Hooks API, Directed Acyclic Graph Agent Execution Engine. \- GitHub, [https://github.com/LeXwDeX/opencode](https://github.com/LeXwDeX/opencode)  
-> 22. Gemini CLI extension for Ralph loops \- GitHub, [https://github.com/gemini-cli-extensions/ralph](https://github.com/gemini-cli-extensions/ralph)  
-> 23. Feature Request: Split-Pane "Live Workspace" – Decoupling Chat Dialogue from Persistent Project Context · google-gemini gemini-cli · Discussion \#17743 \- GitHub, [https://github.com/google-gemini/gemini-cli/discussions/17743](https://github.com/google-gemini/gemini-cli/discussions/17743)  
-> 24. Harness as an Asset: Enforcing Determinism via the Convergent AI Agent Framework (CAAF) \- arXiv, [https://arxiv.org/html/2604.17025v3](https://arxiv.org/html/2604.17025v3)  
-> 25. \[2604.17025\] Harness as an Asset: Enforcing Determinism via the Convergent AI Agent Framework (CAAF) \- arXiv, [https://arxiv.org/abs/2604.17025](https://arxiv.org/abs/2604.17025)  
-> 26. Harness as an Asset: Enforcing Determinism via the Convergent AI Agent Framework (CAAF) \- arXiv, [https://arxiv.org/pdf/2604.17025](https://arxiv.org/pdf/2604.17025)  
-> 27. GitHub \- the-open-engine/zeroshot: Your autonomous engineering team in a CLI. The agent loop produces senior-level code that you can actually trust in prod because of non-negotiable feedback from independent reviewers. Supports Claude Code, OpenAI Codex, OpenCode, and Gemini CLI with trivial setup., [https://github.com/the-open-engine/zeroshot](https://github.com/the-open-engine/zeroshot)  
-> 28. Structured output \+ thinking \+ tool use: two bugs in multi-turn conversations · Issue \#1204 · anthropics/anthropic-sdk-python \- GitHub, [https://github.com/anthropics/anthropic-sdk-python/issues/1204](https://github.com/anthropics/anthropic-sdk-python/issues/1204)  
-> 29. langchain/libs/core/langchain\_core/output\_parsers/openai\_tools.py at master \- GitHub, [https://github.com/langchain-ai/langchain/blob/master/libs/core/langchain\_core/output\_parsers/openai\_tools.py](https://github.com/langchain-ai/langchain/blob/master/libs/core/langchain_core/output_parsers/openai_tools.py)  
-> 30. teamchong/vectorjson: O(n) streaming JSON parser for LLM tool calls. Agents act sooner, abort bad outputs early. WASM SIMD, up to 2000× faster than stock AI SDK parsers. · GitHub, [https://github.com/teamchong/vectorjson](https://github.com/teamchong/vectorjson)  
-> 31. anthropic-sdk-typescript/helpers.md at main \- GitHub, [https://github.com/anthropics/anthropic-sdk-typescript/blob/master/helpers.md](https://github.com/anthropics/anthropic-sdk-typescript/blob/master/helpers.md)  
-> 32. leonhail-nell/prompt-cache-optimizer: Drop-in wrappers for the Anthropic, OpenAI, and Gemini SDKs that make prompt caching effortless. Measure real cache hit rate from the response usage object, attach dollar savings to every call, canonicalize shuffled tools and RAG document order so a "slightly different" payload still hits the cache. · GitHub, [https://github.com/leonhail-nell/prompt-cache-optimizer](https://github.com/leonhail-nell/prompt-cache-optimizer)  
-> 33. Anthropic Caching is not working with generateObject · Issue \#5227 · vercel/ai \- GitHub, [https://github.com/vercel/ai/issues/5227](https://github.com/vercel/ai/issues/5227)  
-> 34. Prompt cache miss on resume: Agent tool description enumerates sub-agents in non-deterministic order · Issue \#49038 · anthropics/claude-code \- GitHub, [https://github.com/anthropics/claude-code/issues/49038](https://github.com/anthropics/claude-code/issues/49038)  
-> 35. Prompt cache fully re-created after turns with many parallel tool calls (cache\_read collapses to system+tools floor) — \~74% of cache writes wasted on Opus 4.8 / v2.1.15x · Issue \#63930 · anthropics/claude-code \- GitHub, [https://github.com/anthropics/claude-code/issues/63930](https://github.com/anthropics/claude-code/issues/63930)  
-> 36. slowmist/openclaw-security-practice-guide \- GitHub, [https://github.com/slowmist/openclaw-security-practice-guide](https://github.com/slowmist/openclaw-security-practice-guide)