docs(gmi): document LoopController duplication and future refactor path

The GMI's processTurnStream() maintains an inline tool-calling loop that
duplicates the LoopController's ReAct loop.  After careful assessment,
a full replacement (Option A) or partial delegation (Option B) is too
risky: the GMI loop carries RAG retrieval, prompt reconstruction via
PromptEngine, persona-scoped tool orchestration, GMI state transitions,
streaming via generateCompletionStream, capability discovery filtering,
and GMIError-based fail_closed semantics — none of which the generic
LoopController abstracts.

Instead (Option C):
- Add a detailed comment block in GMI.processTurnStream() documenting
  all GMI-specific concerns that prevent a drop-in replacement
- Outline a future refactor path: extract RAG+prompt-build into a
  pre-iteration callback and tool-dispatch into a LoopContext adapter
- Add a corresponding note in LoopController.ts pointing back to the
  GMI loop documentation
- The configurable maxToolLoopIterations (added in a prior commit)
  keeps the safety break in sync with LoopController's maxIterations

Author: jddunn

src/api/__tests__/chainOfThought.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const hoisted = vi.hoisted(() => {
+  const generateCompletion = vi.fn();
+  const getProvider = vi.fn(() => ({ generateCompletion }));
+  const createProviderManager = vi.fn(async () => ({ getProvider }));
+  return {
+    generateCompletion,
+    getProvider,
+    createProviderManager,
+  };
+});
+
+vi.mock('../model.js', () => ({
+  resolveModelOption: vi.fn(() => ({ providerId: 'openai', modelId: 'gpt-4.1-mini' })),
+  resolveProvider: vi.fn(() => ({
+    providerId: 'openai',
+    modelId: 'gpt-4.1-mini',
+    apiKey: 'test-key',
+  })),
+  createProviderManager: hoisted.createProviderManager,
+}));
+
+import { generateText } from '../generateText.js';
+import { DEFAULT_COT_INSTRUCTION } from '../generateText.js';
+
+describe('chainOfThought', () => {
+  beforeEach(() => {
+    hoisted.generateCompletion.mockReset();
+    hoisted.generateCompletion.mockResolvedValue({
+      modelId: 'gpt-4.1-mini',
+      usage: { promptTokens: 10, completionTokens: 5, totalTokens: 15 },
+      choices: [
+        {
+          message: { role: 'assistant', content: 'response text' },
+          finishReason: 'stop',
+        },
+      ],
+    });
+  });
+
+  it('does not inject CoT instruction when chainOfThought is disabled', async () => {
+    await generateText({
+      model: 'openai:gpt-4.1-mini',
+      prompt: 'hello',
+      system: 'You are a helper.',
+      tools: { my_tool: { description: 'A tool', parameters: {} } },
+      chainOfThought: false,
+    });
+
+    const messages = hoisted.generateCompletion.mock.calls[0][1];
+    const systemMsg = messages.find((m: any) => m.role === 'system');
+    expect(systemMsg.content).toBe('You are a helper.');
+    expect(systemMsg.content).not.toContain('Before choosing an action');
+  });
+
+  it('injects default CoT instruction when chainOfThought is true', async () => {
+    await generateText({
+      model: 'openai:gpt-4.1-mini',
+      prompt: 'hello',
+      system: 'You are a helper.',
+      tools: { my_tool: { description: 'A tool', parameters: {} } },
+      chainOfThought: true,
+    });
+
+    const messages = hoisted.generateCompletion.mock.calls[0][1];
+    const systemMsg = messages.find((m: any) => m.role === 'system');
+    expect(systemMsg.content).toContain(DEFAULT_COT_INSTRUCTION);
+    expect(systemMsg.content).toContain('You are a helper.');
+  });
+
+  it('injects custom CoT instruction when chainOfThought is a string', async () => {
+    const customCot = 'Think step by step before answering.';
+
+    await generateText({
+      model: 'openai:gpt-4.1-mini',
+      prompt: 'hello',
+      system: 'You are a helper.',
+      tools: { my_tool: { description: 'A tool', parameters: {} } },
+      chainOfThought: customCot,
+    });
+
+    const messages = hoisted.generateCompletion.mock.calls[0][1];
+    const systemMsg = messages.find((m: any) => m.role === 'system');
+    expect(systemMsg.content).toContain(customCot);
+    expect(systemMsg.content).toContain('You are a helper.');
+    expect(systemMsg.content).not.toContain(DEFAULT_COT_INSTRUCTION);
+  });
+});

src/api/agent.ts

@@ -37,6 +37,13 @@ export interface AgentOptions extends BaseAgentConfig {
    * When present, forwarded to `observability.usageLedger` internally.
    */
   usageLedger?: AgentOSUsageLedgerOptions;
+  /**
+   * Chain-of-thought reasoning instruction.
+   * - `false` — disable CoT injection.
+   * - `true` (default for agents) — inject the default CoT instruction when tools are present.
+   * - `string` — inject a custom CoT instruction when tools are present.
+   */
+  chainOfThought?: boolean | string;
 }
 
 /**
@@ -185,6 +192,7 @@ export function agent(opts: AgentOptions): Agent {
     system: buildSystemPrompt(opts),
     tools: opts.tools,
     maxSteps: opts.maxSteps ?? 5,
+    chainOfThought: opts.chainOfThought ?? true,
     apiKey: opts.apiKey,
     baseUrl: opts.baseUrl,
     usageLedger: effectiveLedger,

src/cognitive_substrate/GMI.ts

@@ -805,6 +805,31 @@ export class GMI implements IGMI {
         }
       }
 
+      // -------------------------------------------------------------------
+      // Main tool-calling loop (ReAct-style).
+      //
+      // NOTE: This loop duplicates the general-purpose LoopController
+      // (src/orchestration/runtime/LoopController.ts) but carries
+      // GMI-specific concerns that prevent a simple drop-in replacement:
+      //
+      //   - RAG retrieval + cognitive memory assembly on each iteration
+      //   - Full prompt reconstruction via PromptEngine per iteration
+      //   - Tool orchestration through IToolOrchestrator with persona-scoped
+      //     ToolExecutionRequestDetails (gmiId, capabilities, sessionData)
+      //   - GMIPrimeState transitions (PROCESSING <-> AWAITING_TOOL_RESULT)
+      //   - Streaming via provider.generateCompletionStream() rather than
+      //     the LoopController's AsyncGenerator<LoopChunk> abstraction
+      //   - Capability discovery tool filtering per iteration
+      //   - GMIError-based fail_closed semantics with structured error codes
+      //
+      // Future refactor path: extract the RAG + prompt-build phase into a
+      // pre-iteration callback and the tool-dispatch phase into a
+      // LoopContext adapter, then delegate the iteration/termination logic
+      // to LoopController.execute().  This would unify the safety-break,
+      // parallel-tools, and fail_open/fail_closed policies.  For now the
+      // configurable maxToolLoopIterations (GMIBaseConfig) keeps the safety
+      // break in sync with LoopController's maxIterations concept.
+      // -------------------------------------------------------------------
       let safetyBreak = 0;
       const maxToolLoopIterations = this.config.maxToolLoopIterations ?? 5;
       main_processing_loop: while (safetyBreak < maxToolLoopIterations) {

src/orchestration/runtime/LoopController.ts

@@ -6,6 +6,13 @@
  * that supports parallel/sequential tool dispatch, configurable failure modes, and
  * iteration limits. Yields structured {@link LoopEvent}s for observability.
  *
+ * NOTE: The GMI (src/cognitive_substrate/GMI.ts) still maintains its own inline
+ * tool-calling loop in `processTurnStream()`.  The GMI loop carries RAG retrieval,
+ * prompt reconstruction, persona-scoped tool orchestration, and GMI state
+ * management that this controller does not yet abstract.  The GMI loop documents
+ * a future refactor path to delegate iteration/termination logic here.  See the
+ * comment block in GMI.processTurnStream() for details.
+ *
  * @example
  * ```typescript
  * const controller = new LoopController();