Class AgentLoop

src/agent/loop.ts:96–2671

   */
  maxIterationsOverride?: number;
  /** Per-session reasoning effort (set via /effort). undefined = model default. */
  reasoningEffort?: 'low' | 'medium' | 'high';
}

/**
 * Synthesize tool-result messages for tool_calls that were NEVER executed — e.g. a
 * loop detector (read-loop / stuck-loop / error-loop) fired and skipped the batch with
 * `continue`. The assistant message carrying those tool_calls was already appended to
 * history, so without a matching tool result for each id the conversation is malformed:
 * OpenAI-format providers (kimi, DeepSeek, LM Studio, …) reject the next request with
 * "an assistant message with 'tool_calls' must be followed by tool messages responding
 * to each 'tool_call_id'". (Anthropic tolerates it, which is why it hid until an
 * OpenAI-compatible model was used.) Emitting a short skip-marker per id keeps the
 * assistant→tool invariant intact so the run can continue.
 */
function skippedToolResults(toolCalls: ToolCall[], reason: string): Message[] {
  return toolCalls.map(tc => ({
    role: 'tool' as const,
    tool_call_id: tc.id,
    name: tc.function.name,
    content: `[skipped] ${reason} — this tool call was not executed; do not wait on its result.`,
  }));
}

export class AgentLoop {
  private router: ModelRouter;
  private registry: ToolRegistry;
  private permissions: PermissionEngine;
  private config: QodexConfig;
  private cwd: string;
  /** Working root for tool path-resolution when the user attaches a directory. Sticky across
   *  turns in a session until a new directory is attached. Falls back to `cwd` when unset. */
  private effectiveCwd?: string;
  /** Auto-snapshot service (only set when safety.autoSnapshot is enabled). */
  private snapshotService: SnapshotService | undefined;
  /** Active git sandbox for the current run (set by runSandboxed), exposed to tools. */
  private activeSandbox: GitSandbox | null = null;
  /** Tracks current turn — used for snapshot retention. */
  private currentTurn = 0;
  /**
   * Mid-task steering queue. The UI pushes `/btw …` notes here while a run is in
   * flight; the run loop drains them at the top of each iteration and injects them
   * into the conversation so the model can adjust course without being stopped.
   * Single-threaded JS event loop ⇒ no lock needed.
   */
  private steerQueue: string[] = [];
  /** Session ledger of files the model has demonstrably read (read-before-write gate). */
  private readLedger = new ReadLedger();
  /** Skills already auto-injected this session — never inject the same one twice. */
  private autoInjectedSkills = new Set<string>();
  /** Monotonic union of tool names shipped this session. The relevance gate only ever
   *  ADDS to this — never drops — so the tools block stays a byte-stable cache prefix
   *  across turns (a sliding per-turn set would flip and invalidate the prompt cache). */
  private sessionToolNames = new Set<string>();
  /** Where the active model is actually served from ('ollama'/'lmstudio'/'anthropic'/…) and
   *  its LIVE context window — set each iteration, forwarded on budget_update for the UI. */
  private lastModelSource = '';
  private lastEffectiveCtxWindow = 0;