@kb-labs/agent-core 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,2415 @@
+import * as _kb_labs_agent_contracts from '@kb-labs/agent-contracts';
+import { AgentMode, AgentSessionInfo, AgentSession, AgentEvent, Turn, FileChangeSummary, AgentEventCallback, Tracer, LLMTier, TaskPlan, SessionProgress, TaskSpec, AgentConfig, TaskResult, ModeConfig, SpecSection, StopConditionResult, LoopResult, AgentMemory, FeatureFlags, SpawnAgentRequest, SpawnAgentResult, AsyncTask, ToolPack, ToolFilter, ToolDefinition, ResolvedTool, ToolResult, IterationSnapshot, RunEvaluation } from '@kb-labs/agent-contracts';
+import { ToolRegistry, SessionMemoryBridge } from '@kb-labs/agent-tools';
+import { RuntimeProfile, ResultMapper, StopCondition, RunContext, LLMCallResult, ExecutionLoop as ExecutionLoop$1, LoopContext as LoopContext$1, LoopResult as LoopResult$1, AgentMiddleware, ControlAction, LLMCtx, LLMCallPatch, ToolExecCtx, ToolOutput, IAgentRunner, AgentSDK, ToolGuard, OutputProcessor, InputNormalizer, ToolCallInput, ContextMeta } from '@kb-labs/agent-sdk';
+export { AgentMiddleware, ControlAction, LLMCallPatch, LLMCallResult, LLMCtx, RunContext, ToolExecCtx, ToolOutput } from '@kb-labs/agent-sdk';
+import { StorageConfig, ChangeStore, FileChangeSummary as FileChangeSummary$1 } from '@kb-labs/agent-history';
+import { LLMMessage, ILLM, LLMTool } from '@kb-labs/sdk';
+export { SessionArtifactStore } from '@kb-labs/agent-store';
+export { completePendingActions, createKernelState, ingestUserTurn, isCorrectionPendingAction, projectKernelPrompt, recordCorrection, recordDecision, recordToolArtifact } from '@kb-labs/agent-kernel';
+
+/**
+ * Extended session with agentId for storage
+ */
+interface StoredSession extends AgentSession {
+    agentId: string;
+    name?: string;
+}
+/**
+ * Conversation turn extracted from events
+ */
+interface ConversationTurn {
+    userTask: string;
+    agentResponse?: string;
+    timestamp: string;
+}
+interface SessionKpiBaseline {
+    version: number;
+    updatedAt: string;
+    driftRateEma: number;
+    evidenceDensityEma: number;
+    toolErrorRateEma: number;
+    samples: number;
+    tokenHistory: number[];
+    iterationUtilizationHistory: number[];
+    qualityScoreHistory: number[];
+}
+/**
+ * Manages agent sessions (creation, persistence, retrieval)
+ */
+declare class SessionManager {
+    private workingDir;
+    private readonly artifactStore;
+    /** In-memory cache of per-run sequence counters (initialized lazily from NDJSON) */
+    private runSeqCounters;
+    /** In-memory cache of turn sequence counters per session (for turns.json). */
+    private turnSeqCounters;
+    /** Turn assembler for creating turn snapshots from events */
+    private assembler;
+    /** Write queue per session to prevent concurrent write race conditions */
+    private writeQueues;
+    /**
+     * Serialized event-processing queue per session.
+     * Ensures addEvent calls for the same session are processed in arrival order
+     * even when the caller fires them concurrently with void (fire-and-forget).
+     * This prevents tool:end being processed by TurnAssembler before tool:start.
+     */
+    private eventQueues;
+    /** Write queue per session for artifact projection updates */
+    private artifactWriteQueues;
+    /** Write queue per session for KPI baseline updates */
+    private kpiWriteQueues;
+    constructor(workingDir: string);
+    /**
+     * Create a new session
+     */
+    createSession(config: {
+        mode: AgentMode;
+        task: string;
+        agentId: string;
+        name?: string;
+        planId?: string;
+        sessionId?: string;
+    }): Promise<AgentSessionInfo>;
+    /**
+     * Generate a human-readable session name from task
+     */
+    private generateSessionName;
+    /**
+     * Convert stored session to session info
+     */
+    private toSessionInfo;
+    /**
+     * Save session to disk
+     */
+    saveSession(session: StoredSession | AgentSession): Promise<void>;
+    /**
+     * Load session from disk
+     */
+    loadSession(sessionId: string): Promise<StoredSession | null>;
+    /**
+     * Get session with full info
+     */
+    getSessionInfo(sessionId: string): Promise<AgentSessionInfo | null>;
+    /**
+     * Update session status
+     */
+    updateSessionStatus(sessionId: string, status: AgentSession['status']): Promise<void>;
+    /**
+     * List all sessions with info
+     */
+    listSessions(options?: {
+        agentId?: string;
+        status?: AgentSession['status'];
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        sessions: AgentSessionInfo[];
+        total: number;
+    }>;
+    /**
+     * Get next per-run sessionSeq for a specific run within a session.
+     * Each run has independent sequence counters starting from 1.
+     * Lazily initialized: reads NDJSON on first call to find max existing sessionSeq for this runId,
+     * then uses in-memory counter for subsequent calls.
+     */
+    private getNextSessionSeq;
+    /**
+     * Add event to session (append-only, race-condition safe).
+     * Assigns per-run sessionSeq for ordering within each run.
+     * Also processes event to update turn snapshots.
+     *
+     * Events for the same session are serialized via eventQueues so that
+     * concurrent fire-and-forget callers (void addEvent(...)) don't cause
+     * tool:end to be processed before tool:start in TurnAssembler.
+     */
+    addEvent(sessionId: string, event: AgentEvent): Promise<void>;
+    private _addEventInternal;
+    /**
+     * Get all events for a session
+     */
+    getSessionEvents(sessionId: string, options?: {
+        limit?: number;
+        offset?: number;
+        types?: string[];
+    }): Promise<AgentEvent[]>;
+    /**
+     * Count events in session
+     */
+    countEvents(sessionId: string, types?: string[]): Promise<number>;
+    /**
+     * Extract conversation history from session events
+     *
+     * Parses events.ndjson to reconstruct user-agent conversation turns.
+     * Uses agent:start events (without parentAgentId = top-level requests).
+     * Uses agent:end for summaries.
+     *
+     * @param sessionId - Session ID
+     * @param maxTurns - Maximum number of turns to return (default: 10)
+     * @returns Array of conversation turns, oldest first
+     */
+    getConversationHistory(sessionId: string, maxTurns?: number): Promise<Array<{
+        userTask: string;
+        agentResponse?: string;
+        timestamp: string;
+    }>>;
+    /**
+     * Build conversation history from canonical turn snapshots (turns.json).
+     * This avoids lossy reconstruction from events summary.
+     */
+    private getConversationHistoryFromTurns;
+    private extractAssistantText;
+    /**
+     * Get conversation history with progressive summarization for long sessions
+     *
+     * Strategy:
+     * - Recent turns (last 3): Full context (up to 2000 chars each)
+     * - Mid-term turns (4-10): Summarized (up to 500 chars each)
+     * - Old turns (11+): Ultra-brief (up to 150 chars each, max 10 oldest)
+     *
+     * This keeps token usage bounded while maintaining context depth.
+     *
+     * @param sessionId - Session ID
+     * @param llm - Optional LLM instance for intelligent summarization (if not provided, uses truncation)
+     * @returns Structured history with recent/mid-term/old tiers
+     */
+    getConversationHistoryWithSummarization(sessionId: string, llm?: {
+        chat?: (messages: Array<{
+            role: string;
+            content: string;
+        }>) => Promise<string>;
+    }): Promise<{
+        recent: ConversationTurn[];
+        midTerm: ConversationTurn[];
+        old: ConversationTurn[];
+    }>;
+    /**
+     * Store turn snapshot to turns.json
+     * Serializes writes per session to prevent race-condition duplicates
+     */
+    storeTurnSnapshot(sessionId: string, turn: Turn): Promise<void>;
+    private _writeTurnSnapshot;
+    /**
+     * Attach file change summaries to the assistant turn for a given runId.
+     * Called after agent.execute() completes to surface file changes in the UI.
+     */
+    attachFileChangesToTurn(sessionId: string, runId: string, fileChanges: FileChangeSummary[]): Promise<void>;
+    private _attachFileChangesToTurn;
+    /**
+     * Update fileChanges metadata on a turn (e.g. after approve/rollback).
+     * Patches individual change entries by changeId.
+     */
+    updateTurnFileChanges(sessionId: string, runId: string, updatedChanges: _kb_labs_agent_contracts.FileChangeSummary[]): Promise<void>;
+    /**
+     * Load turn snapshots for session
+     */
+    getTurns(sessionId: string): Promise<Turn[]>;
+    /**
+     * Lazy migration: rebuild turns from events.ndjson
+     * (for old sessions without turns.json)
+     */
+    private migrateTurnsFromEvents;
+    /**
+     * Get conversation snapshot for WebSocket connections
+     * Returns last 20 completed turns + active turns
+     */
+    getConversationSnapshot(sessionId: string): Promise<{
+        completedTurns: Turn[];
+        activeTurns: Turn[];
+        totalTurns: number;
+    }>;
+    /**
+     * Create user turn with task/question
+     * Called when user submits a task to agent
+     */
+    createUserTurn(sessionId: string, task: string, runId: string): Promise<Turn>;
+    /**
+     * Reserve next turn sequence number atomically per session.
+     * Uses the same serialized write queue as turns.json updates.
+     */
+    private reserveNextTurnSequence;
+    /**
+     * Process event and update turn snapshot
+     * Returns updated turn if changed, null otherwise
+     */
+    processEventAndUpdateTurn(sessionId: string, event: AgentEvent): Promise<Turn | null>;
+    /**
+     * Store extracted trace artifacts for a completed run.
+     */
+    storeTraceArtifacts(sessionId: string, runId: string, traceEntries: Array<Record<string, unknown>>): Promise<void>;
+    /**
+     * Render compact trace-memory context for prompt injection.
+     */
+    getTraceArtifactsContext(sessionId: string): Promise<string>;
+    private loadArtifacts;
+    private updateArtifacts;
+    private extractTraceArtifacts;
+    private mergeArtifacts;
+    private uniqueTail;
+    private createEmptyArtifacts;
+    /**
+     * Get session directory path
+     */
+    getSessionDir(sessionId: string): string;
+    /**
+     * Get events file path (NDJSON format)
+     */
+    getEventsPath(sessionId: string): string;
+    /**
+     * Get session plan file path
+     */
+    getSessionPlanPath(sessionId: string): string;
+    /**
+     * Get session spec JSON file path
+     */
+    getSessionSpecPath(sessionId: string): string;
+    /**
+     * Get session spec markdown file path
+     */
+    getSessionSpecMdPath(sessionId: string): string;
+    /**
+     * Get session progress file path
+     */
+    getSessionProgressPath(sessionId: string): string;
+    /**
+     * Get turns file path (Turn snapshots JSON)
+     */
+    getTurnsPath(sessionId: string): string;
+    /**
+     * Get trace artifacts projection path
+     */
+    getArtifactsPath(sessionId: string): string;
+    /**
+     * Get KPI baseline projection path
+     */
+    getKpiBaselinePath(sessionId: string): string;
+    /**
+     * Read persisted KPI baseline for this session.
+     */
+    getKpiBaseline(sessionId: string): Promise<SessionKpiBaseline | null>;
+    /**
+     * Update persisted KPI baseline with serialized writes per session.
+     */
+    updateKpiBaseline(sessionId: string, updater: (current: SessionKpiBaseline | null) => SessionKpiBaseline): Promise<void>;
+}
+
+/**
+ * Plan generator - creates execution plans using LLM with native tool calling
+ */
+
+/**
+ * Generates execution plans from task descriptions
+ */
+declare class PlanGenerator {
+    /**
+     * Generate a task execution plan using native tool calling
+     */
+    generate(config: {
+        task: string;
+        sessionId: string;
+        mode: AgentMode;
+        complexity?: 'simple' | 'medium' | 'complex';
+        toolRegistry?: ToolRegistry;
+        researchContext?: string;
+        onEvent?: AgentEventCallback;
+        agentId?: string;
+        parentAgentId?: string;
+        tracer?: Tracer;
+        tier?: LLMTier;
+    }): Promise<TaskPlan>;
+    /**
+     * Update an existing plan based on user feedback.
+     * Uses a dedicated plan_update tool instead of free-form JSON.
+     */
+    update(config: {
+        plan: TaskPlan;
+        feedback: string;
+        mode?: AgentMode;
+        toolRegistry?: ToolRegistry;
+        enableResearch?: boolean;
+        onEvent?: AgentEventCallback;
+        agentId?: string;
+        parentAgentId?: string;
+        tracer?: Tracer;
+        tier?: LLMTier;
+    }): Promise<TaskPlan>;
+    private buildTaskPlan;
+    private runResearchPhase;
+    private collectResearchContext;
+    private collectDeterministicResearchEvidence;
+    private runDelegatedResearchPhase;
+    private selectResearchGaps;
+    private normalizeChildResearchOutput;
+    private regeneratePlanWithQualityFeedback;
+    private emitStatus;
+    private emitProgress;
+    private emitEvent;
+    private getTokensUsed;
+    private traceLLMCall;
+    private newToolCallId;
+    private assessPlanQuality;
+    private assessFreeformMarkdown;
+    private isRefactorTask;
+    private shouldRetryPlan;
+    private clamp01;
+    private createResearchTool;
+    /**
+     * Create the plan generation tool
+     */
+    private createPlanTool;
+    private createRefactorPlanTool;
+    private createPlanUpdateTool;
+    /**
+     * Get research tools from registry (read-only tools for investigation)
+     */
+    private getResearchTools;
+    /**
+     * Normalize phases from tool call
+     */
+    private normalizePhasesFromTool;
+    private parsePhasesFromMarkdown;
+    private normalizePlanMarkdown;
+    private createFallbackPhases;
+    private synthesizeRefactorPhasesFromChangeSets;
+    private normalizePhaseName;
+    private normalizePhaseDescription;
+    private normalizeStepAction;
+    private normalizeExpectedOutcome;
+    private extractHumanLabel;
+    private extractOutcomeFromAction;
+    /**
+     * Build system prompt for plan generation
+     */
+    private buildSystemPrompt;
+    private buildResearchSystemPrompt;
+    private buildUpdateSystemPrompt;
+    private buildPlanningProfile;
+    private extractPathHints;
+    private extractKeywordHints;
+    /**
+     * Get mode-specific context for plan generation
+     */
+    private getModeContext;
+    private getPlanToolName;
+}
+
+/**
+ * Plan executor - executes plans step by step with progress tracking
+ */
+
+/**
+ * Executes task plans with progress tracking
+ */
+declare class PlanExecutor {
+    private tracer?;
+    constructor(tracer?: Tracer);
+    /**
+     * Execute a plan
+     */
+    execute(plan: TaskPlan, toolExecutor: (tool: string, args: Record<string, unknown>) => Promise<string>): Promise<{
+        success: boolean;
+        completedPhases: number;
+        completedSteps: number;
+        failedSteps: number;
+        error?: string;
+    }>;
+    /**
+     * Check if phase dependencies are met
+     */
+    private areDependenciesMet;
+    /**
+     * Calculate progress
+     */
+    calculateProgress(plan: TaskPlan): SessionProgress;
+    /**
+     * Save progress to file
+     */
+    saveProgress(progress: SessionProgress, filePath: string): Promise<void>;
+    /**
+     * Record trace entry
+     */
+    private recordTrace;
+}
+
+interface PlanDocumentServiceOptions {
+    plansDir?: string;
+}
+declare class PlanDocumentService {
+    private readonly workingDir;
+    private readonly plansDir;
+    constructor(workingDir: string, options?: PlanDocumentServiceOptions);
+    getPlansDir(): string;
+    getPlanPath(plan: TaskPlan): string;
+    createDraft(plan: TaskPlan): Promise<{
+        path: string;
+        markdown: string;
+    }>;
+    renderDraft(plan: TaskPlan): string;
+    reviseDraft(planPath: string, markdown: string): Promise<string>;
+    appendExecutionLog(planPath: string, entry: string): Promise<string>;
+    refreshToc(markdown: string): string;
+    private buildDraftMarkdown;
+    private expandPhaseKeySteps;
+    private collectPhaseExpectedResults;
+    private collectVerificationCommands;
+    private compactSentence;
+    private removeExistingToc;
+    private collectHeadings;
+    private renderToc;
+    private slugify;
+    private slugifyHeading;
+}
+
+/**
+ * Plan Output Validator — deterministic rubric-based quality gate for generated plans.
+ *
+ * Checks specificity, actionability, completeness, and verification without LLM calls.
+ * Returns a composite score (0–1) and pass/fail verdict.
+ */
+type Severity = 'error' | 'warning' | 'info';
+interface ValidatorIssue {
+    dimension: 'specificity' | 'actionability' | 'completeness' | 'verification';
+    severity: Severity;
+    message: string;
+}
+interface RubricScore {
+    raw: number;
+    weighted: number;
+    details: string;
+}
+interface PlanValidationResult {
+    passed: boolean;
+    score: number;
+    rubric: {
+        specificity: RubricScore;
+        actionability: RubricScore;
+        completeness: RubricScore;
+        verification: RubricScore;
+    };
+    issues: ValidatorIssue[];
+}
+declare class PlanValidator {
+    /**
+     * Validate a markdown plan and return rubric-based scoring.
+     */
+    validate(markdown: string): PlanValidationResult;
+    private scoreSpecificity;
+    private scoreActionability;
+    private scoreCompleteness;
+    private scoreVerification;
+}
+
+/**
+ * Spec Output Validator — deterministic rubric-based quality gate for generated specs.
+ *
+ * Checks coverage (plan steps covered), precision (before/after diffs present),
+ * and file validity without LLM calls.
+ * Returns a composite score (0–1) and pass/fail verdict.
+ */
+
+type SpecSeverity = 'error' | 'warning' | 'info';
+interface SpecValidatorIssue {
+    dimension: 'coverage' | 'precision' | 'files';
+    severity: SpecSeverity;
+    message: string;
+}
+interface SpecRubricScore {
+    raw: number;
+    weighted: number;
+    details: string;
+}
+interface SpecValidationResult {
+    passed: boolean;
+    score: number;
+    metrics: {
+        planStepCount: number;
+        coveredStepRefs: number;
+        uncoveredStepCount: number;
+        phaseCoverage: number;
+        stepCoverage: number;
+        diffPairs: number;
+    };
+    rubric: {
+        coverage: SpecRubricScore;
+        precision: SpecRubricScore;
+        files: SpecRubricScore;
+    };
+    issues: SpecValidatorIssue[];
+}
+declare class SpecValidator {
+    /**
+     * Validate a spec against its source plan and return rubric-based scoring.
+     */
+    validate(spec: TaskSpec, plan: TaskPlan): SpecValidationResult;
+    /**
+     * Validate from raw markdown (when structured spec is not yet parsed).
+     */
+    validateMarkdown(markdown: string, plan: TaskPlan): SpecValidationResult;
+    private scoreCoverage;
+    private scorePrecision;
+    private scoreFiles;
+}
+
+/**
+ * Mode handler interface and base implementation
+ */
+
+/**
+ * Mode handler interface - each mode implements this
+ */
+interface ModeHandler {
+    /**
+     * Execute task in this mode
+     */
+    execute(task: string, config: AgentConfig, toolRegistry: ToolRegistry): Promise<TaskResult>;
+}
+/**
+ * Get mode handler for specified mode.
+ * Delegates to ModeRegistry — supports built-in and custom modes.
+ */
+declare function getModeHandler(modeConfig?: ModeConfig): Promise<ModeHandler>;
+
+/**
+ * Execute mode handler - standard task execution with optional revision loop.
+ *
+ * When a session has an approved plan, the plan markdown is injected into
+ * the task prompt and the plan status is tracked through its lifecycle:
+ *   approved → in_progress → completed | failed
+ *
+ * Revision loop (when enabled):
+ *   execute → quality gate → if fail → compact summary → inject feedback → re-execute
+ *   Max 2 revisions. Quality gate is heuristic (no LLM).
+ */
+
+/**
+ * Execute mode - standard agent execution
+ */
+declare class ExecuteModeHandler implements ModeHandler {
+    execute(task: string, config: AgentConfig, toolRegistry: ToolRegistry): Promise<TaskResult>;
+    /**
+     * Single execution attempt.
+     */
+    private runOnce;
+    /**
+     * Build a revision task that includes compact feedback from previous attempt.
+     */
+    private buildRevisionTask;
+    /**
+     * Load approved (or draft) plan from session storage.
+     * Falls back to plan.md (written by plan_write tool) if plan.json not available.
+     */
+    private loadApprovedPlan;
+    /**
+     * Update plan status on disk.
+     */
+    private updatePlanStatus;
+    /**
+     * Inject full plan markdown into the task prompt so the agent follows it.
+     * Also adds a todo bootstrap instruction so the agent tracks progress.
+     */
+    private buildTaskWithPlan;
+    /**
+     * Build a todo_create instruction from plan phases so the agent tracks progress.
+     * Returns null if no phases or sessionId is missing.
+     */
+    private buildTodoBootstrap;
+    /**
+     * Fallback compact formatter when markdown is not stored on the plan object.
+     */
+    private formatPhasesCompact;
+}
+
+/**
+ * Plan mode handler - lightweight "Claude Code style" planning flow.
+ *
+ * Core behavior:
+ * - Reuse regular Agent loop (research + tool use).
+ * - Restrict tool access to read-only/discovery/reporting tools.
+ * - Ask agent to output a markdown plan (free-form, human-oriented).
+ * - Persist plan as session plan.json + canonical markdown document.
+ */
+
+declare class PlanModeHandler implements ModeHandler {
+    execute(task: string, config: AgentConfig, toolRegistry: ToolRegistry): Promise<TaskResult>;
+    private loadPlan;
+    private buildPlanPrompt;
+    private createSubRunner;
+    private buildFallbackPlan;
+    private buildBudgetSnapshot;
+    private emit;
+}
+
+declare function createPlanRuntimeProfile(options?: {
+    workingDir?: string;
+    sessionManager?: SessionManager;
+    task?: string;
+    complexity?: 'simple' | 'medium' | 'complex';
+    existingPlan?: TaskPlan | null;
+}): RuntimeProfile;
+
+interface PlanOutputValidation {
+    passed: boolean;
+    summary: string;
+    result: PlanValidationResult;
+}
+declare class PlanOutputValidator {
+    private readonly validator;
+    validate(markdown: string): PlanOutputValidation;
+    private buildSummary;
+}
+
+interface PlanArtifactWriteResult {
+    planPath: string;
+    documentPath: string;
+    markdown: string;
+}
+declare class PlanArtifactWriter {
+    private readonly workingDir;
+    private readonly sessionManager;
+    private readonly documentService;
+    constructor(workingDir: string, sessionManager?: SessionManager, documentService?: PlanDocumentService);
+    write(sessionId: string, plan: TaskPlan): Promise<PlanArtifactWriteResult>;
+}
+
+interface PlanResultMapperOptions {
+    task: string;
+    complexity: 'simple' | 'medium' | 'complex';
+    existingPlan?: TaskPlan | null;
+}
+declare function createPlanResultMapper(options: PlanResultMapperOptions): ResultMapper;
+
+/**
+ * Edit mode handler - modify existing files
+ */
+
+/**
+ * Edit mode - focus on modifying existing files
+ */
+declare class EditModeHandler implements ModeHandler {
+    execute(task: string, config: AgentConfig, toolRegistry: ToolRegistry): Promise<TaskResult>;
+}
+
+/**
+ * Debug mode handler - analyze errors with trace context
+ */
+
+/**
+ * Debug mode - analyze errors and suggest fixes with trace context
+ */
+declare class DebugModeHandler implements ModeHandler {
+    execute(task: string, config: AgentConfig, toolRegistry: ToolRegistry): Promise<TaskResult>;
+}
+
+/**
+ * Spec mode handler — generates a detailed specification from an approved plan.
+ *
+ * Not a separate AgentMode. Called from REST/CLI after plan approval.
+ * Creates a child agent with read-only tools + plan markdown in the system prompt.
+ * The agent reads actual source files, verifies code at specified line numbers,
+ * and produces exact before/after diffs for each plan step.
+ *
+ * Output: TaskSpec (structured) + spec.md (human-readable markdown).
+ */
+
+declare class SpecModeHandler {
+    /**
+     * Generate a detailed specification from an approved plan.
+     *
+     * @param plan - Approved TaskPlan (must have status 'approved')
+     * @param config - Agent config (workingDir, onEvent, etc.)
+     * @param toolRegistry - Full tool registry (will be wrapped read-only)
+     * @returns TaskResult with .spec populated
+     */
+    execute(plan: TaskPlan, config: AgentConfig, toolRegistry: ToolRegistry): Promise<TaskResult>;
+    private buildSpecPrompt;
+    private runDelegatedResearchPacks;
+    private buildResearchPacks;
+    private chunkArray;
+    private collectUncoveredPlanSteps;
+    private tryRepairSpecWithCoverageGaps;
+    private resolveSpecBudgetPolicy;
+    private resolveSpecIterations;
+    private estimatePlanTokens;
+    private clampNumber;
+    private clampInt;
+    private buildFallbackPartialSpec;
+    private planToMarkdownFallback;
+    parseSpecSections(markdown: string, plan: TaskPlan): SpecSection[];
+    private parseChangeBlock;
+    private createSubRunner;
+    private emit;
+    private buildBudgetSnapshot;
+}
+
+/**
+ * ModeRegistry — dynamic mode registration without modifying core.
+ *
+ * Replaces the switch/case in getModeHandler() with a registry that can
+ * be extended with custom modes at runtime.
+ *
+ * Built-in modes are registered lazily (dynamic import) to preserve
+ * tree-shaking and the existing performance characteristics.
+ *
+ * Usage (custom mode):
+ *   modeRegistry.register('review', () => new ReviewModeHandler());
+ *   // Now agent config { mode: 'review' } uses ReviewModeHandler
+ *
+ * Usage (override built-in):
+ *   modeRegistry.register('plan', () => new CustomPlanHandler(), { override: true });
+ */
+
+/** Factory function that creates a ModeHandler instance */
+type ModeHandlerFactory = () => ModeHandler | Promise<ModeHandler>;
+interface ModeRegistration {
+    readonly mode: string;
+    readonly factory: ModeHandlerFactory;
+    readonly builtIn: boolean;
+}
+interface RegisterOptions {
+    /** Allow overriding an already-registered mode (including built-ins) */
+    override?: boolean;
+}
+declare class ModeRegistry {
+    private readonly registrations;
+    constructor();
+    /**
+     * Register a mode handler factory.
+     *
+     * @throws If mode is already registered and override is not set.
+     */
+    register(mode: string, factory: ModeHandlerFactory, options?: RegisterOptions): void;
+    /**
+     * Check whether a mode is registered.
+     */
+    has(mode: string): boolean;
+    /**
+     * List all registered mode names.
+     */
+    list(): string[];
+    /**
+     * Get a ModeHandler for the given mode.
+     * Falls back to 'execute' if mode is not found.
+     *
+     * @throws If neither the requested mode nor 'execute' fallback is registered.
+     */
+    get(mode: string): Promise<ModeHandler>;
+    private registerBuiltIns;
+}
+/**
+ * Global ModeRegistry instance.
+ *
+ * Use this to register custom modes application-wide:
+ *   import { modeRegistry } from '@kb-labs/agent-core';
+ *   modeRegistry.register('my-mode', () => new MyModeHandler());
+ */
+declare const modeRegistry: ModeRegistry;
+/**
+ * Convenience function that replaces the old getModeHandler() switch/case.
+ * Delegates to the global modeRegistry.
+ */
+declare function getModeHandlerFromRegistry(mode: string): Promise<ModeHandler>;
+
+type ExecutionPhase = 'init' | 'scoping' | 'planning_lite' | 'executing' | 'converging' | 'verifying' | 'reporting' | 'completed' | 'failed';
+type PhaseTransition = {
+    from: ExecutionPhase;
+    to: ExecutionPhase;
+    timestamp: string;
+    reason?: string;
+};
+declare class ExecutionStateMachine {
+    private current;
+    private transitions;
+    private enteredAt;
+    private durationsMs;
+    getCurrent(): ExecutionPhase;
+    getTransitions(): PhaseTransition[];
+    transition(to: ExecutionPhase, reason?: string): void;
+    getPhaseDurationsMs(now?: number): Record<ExecutionPhase, number>;
+}
+
+type StepStatus = 'pending' | 'done' | 'failed';
+type CapabilityType = 'discover_resource' | 'read_resource' | 'mutate_resource' | 'execute_command' | 'memory_access' | 'progress_tracking' | 'finalize_result' | 'integrate_external' | 'general_action';
+type LedgerStep = {
+    id: string;
+    goal: string;
+    capability: CapabilityType;
+    toolName?: string;
+    status: StepStatus;
+    startedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    error?: string;
+    evidence?: string;
+};
+declare class TaskLedger {
+    private steps;
+    private activeById;
+    private counter;
+    startStep(params: {
+        goal: string;
+        capability: CapabilityType;
+        toolName?: string;
+    }): string;
+    completeStep(stepId: string, evidence?: string): void;
+    failStep(stepId: string, error: string): void;
+    getSummary(): {
+        totalSteps: number;
+        completedSteps: number;
+        failedSteps: number;
+        pendingSteps: number;
+        avgStepDurationMs: number;
+        capabilityUsage: Record<CapabilityType, number>;
+    };
+}
+declare function mapToolToCapability(toolName: string): CapabilityType;
+
+interface AgentBehaviorPolicy {
+    retrieval: {
+        minReadWindowLines: number;
+        maxConsecutiveSmallWindowReadsPerFile: number;
+        smallFileReadAllThresholdLines: number;
+    };
+    noResult: {
+        minIterationsBeforeConclusion: number;
+        maxConsecutiveNoSignalSearchByTier: Record<LLMTier, number>;
+    };
+    evidence: {
+        minFilesReadForInformational: number;
+        minEvidenceDensityForInformational: number;
+        minInformationalResponseChars: number;
+    };
+}
+declare function createDefaultAgentBehaviorPolicy(): AgentBehaviorPolicy;
+
+interface WorkspaceRepoNode {
+    name: string;
+    path: string;
+    reasons: string[];
+    /** Package names found inside each repo */
+    packages: string[];
+    /** Top-level directory names */
+    dirs: string[];
+}
+interface WorkspaceDiscoveryResult {
+    rootDir: string;
+    repos: WorkspaceRepoNode[];
+}
+declare function discoverWorkspace(rootDir: string): Promise<WorkspaceDiscoveryResult>;
+
+/**
+ * StopConditionEvaluator — deterministic evaluation of all stop conditions.
+ *
+ * Checks ALL conditions in a single pass and returns the highest-priority match.
+ * Priority order: abort > report-complete > hard-budget > max-iterations > loop > no-tool-calls.
+ *
+ * Fixes bug: previously isLastIteration with tool calls (agent.ts:1247) triggered forced
+ * synthesis BEFORE checking for report tool (agent.ts:1462). Now REPORT_COMPLETE has
+ * priority 1 while MAX_ITERATIONS has priority 3.
+ *
+ * Custom SDK conditions are evaluated alongside built-ins. Priority >= 10 is reserved
+ * for custom conditions (built-ins use 0–5).
+ */
+
+/**
+ * Minimal interface for LLM response — only what StopConditionEvaluator needs.
+ */
+interface StopEvalResponse {
+    toolCalls?: Array<{
+        name: string;
+        input?: Record<string, unknown>;
+    }>;
+    content?: string;
+}
+/**
+ * Context needed to evaluate stop conditions.
+ */
+interface StopEvalContext {
+    /** Current iteration (0-based) */
+    iteration: number;
+    /** Maximum allowed iterations */
+    maxIterations: number;
+    /** AbortSignal from user / parent agent */
+    abortSignal?: AbortSignal;
+    /** Total tokens consumed so far */
+    totalTokens: number;
+    /** Hard token limit (0 = no limit) */
+    hardTokenLimit: number;
+    /** Whether a loop was detected this iteration */
+    loopDetected: boolean;
+}
+/**
+ * Evaluate all stop conditions and return the highest-priority match (if any).
+ *
+ * Returns null if no stop condition fires (execution should continue).
+ */
+declare function evaluateStopConditions(ctx: StopEvalContext, response: StopEvalResponse): StopConditionResult | null;
+/**
+ * StopConditionEvaluator class — stateless, injectable for testing.
+ *
+ * Pass custom `StopCondition[]` from agent-sdk (via AgentSDK.addStopCondition()) to
+ * extend evaluation with user-defined conditions. Built-in conditions use priorities 0–5;
+ * custom conditions should use priority >= 10 to avoid overriding built-ins.
+ */
+declare class StopConditionEvaluator {
+    private readonly customConditions;
+    constructor(customConditions?: StopCondition[]);
+    evaluate(ctx: StopEvalContext, response: StopEvalResponse, 
+    /** Full RunContext — passed to SDK custom conditions (optional for backward compat) */
+    runCtx?: RunContext, 
+    /** Full LLM result — passed to SDK custom conditions (optional for backward compat) */
+    llmResult?: LLMCallResult): StopConditionResult | null;
+}
+
+/**
+ * ExecutionLoop — the core iteration engine for Agent v2.
+ *
+ * Extracted from agent.ts `executeWithTier()` (lines 942–1650).
+ * Uses a callback-based LoopContext so the loop has no direct dependency
+ * on the Agent class itself (enabling independent unit testing).
+ *
+ * Key improvements over the agent.ts loop:
+ * 1. Returns LoopResult<T> — never throws TierEscalationSignal
+ * 2. Integrates StopConditionEvaluator for priority-based stop ordering
+ * 3. Supports ControlAction ('continue'|'stop'|'escalate') from guards
+ * 4. Iteration budget extension is supported via extendBudget callback
+ *
+ * Strangler fig pattern: agent.ts still owns the loop today.
+ * This class is built and tested in isolation first, then wired in.
+ */
+
+/**
+ * A single LLM response — tool calls or final content.
+ */
+interface LoopLLMResponse {
+    content: string;
+    toolCalls?: LoopToolCall[];
+    /** Token counts for this turn */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+interface LoopToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface LoopToolResult {
+    toolCallId: string;
+    output: string;
+    isError?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Per-iteration snapshot passed to most callbacks.
+ */
+interface IterationContext {
+    iteration: number;
+    maxIterations: number;
+    totalTokens: number;
+    isLastIteration: boolean;
+}
+/**
+ * Everything the loop needs — implemented by the Agent (or a test stub).
+ *
+ * Callbacks are kept minimal: only what changes behaviour.
+ * Side-effect-only hooks (tracing, metrics, events) are optional.
+ */
+interface LoopContext<TResult> {
+    /** Initial max iterations. Loop may call extendBudget() to raise this. */
+    maxIterations: number;
+    /**
+     * Called once per iteration to get the LLM response.
+     * Receives accumulated token count for budget decisions.
+     */
+    callLLM(ctx: IterationContext): Promise<LoopLLMResponse>;
+    /**
+     * Execute all tool calls for this iteration.
+     * Returns results in the same order as calls.
+     */
+    executeTools(calls: LoopToolCall[], ctx: IterationContext): Promise<LoopToolResult[]>;
+    /**
+     * Build the final TaskResult from a report call or natural stop.
+     */
+    buildResult(answer: string, ctx: IterationContext, reasonCode: string): Promise<TResult>;
+    /**
+     * True when the agent's AbortController has been signalled.
+     */
+    isAborted(): boolean;
+    /**
+     * Returns the report answer if any tool call in the list is 'report'.
+     * Returns undefined otherwise.
+     */
+    extractReportAnswer(calls: LoopToolCall[]): string | undefined;
+    /**
+     * Returns the reason string if the same tool calls have looped 3x.
+     */
+    detectLoop(calls: LoopToolCall[]): string | undefined;
+    /**
+     * Returns the escalation reason if the loop should escalate tier.
+     * Called after tool execution each iteration.
+     */
+    evaluateEscalation(ctx: IterationContext): {
+        shouldEscalate: boolean;
+        reason: string;
+    } | null;
+    /**
+     * Token hard limit: returns stop reason if limit is exceeded.
+     * Called before LLM call each iteration.
+     */
+    checkHardTokenLimit(totalTokens: number): string | undefined;
+    /**
+     * Called after tool execution. May return a higher budget than current.
+     * Return current maxIterations to keep unchanged.
+     */
+    extendBudget(ctx: IterationContext): number;
+    /** Called at the start of each iteration (for events/tracing). */
+    onIterationStart?(ctx: IterationContext): void;
+    /** Called at the end of each iteration (for events/tracing). */
+    onIterationEnd?(ctx: IterationContext, hadToolCalls: boolean): void;
+    /** Called when a stop condition fires. */
+    onStop?(condition: StopConditionResult, ctx: IterationContext): void;
+    /** Called when token count updates after LLM response. */
+    onTokensConsumed?(delta: number, total: number): void;
+}
+/**
+ * Runs the agent iteration loop and returns a LoopResult.
+ *
+ * Never throws — tier escalation is returned as `{ outcome: 'escalate' }`.
+ * All other errors are caught and returned as `{ outcome: 'complete', result: failureResult }`.
+ */
+declare class ExecutionLoop<TResult> {
+    private readonly ctx;
+    private readonly evaluator;
+    constructor(ctx: LoopContext<TResult>);
+    run(): Promise<LoopResult<TResult>>;
+}
+
+/**
+ * LinearExecutionLoop — SDK-native implementation of ExecutionLoop.
+ *
+ * Implements the agent-sdk ExecutionLoop interface:
+ *   run(ctx: LoopContext): Promise<LoopResult>
+ *
+ * LoopContext (from agent-sdk) provides only infrastructure primitives:
+ *   - run: RunContext          — shared run state
+ *   - appendMessage()         — only way to mutate message history
+ *   - callLLM()               — LLM call with middleware pipeline applied
+ *   - executeTools()          — tool execution with guards + processors applied
+ *
+ * All business logic (stop detection, report extraction, loop detection)
+ * lives here — not in LoopContext. This keeps the contract minimal.
+ *
+ * Stop priority order (lower number = higher priority):
+ *   0  ABORT        — abortSignal fired
+ *   1  REPORT       — agent called the report tool
+ *   2  HARD_BUDGET  — token hard limit (via BudgetMiddleware metadata)
+ *   3  MAX_ITER     — hit maxIterations
+ *   4  LOOP         — same 3 tool calls repeated twice
+ *   5  NO_TOOLS     — LLM returned no tool calls (natural completion)
+ *
+ * Returns LoopOutput — AgentRunner builds the full TaskResult from it.
+ */
+
+declare class LinearExecutionLoop implements ExecutionLoop$1 {
+    run(ctx: LoopContext$1): Promise<LoopResult$1>;
+}
+
+/**
+ * Builds the system prompt for the agent LLM call.
+ *
+ * Architecture inspired by Claude Code:
+ * - Static sections (core rules, workflow) — stable across sessions, cacheable
+ * - Semi-static sections (working dir, delegation) — stable within session
+ * - Dynamic sections (memory, facts, workspace) — change per iteration
+ *
+ * Tool descriptions are NOT in the system prompt — they go via API `tools:` parameter.
+ * Project instructions (AGENTS.md) loaded conditionally based on task scope.
+ */
+
+interface SystemPromptInput {
+    workingDir: string;
+    responseMode: 'auto' | 'brief' | 'deep';
+    isSubAgent: boolean;
+    sessionId?: string;
+    sessionRootDir?: string;
+    currentTask?: string;
+    memory?: AgentMemory;
+    workspaceDiscovery?: WorkspaceDiscoveryResult | null;
+    factSheetContent?: string;
+    archiveSummaryHint?: string;
+}
+declare class SystemPromptBuilder {
+    build(input: SystemPromptInput): Promise<string>;
+}
+declare function loadProjectInstructions(workingDir: string): string | null;
+
+/**
+ * Run Metrics Emitter
+ *
+ * Fires analytics events for run KPIs, tool outcomes, tier escalations,
+ * and detects quality regressions using EMA baselines.
+ */
+interface KpiBaseline {
+    driftRateEma: number;
+    evidenceDensityEma: number;
+    toolErrorRateEma: number;
+    samples: number;
+    tokenHistory: number[];
+    iterationUtilizationHistory: number[];
+    qualityScoreHistory: number[];
+}
+interface TierEscalation {
+    from: string;
+    to: string;
+    reason: string;
+    iteration: number;
+}
+interface RegressionMetrics {
+    driftRate: number;
+    evidenceDensity: number;
+    toolErrorRate: number;
+    tokensUsed: number;
+    iterationsUsed: number;
+    iterationBudget: number;
+    iterationUtilization: number;
+    qualityScore: number;
+    qualityGateStatus: string;
+}
+interface RunKpiPayload {
+    sessionId?: string;
+    agentId: string;
+    task: string;
+    success: boolean;
+    error?: string;
+    summaryPreview: string;
+    iterationsUsed: number;
+    iterationBudget: number;
+    tokenBudget?: number;
+    tokenUtilization?: number;
+    startTier: string;
+    finalTier: string;
+    durationMs: number;
+    tokensUsed: number;
+    toolCallsTotal: number;
+    toolSuccessCount: number;
+    toolErrorCount: number;
+    todoToolCalls: number;
+    filesReadCount: number;
+    filesModifiedCount: number;
+    filesCreatedCount: number;
+    driftDomainCount: number;
+    driftDomains: string[];
+    executionPhase: string;
+    phaseDurationsMs: Record<string, number>;
+    phaseTransitionCount: number;
+    phaseTransitions: unknown[];
+    ledger: {
+        failedSteps: number;
+        pendingSteps: number;
+    };
+    qualityGate: {
+        status: string;
+        score: number;
+        reasons: string[];
+    } | null;
+    /** Fraction of iterations that repeated intent without new evidence. */
+    repeatNoEvidenceRate?: number;
+}
+interface ToolOutcomeInput {
+    toolName: string;
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    retryable?: boolean;
+}
+interface KpiBaselinePersister {
+    getKpiBaseline(sessionId: string): Promise<KpiBaseline | null>;
+    updateKpiBaseline(sessionId: string, fn: () => {
+        version: number;
+        updatedAt: string;
+        driftRateEma: number;
+        evidenceDensityEma: number;
+        toolErrorRateEma: number;
+        samples: number;
+        tokenHistory: number[];
+        iterationUtilizationHistory: number[];
+        qualityScoreHistory: number[];
+    }): Promise<void>;
+}
+interface EmitContext {
+    analytics: {
+        track(event: string, payload: unknown): Promise<void>;
+    } | null;
+    sessionId?: string;
+    persister?: KpiBaselinePersister;
+    baselineKey: string;
+    log: (msg: string) => void;
+}
+/** For testing: clear the process-level baseline map */
+declare function clearProcessKpiBaselines(): void;
+declare class RunMetricsEmitter {
+    readonly tierEscalations: TierEscalation[];
+    recordTierEscalation(from: string, to: string, reason: string, iteration: number, ctx: {
+        analytics: EmitContext['analytics'];
+        sessionId?: string;
+        agentId: string;
+        task: string;
+        tierEscalatedEvent: string;
+        log: (msg: string) => void;
+    }): Promise<void>;
+    trackToolOutcome(input: ToolOutcomeInput, ctx: {
+        analytics: EmitContext['analytics'];
+        toolCalledEvent: string;
+        log: (msg: string) => void;
+    }): void;
+    emitRunKpis(payload: RunKpiPayload, ctx: EmitContext): Promise<void>;
+    private emitQualityRegressionEvent;
+    reset(): void;
+}
+declare function getKpiBaselineKey(sessionRootDir: string, workingDir: string): string;
+declare function detectQualityRegression(metrics: RegressionMetrics, baseline: KpiBaseline): {
+    regressed: boolean;
+    reasons: string[];
+};
+declare function updateKpiBaseline(baseline: KpiBaseline, metrics: RegressionMetrics, alpha?: number): KpiBaseline;
+declare function extractToolErrorCode(result: {
+    success: boolean;
+    error?: string;
+    errorDetails?: {
+        code?: string;
+        retryable?: boolean;
+    };
+    metadata?: Record<string, unknown>;
+}): string | null;
+
+/**
+ * MiddlewarePipeline — orchestrates middleware execution with error handling.
+ *
+ * Features:
+ * - Runs before-hooks ascending (lower order = first), after-hooks descending
+ * - Per-middleware failure policy: fail-open (log + skip) or fail-closed (stop)
+ * - Per-hook timeout enforcement (0 = no timeout)
+ */
+
+interface PipelineOptions {
+    featureFlags: FeatureFlags;
+    onError?: (middlewareName: string, hookName: string, error: unknown) => void;
+}
+declare class MiddlewarePipeline {
+    private readonly asc;
+    private readonly desc;
+    private readonly options;
+    constructor(middlewares: AgentMiddleware[], options: PipelineOptions);
+    private getActive;
+    private runHook;
+    onStart(ctx: RunContext): Promise<void>;
+    onStop(ctx: RunContext, reason: string): Promise<void>;
+    onComplete(ctx: RunContext): Promise<void>;
+    beforeIteration(ctx: RunContext): Promise<ControlAction>;
+    afterIteration(ctx: RunContext): Promise<void>;
+    /** Merges patches from all middlewares in order (last wins per field) */
+    beforeLLMCall(ctx: LLMCtx): Promise<LLMCallPatch>;
+    afterLLMCall(ctx: LLMCtx, result: LLMCallResult): Promise<void>;
+    /** Returns 'skip' if ANY middleware votes skip */
+    beforeToolExec(ctx: ToolExecCtx): Promise<'execute' | 'skip'>;
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): Promise<void>;
+}
+
+/**
+ * ObservabilityMiddleware — bridges AgentMiddleware hooks to AgentEvent stream.
+ *
+ * Architecture (bus pattern):
+ *   - Lifecycle hooks (beforeLLMCall, afterLLMCall, beforeToolExec, afterToolExec)
+ *     emit into ctx.run.eventBus — infrastructure-level events.
+ *   - onStart subscribes to eventBus and translates to UI AgentEvent stream
+ *     via the onEvent callback (CLI, WebSocket, NDJSON trace).
+ *   - onStart/onStop emit agent:start / agent:end directly to onEvent
+ *     (lifecycle events don't go through the bus — they are one-per-run).
+ *
+ * Design:
+ *   - order = 5 (runs before all other middlewares so events fire first)
+ *   - failPolicy = 'fail-open' (observability NEVER breaks execution)
+ *
+ * File tracking (via run.meta):
+ *   - 'files' namespace, keys: 'read', 'modified', 'created'
+ *   - Populated by afterToolExec based on tool name + input
+ *   - SDKAgentRunner reads these at the end to build TaskResult
+ */
+
+declare class ObservabilityMiddleware {
+    private readonly agentId;
+    private readonly parentAgentId;
+    private readonly sessionId;
+    private readonly onEvent;
+    readonly name = "observability";
+    readonly order = 5;
+    readonly config: {
+        failPolicy: "fail-open";
+    };
+    private _startedAt;
+    private _llmStartedAt;
+    private _toolStartedAt;
+    private _lastIteration;
+    private _totalTokens;
+    private _pendingDebug;
+    /** Extra metadata injected before onStart — set by runner after workspace discovery. */
+    startMeta?: {
+        budget?: {
+            maxTokens: number;
+            softLimitRatio: number;
+            hardLimitRatio: number;
+        };
+        workspaceTopology?: string[];
+        workingDir?: string;
+    };
+    constructor(agentId: string, parentAgentId: string | undefined, sessionId: string | undefined, onEvent: AgentEventCallback | undefined);
+    onStart(ctx: RunContext): void;
+    onStop(ctx: RunContext, reason: string): void;
+    beforeIteration(ctx: RunContext): 'continue';
+    afterIteration(ctx: RunContext): void;
+    beforeLLMCall(ctx: LLMCtx): undefined;
+    afterLLMCall(ctx: LLMCtx, result: LLMCallResult): void;
+    beforeToolExec(ctx: ToolExecCtx): 'execute';
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): void;
+    private _emit;
+}
+
+/**
+ * ChangeTrackingMiddleware — captures file change snapshots via the SDK pipeline.
+ *
+ * Design:
+ *   - order = 8 (after Observability=5, before Budget=10)
+ *   - failPolicy = 'fail-open': tracking errors never break execution
+ *   - Intercepts afterToolExec for fs_write / fs_patch / fs_delete
+ *   - Tools must include before/after content in result.metadata (see filesystem.ts)
+ *   - Persists FileChange snapshots via ChangeStore
+ *   - Writes FileChangeSummary[] to RunContext.meta('changes', 'summaries') per run
+ *   - SDKAgentRunner reads meta at end to populate TaskResult.fileChanges
+ *
+ * Data flow:
+ *   fs_write/fs_patch/fs_delete
+ *     → result.metadata.changeSnapshot: { operation, beforeContent?, afterContent, ...opMeta }
+ *     → ChangeTrackingMiddleware.afterToolExec
+ *     → ChangeStore.save()
+ *     → meta('changes', 'summaries') += FileChangeSummary
+ */
+
+interface ChangeSnapshot {
+    operation: 'write' | 'patch' | 'delete';
+    /** File content before the operation (undefined = new file) */
+    beforeContent?: string;
+    /** File content after the operation */
+    afterContent: string;
+    isOverwrite?: boolean;
+    startLine?: number;
+    endLine?: number;
+    linesAdded?: number;
+    linesRemoved?: number;
+    wasDeleted?: boolean;
+}
+interface ChangeTrackingConfig {
+    agentId: string;
+    sessionId: string | undefined;
+    workingDir: string;
+    storageConfig?: Partial<StorageConfig>;
+}
+declare class ChangeTrackingMiddleware {
+    readonly name = "change-tracking";
+    readonly order = 8;
+    readonly config: {
+        failPolicy: "fail-open";
+    };
+    private readonly store;
+    private readonly agentId;
+    private readonly sessionId;
+    /** Current run ID — set on onStart, used to tag all changes in this run */
+    private runId;
+    constructor(cfg: ChangeTrackingConfig);
+    onStart(ctx: RunContext): void;
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): Promise<void>;
+    /** Rollback all changes captured in the current run — useful for undo-run */
+    rollbackRun(sessionId: string, workingDir: string): Promise<{
+        rolledBack: number;
+        errors: string[];
+    }>;
+    /** Expose store for external queries (CLI, REST handlers) */
+    get changeStore(): ChangeStore;
+}
+declare function getFileChangeSummaries(ctx: RunContext): FileChangeSummary$1[];
+
+/**
+ * BudgetMiddleware — token budget enforcement and convergence nudging.
+ *
+ * Hook points:
+ * - beforeIteration: check hard limit → return 'stop' if exceeded
+ * - beforeLLMCall: inject convergence nudge at soft limit via LLMCallPatch
+ *
+ * Token counter is injected via a simple getter — the runner owns totalTokens
+ * and passes a closure. Everything else (policy, nudge state) lives here.
+ */
+
+interface BudgetPolicy {
+    active: boolean;
+    maxTokens: number;
+    softLimitRatio: number;
+    hardLimitRatio: number;
+    hardStop: boolean;
+    forceSynthesisOnHardLimit: boolean;
+}
+declare class BudgetMiddleware {
+    readonly name = "budget";
+    readonly order = 10;
+    readonly config: {
+        failPolicy: "fail-closed";
+        timeoutMs: number;
+    };
+    private readonly policy;
+    private readonly getTokensUsed;
+    private _convergenceNudgeSent;
+    /** Token deltas per iteration for diminishing returns detection */
+    private _iterationDeltas;
+    private _lastIterTokens;
+    private _diminishingNudgeSent;
+    constructor(policy: BudgetPolicy, getTokensUsed: () => number);
+    get convergenceNudgeSent(): boolean;
+    beforeIteration(ctx: RunContext): ControlAction;
+    beforeLLMCall(ctx: LLMCtx): LLMCallPatch | undefined;
+    reset(): void;
+}
+
+/**
+ * ProgressMiddleware — stuck detection and loop detection.
+ *
+ * Hook points:
+ * - beforeIteration: detect stuck state (too many iterations without progress)
+ * - afterToolExec: reset counter on successful tool, detect repeated call loops
+ *
+ * All state lives here. Callbacks are optional observers (for logging/telemetry).
+ * fail-open: progress tracking errors never break execution.
+ */
+
+interface ProgressCallbacks {
+    onProgress?: (iteration: number) => void;
+    onStuck?: (iteration: number, iterationsSinceProgress: number) => void;
+    onLoop?: (iteration: number, repeatedCalls: string[]) => void;
+}
+declare class ProgressMiddleware {
+    readonly name = "progress";
+    readonly order = 50;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly stuckThreshold;
+    private readonly callbacks;
+    private _iterationsSinceProgress;
+    private _recentToolCalls;
+    private _lastIterNudgeSent;
+    /** Tracks which stuck nudge level was last sent (0 = none) */
+    private _stuckNudgeLevel;
+    /** Tool calls since last plan_write (plan mode checkpoint tracking) */
+    private _toolCallsSincePlanWrite;
+    /** Whether plan checkpoint nudge was injected for current LLM call */
+    private _planCheckpointPending;
+    constructor(stuckThreshold?: number, callbacks?: ProgressCallbacks);
+    get iterationsSinceProgress(): number;
+    get isStuck(): boolean;
+    beforeIteration(ctx: RunContext): ControlAction;
+    beforeLLMCall(ctx: LLMCtx): LLMCallPatch | undefined;
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): void;
+    /**
+     * Read current plan.md from session directory.
+     * Returns null if no plan file exists or session info unavailable.
+     */
+    private _readPlanFile;
+    reset(): void;
+}
+
+/**
+ * AnalyticsMiddleware — pure observer for metrics and tool outcome tracking.
+ *
+ * Hook points:
+ * - onStart: record start time
+ * - afterLLMCall: record token usage
+ * - afterToolExec: track tool outcomes
+ * - onStop: emit run metrics
+ *
+ * fail-open: analytics should NEVER break execution.
+ */
+
+interface ToolOutcome {
+    toolName: string;
+    success: boolean;
+    durationMs?: number;
+    errorCode?: string;
+}
+interface RunMetrics {
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    totalIterations: number;
+    toolOutcomes: ToolOutcome[];
+    toolSuccessCount: number;
+    toolErrorCount: number;
+    stopReason?: string;
+}
+interface AnalyticsCallbacks {
+    onRunComplete?: (metrics: RunMetrics) => void;
+    onToolOutcome?: (outcome: ToolOutcome) => void;
+}
+declare class AnalyticsMiddleware {
+    readonly name = "analytics";
+    readonly order = 90;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly callbacks;
+    private _startedAt;
+    private _toolOutcomes;
+    private _toolSuccessCount;
+    private _toolErrorCount;
+    private _lastIteration;
+    constructor(callbacks?: AnalyticsCallbacks);
+    get toolSuccessCount(): number;
+    get toolErrorCount(): number;
+    get toolOutcomes(): ReadonlyArray<ToolOutcome>;
+    onStart(_ctx: RunContext): void;
+    afterLLMCall(ctx: LLMCtx, result: LLMCallResult): void;
+    afterToolExec(_ctx: ToolExecCtx, result: ToolOutput): void;
+    onStop(_ctx: RunContext, reason: string): void;
+    reset(): void;
+}
+
+/**
+ * ContextFilterMiddleware — sliding window + output truncation + optional compaction.
+ *
+ * Hook points:
+ * - afterToolExec: (intentionally empty — rounds extracted from ctx.messages in beforeLLMCall)
+ * - beforeLLMCall: return LLMCallPatch with filtered message window
+ *
+ * Design:
+ *   - order = 15 (after budget=10, so budget's convergence nudge is already appended)
+ *   - failPolicy = 'fail-open' (never breaks execution)
+ *   - The middleware slices the last N iterations on each LLM call.
+ *   - System messages and the initial user task are ALWAYS preserved.
+ *   - Tool outputs longer than maxOutputLength are truncated.
+ *   - When enableCompaction is true, dropped rounds are summarized by a small-tier LLM
+ *     instead of being silently removed.
+ */
+
+interface ContextFilterMwConfig {
+    /** Max characters for tool output before truncation (default: 8000) */
+    maxOutputLength?: number;
+    /** Number of most-recent assistant+tool-result "rounds" to keep (default: 10) */
+    slidingWindowSize?: number;
+    /** When true, dropped rounds are summarized by LLM instead of silently removed (default: false) */
+    enableCompaction?: boolean;
+}
+declare class ContextFilterMiddleware {
+    readonly name = "context-filter";
+    readonly order = 15;
+    readonly config: {
+        failPolicy: 'fail-open';
+        timeoutMs: number;
+    };
+    private readonly maxOutputLength;
+    private readonly slidingWindowSize;
+    private readonly enableCompaction;
+    private readonly rounds;
+    private compactionCache;
+    private llm;
+    constructor(config?: ContextFilterMwConfig);
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): void;
+    beforeLLMCall(ctx: LLMCtx): Promise<LLMCallPatch | undefined>;
+    /**
+     * Build a summary for dropped rounds.
+     * With compaction enabled: LLM summarization (cached).
+     * Without compaction: simple "[N earlier iterations removed]" note.
+     */
+    private buildDropSummary;
+    /**
+     * Call small-tier LLM to summarize dropped rounds into a compact block.
+     */
+    private summarizeRounds;
+    /**
+     * Microcompact: for rounds being kept (not dropped), clear tool result content
+     * from old rounds while keeping assistant text. This reduces context size
+     * without losing the agent's reasoning chain.
+     *
+     * Only applied to rounds older than `keepFullRounds` from the end.
+     * The most recent rounds keep full tool outputs for immediate context.
+     */
+    private microcompact;
+    private truncate;
+}
+
+/**
+ * TaskMiddleware — async task management for sub-agent operations.
+ *
+ * Manages a registry of async tasks submitted via task_submit tool.
+ * Tasks run concurrently as sub-agents and can be polled (task_status)
+ * or awaited (task_collect).
+ *
+ * Hook points:
+ *   beforeLLMCall → inject pending/completed task summary into Status Block
+ *   onStop        → cancel all pending tasks
+ *
+ * order = 25 (after FactSheet=20, before Progress=50)
+ */
+
+interface TaskMiddlewareConfig {
+    /** Max concurrent async tasks (default: 3) */
+    maxConcurrent?: number;
+}
+type SpawnFn = (request: SpawnAgentRequest) => Promise<SpawnAgentResult>;
+declare class TaskMiddleware {
+    readonly name = "task-manager";
+    readonly order = 25;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly tasks;
+    private readonly promises;
+    private readonly maxConcurrent;
+    private spawnFn;
+    constructor(config?: TaskMiddlewareConfig);
+    /** Set the spawn function (called by runner during setup) */
+    setSpawnFn(fn: SpawnFn): void;
+    /**
+     * Submit a new async task. Returns immediately with a task ID.
+     */
+    submit(description: string, request: SpawnAgentRequest): Promise<AsyncTask>;
+    /**
+     * Get status of one or all tasks.
+     */
+    getStatus(taskId?: string): AsyncTask | AsyncTask[] | null;
+    /**
+     * Await a specific task and return its result.
+     */
+    collect(taskId: string): Promise<SpawnAgentResult>;
+    /**
+     * Inject task summary into context via meta (read by FactSheetMiddleware's Status Block).
+     */
+    beforeLLMCall(ctx: LLMCtx): LLMCallPatch | undefined;
+    /**
+     * On stop: no cleanup needed — promises resolve/reject on their own.
+     */
+    onStop(): void;
+}
+
+/**
+ * SearchSignalMiddleware — search quality tracking and early conclusion.
+ *
+ * Feature-flagged: enabled when FeatureFlags.searchSignal is true.
+ */
+
+interface SearchSignalMwState {
+    searchSignalHits: number;
+    lastSignalIteration: number;
+    noResultStreak: number;
+}
+interface SearchSignalCallbacks {
+    onSignalHit?: (toolName: string, iteration: number) => void;
+    onNoResultStreak?: (streak: number, iteration: number) => void;
+}
+declare class SearchSignalMiddleware {
+    readonly name = "search-signal";
+    readonly order = 60;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly callbacks;
+    private _hits;
+    private _lastSignalIteration;
+    private _noResultStreak;
+    private _featureFlags?;
+    constructor(callbacks?: SearchSignalCallbacks);
+    enabled(): boolean;
+    withFeatureFlags(flags: FeatureFlags): this;
+    get state(): SearchSignalMwState;
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): void;
+    onStop(): void;
+    reset(): void;
+}
+
+/**
+ * TodoSyncMiddleware — todo list coordination and phase syncing.
+ *
+ * Feature-flagged: enabled when FeatureFlags.todoSync is true.
+ */
+
+interface TodoSyncCallbacks {
+    onNudge?: (iteration: number) => void;
+    onFinalize?: (success: boolean) => void;
+}
+declare class TodoSyncMiddleware {
+    readonly name = "todo-sync";
+    readonly order = 40;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly callbacks;
+    private _nudgeSent;
+    private _featureFlags?;
+    constructor(callbacks?: TodoSyncCallbacks);
+    enabled(): boolean;
+    withFeatureFlags(flags: FeatureFlags): this;
+    get nudgeSent(): boolean;
+    beforeIteration(_ctx: RunContext): ControlAction;
+    beforeLLMCall(ctx: LLMCtx): LLMCallPatch | undefined;
+    onStop(_ctx: RunContext, reason: string): void;
+    reset(): void;
+}
+
+/**
+ * ReflectionMiddleware — adaptive LLM-driven operational reflection.
+ *
+ * Feature-flagged: enabled when FeatureFlags.reflection is true.
+ */
+
+interface ReflectionCallbacks {
+    onReflectionNeeded?: (trigger: string, iteration: number) => void;
+}
+declare class ReflectionMiddleware {
+    readonly name = "reflection";
+    readonly order = 70;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly callbacks;
+    private _toolCallsSinceReflection;
+    private _failedToolsSinceReflection;
+    private readonly reflectionInterval;
+    private _featureFlags?;
+    constructor(callbacks?: ReflectionCallbacks, reflectionInterval?: number);
+    enabled(): boolean;
+    withFeatureFlags(flags: FeatureFlags): this;
+    afterToolExec(ctx: ToolExecCtx, result: ToolOutput): void;
+    onStop(): void;
+    reset(): void;
+}
+
+/**
+ * TaskClassifierMiddleware — intent inference and scope extraction.
+ *
+ * Feature-flagged: enabled when FeatureFlags.taskClassifier is true.
+ * Runs first (order=5) — classification informs other middlewares.
+ *
+ * Classification strategy:
+ * 1. LLM tool calling (preferred) — language-agnostic, semantic, uses classify_task tool
+ * 2. Heuristic regex fallback — instant, no LLM cost, English/Russian keywords
+ */
+
+type TaskIntent = 'action' | 'discovery' | 'analysis';
+interface TaskClassification {
+    intent: TaskIntent;
+    scope?: string;
+    confidence: number;
+}
+interface TaskClassifierCallbacks {
+    onClassified?: (classification: TaskClassification) => void;
+}
+declare class TaskClassifierMiddleware {
+    readonly name = "task-classifier";
+    readonly order = 5;
+    readonly config: {
+        failPolicy: "fail-open";
+        timeoutMs: number;
+    };
+    private readonly callbacks;
+    private _classification;
+    private _featureFlags?;
+    constructor(callbacks?: TaskClassifierCallbacks);
+    enabled(): boolean;
+    withFeatureFlags(flags: FeatureFlags): this;
+    get classification(): TaskClassification | null;
+    onStart(ctx: RunContext): Promise<void>;
+    private classify;
+    reset(): void;
+}
+
+/**
+ * ToolManager — single enforcement layer for tool registration and execution.
+ *
+ * Responsibilities:
+ * 1. Register ToolPacks with namespace assignment and conflict resolution
+ * 2. Resolve tool names (short or qualified) to the correct packed tool
+ * 3. Enforce permissions (allowedPaths, deniedCommands, networkAllowed)
+ * 4. Audit trail logging (when auditTrail: true)
+ * 5. Delegate execution to the packed tool
+ *
+ * Tools and packs do NOT check permissions themselves — ToolManager does.
+ */
+
+interface ToolManagerOptions {
+    /** Called before each tool execution when pack has auditTrail: true */
+    onAudit?: (toolName: string, packId: string, input: Record<string, unknown>) => void;
+    /** Called on registration errors (for logging) */
+    onError?: (message: string) => void;
+}
+declare class ToolManager {
+    private readonly packs;
+    private readonly resolvedTools;
+    private readonly options;
+    constructor(options?: ToolManagerOptions);
+    /**
+     * Register a ToolPack. Handles namespace assignment and conflict resolution.
+     * @throws If conflictPolicy is 'error' and a name collision occurs
+     */
+    register(pack: ToolPack): void;
+    private resolveConflict;
+    private findPackedTool;
+    private createResolved;
+    /**
+     * Get all tool definitions matching the filter. Used to build the LLM tool list.
+     */
+    getDefinitions(filter?: ToolFilter): ToolDefinition[];
+    /**
+     * Get resolved tools matching the filter.
+     */
+    getTools(filter?: ToolFilter): ResolvedTool[];
+    /**
+     * Get a single tool by name (short or qualified).
+     */
+    getTool(name: string): ResolvedTool | undefined;
+    /**
+     * Get sorted list of tool names.
+     */
+    getToolNames(): string[];
+    /**
+     * Check if a tool exists.
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Get all registered pack IDs.
+     */
+    getPackIds(): string[];
+    /**
+     * Execute a tool by name. This is the SINGLE enforcement layer:
+     * 1. Resolve name → find tool
+     * 2. Permission check (allowedPaths, deniedCommands, networkAllowed)
+     * 3. Audit trail (if enabled)
+     * 4. Delegate to pack executor
+     */
+    execute(name: string, input: Record<string, unknown>): Promise<ToolResult>;
+    private checkPermissions;
+    /**
+     * Remove all resolved tools whose short name is NOT in the allowlist.
+     * Used by sub-agents with preset-based tool restrictions.
+     */
+    applyAllowlist(allowedTools: string[]): void;
+    /**
+     * Initialize all registered packs.
+     */
+    initializeAll(): Promise<void>;
+    /**
+     * Dispose all registered packs.
+     */
+    disposeAll(): Promise<void>;
+}
+
+/**
+ * CoreToolPack — wraps the existing tool registry into a ToolPack.
+ *
+ * This provides backward compatibility: the current 22+ tools continue to
+ * work through the new ToolManager, while new packs (kb-labs, MCP) can
+ * be added alongside.
+ *
+ * The pack does NOT re-implement tools — it wraps the existing ToolRegistry.
+ */
+
+/**
+ * Minimal interface matching ToolRegistry from agent-tools.
+ * Avoids direct import to keep agent-core independent.
+ */
+interface LegacyToolRegistry {
+    getDefinitions(): Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+        };
+    }>;
+    execute(name: string, input: Record<string, unknown>): Promise<ToolResult>;
+    getToolNames(): string[];
+}
+/**
+ * Create a CoreToolPack from an existing ToolRegistry.
+ */
+declare function createCoreToolPack(registry: LegacyToolRegistry): ToolPack;
+
+/**
+ * KB Labs ToolPack — stub for future kb-labs-specific tools.
+ *
+ * Will include:
+ * - mind-rag integration (semantic code search)
+ * - workflow management tools
+ * - plugin system integration
+ *
+ * Currently disabled by default — enabled via configuration.
+ */
+
+/**
+ * Create the KB Labs ToolPack (stub — no tools yet).
+ */
+declare function createKBLabsToolPack(): ToolPack;
+
+/**
+ * AsyncTaskToolPack — ToolPack wrapping task_submit / task_status / task_collect.
+ *
+ * Created by runner in executeWithTier and registered alongside CoreToolPack.
+ * The pack holds a reference to the TaskMiddleware which owns the task registry.
+ */
+
+declare function createAsyncTaskToolPack(taskMw: TaskMiddleware): ToolPack;
+
+/**
+ * AgentRegistry — typed catalogue of agent presets.
+ *
+ * Each preset specifies:
+ * - toolPacks: which ToolPacks the agent gets (namespaces, not concrete classes)
+ * - featureFlags overrides (vs DEFAULT_FEATURE_FLAGS)
+ * - systemPrompt suffix (appended after the base prompt)
+ * - maxIterations default
+ * - readOnly: prevents write tools being registered
+ *
+ * Presets ship with the platform; consumers can add custom types via register().
+ *
+ * Design: registry is purely a data store (no Agent instantiation here).
+ * The Orchestrator reads registry to configure child agents.
+ */
+
+/**
+ * Which tool packs an agent is allowed to load.
+ * 'core'    — read-only file system, search, memory tools
+ * 'coder'   — full FS (write, patch), shell execution
+ * 'kb-labs' — kb-labs specific tools (mind-rag, workflow, etc.)
+ */
+type ToolPackRef = 'core' | 'coder' | 'kb-labs' | string;
+/**
+ * A registered agent type definition.
+ */
+interface AgentTypeDefinition {
+    /** Unique identifier, used when spawning: `registry.get('researcher')` */
+    readonly id: string;
+    /** Human-readable label */
+    readonly label: string;
+    /** Brief description shown in UIs and prompts */
+    readonly description: string;
+    /** Tool packs this agent is allowed to use */
+    readonly toolPacks: ToolPackRef[];
+    /** Feature flag overrides (merged on top of DEFAULT_FEATURE_FLAGS) */
+    readonly featureFlags?: Partial<FeatureFlags>;
+    /** Suffix appended to the base system prompt */
+    readonly systemPromptSuffix?: string;
+    /** Default max iterations (can be overridden at spawn time) */
+    readonly maxIterations: number;
+    /** If true, write/patch/exec tools are stripped from registered packs */
+    readonly readOnly: boolean;
+    /** Max spawn depth: 0 = cannot spawn children */
+    readonly maxDepth: number;
+}
+declare class AgentRegistry {
+    private readonly definitions;
+    constructor();
+    /**
+     * Register a custom agent type or override a preset.
+     * Throws if id is empty.
+     */
+    register(definition: AgentTypeDefinition): void;
+    /**
+     * Get an agent type definition by id.
+     * Returns undefined if not found (callers should handle missing types).
+     */
+    get(id: string): AgentTypeDefinition | undefined;
+    /**
+     * Get an agent type definition, throwing if not found.
+     */
+    getOrThrow(id: string): AgentTypeDefinition;
+    /**
+     * List all registered agent type ids.
+     */
+    listIds(): string[];
+    /**
+     * List all registered agent type definitions.
+     */
+    list(): AgentTypeDefinition[];
+    /**
+     * Merge feature flags: DEFAULT + preset overrides.
+     */
+    resolveFeatureFlags(id: string): FeatureFlags;
+    /**
+     * Check whether a definition exists.
+     */
+    has(id: string): boolean;
+}
+/**
+ * Singleton registry for the process (can be replaced in tests).
+ */
+declare const globalAgentRegistry: AgentRegistry;
+
+/**
+ * ParallelExecutor — resource-governed parallel sub-agent execution.
+ *
+ * Features:
+ * - Concurrency cap: at most `maxConcurrent` agents run simultaneously
+ * - Cancel tree: parent AbortController propagates to all children
+ * - Budget partition: parent token budget split across children (equal | weighted)
+ * - Dedupe key: identical tasks share one execution
+ * - Backpressure: queue size cap, reject or wait when queue is full
+ * - Join timeout: collect results up to `joinTimeoutMs`, return partial on timeout
+ * - MaxDepth: prevents runaway recursion
+ *
+ * The executor is generic: it calls a `runner` function you provide,
+ * so it has no direct dependency on the Agent class (testable in isolation).
+ */
+interface SubAgentRequest {
+    /** Unique task description */
+    task: string;
+    /** Agent type from registry (default: 'researcher') */
+    agentType?: string;
+    /** Override max iterations for this specific spawn */
+    maxIterations?: number;
+    /** Working directory (relative to project root) */
+    workingDir?: string;
+    /**
+     * Dedup key — if another pending/running task has the same key,
+     * this request joins that result instead of spawning a new agent.
+     * Default: task string itself.
+     */
+    dedupeKey?: string;
+    /** Weight for budget partition (1 = equal share). Default: 1 */
+    weight?: number;
+}
+interface SubAgentResult {
+    task: string;
+    agentType: string;
+    success: boolean;
+    result: string;
+    iterations: number;
+    tokensUsed: number;
+    /** True if this result came from a deduped execution */
+    deduped?: boolean;
+    /** Error message if success=false */
+    error?: string;
+    /** Whether the result was collected before timeout */
+    timedOut?: boolean;
+}
+type TokenPartitionStrategy = 'equal' | 'weighted';
+interface ParallelExecutorConfig {
+    /** Maximum simultaneously running agents. Default: 5 */
+    maxConcurrent: number;
+    /** Maximum queue size (pending, not running). Reject beyond this. Default: 20 */
+    maxQueueSize: number;
+    /** Maximum nesting depth. 0 = cannot spawn. Default: 3 */
+    maxDepth: number;
+    /** Maximum time to wait for all agents to complete (ms). Default: 120_000 */
+    joinTimeoutMs: number;
+    /** How to split token budget across children. Default: 'equal' */
+    tokenPartition: TokenPartitionStrategy;
+    /** Total token budget available to share (0 = unlimited). Default: 0 */
+    parentTokenBudget: number;
+}
+/**
+ * Function signature for actually running a sub-agent.
+ * Injected by the caller (Agent or test stub).
+ */
+type AgentRunner = (request: SubAgentRequest, tokenBudget: number, signal: AbortSignal) => Promise<SubAgentResult>;
+declare class ParallelExecutor {
+    private readonly config;
+    private readonly runner;
+    private readonly parentSignal;
+    /** Currently running slot count */
+    private running;
+    /** Pending tasks waiting for a slot */
+    private readonly queue;
+    /** Dedup map: key → shared promise */
+    private readonly dedupeMap;
+    constructor(runner: AgentRunner, parentSignal: AbortSignal, config?: Partial<ParallelExecutorConfig>);
+    /**
+     * Submit a batch of requests and collect results.
+     * Returns when all finish or joinTimeoutMs elapses (whichever comes first).
+     * Timed-out tasks have `timedOut: true` in their result.
+     */
+    executeAll(requests: SubAgentRequest[], depth?: number): Promise<SubAgentResult[]>;
+    /**
+     * Submit a single request.
+     * Handles dedup, backpressure, and concurrency limit.
+     */
+    submit(req: SubAgentRequest, tokenBudget: number, depth?: number): Promise<SubAgentResult>;
+    private enqueue;
+    private drainQueue;
+    private runOne;
+    private partitionBudget;
+    private joinWithTimeout;
+    /** Return current running/queue stats for monitoring. */
+    stats(): {
+        running: number;
+        queued: number;
+        deduped: number;
+    };
+}
+
+type DelegationStrategy = 'auto' | 'sequential' | 'parallel';
+interface OrchestratorConfig {
+    /** Strategy for delegating subtasks. Default: 'sequential' */
+    strategy: DelegationStrategy;
+    /** ParallelExecutor config (used for 'parallel' and 'auto' strategies) */
+    executor: Partial<ParallelExecutorConfig>;
+    /** Agent registry (default: globalAgentRegistry) */
+    registry?: AgentRegistry;
+    /** Current depth (incremented for each level of nesting) */
+    depth: number;
+}
+/**
+ * A single spawn request from the tool layer.
+ * Used by TaskMiddleware's spawnFn to create sub-agents.
+ */
+interface LegacySpawnRequest {
+    task: string;
+    maxIterations?: number;
+    workingDir?: string;
+}
+/**
+ * Result returned to the tool layer.
+ */
+interface LegacySpawnResult {
+    success: boolean;
+    result: string;
+    iterations: number;
+    tokensUsed: number;
+}
+declare class SubAgentOrchestrator {
+    private readonly config;
+    private readonly registry;
+    private readonly executor;
+    constructor(runner: AgentRunner, parentSignal: AbortSignal, config?: Partial<OrchestratorConfig>);
+    /**
+     * Spawn a single sub-agent.
+     */
+    spawnOne(req: LegacySpawnRequest): Promise<LegacySpawnResult>;
+    /**
+     * Spawn multiple sub-agents using the configured strategy.
+     */
+    spawnMany(requests: SubAgentRequest[], strategy?: DelegationStrategy): Promise<SubAgentResult[]>;
+    /**
+     * Resolve an agent type definition from the registry.
+     * Returns undefined if agentType is not registered.
+     */
+    resolveAgentType(agentType: string): AgentTypeDefinition | undefined;
+    /**
+     * Return executor stats for monitoring.
+     */
+    stats(): {
+        running: number;
+        queued: number;
+        deduped: number;
+    };
+    private toLegacyResult;
+}
+
+/**
+ * bootstrapAgentSDK — registers SDKAgentRunner as the RunnerFactory.
+ *
+ * Call this exactly once at application startup, before any sdk.createRunner() call.
+ * Typically called at the top of the CLI entry point (agent:run command).
+ *
+ * @example
+ *   import { bootstrapAgentSDK } from '@kb-labs/agent-core';
+ *   bootstrapAgentSDK();
+ *   const runner = new AgentSDK().register(pack).createRunner(config);
+ */
+declare function bootstrapAgentSDK(): void;
+
+/**
+ * SDKAgentRunner — clean agent implementation via AgentSDK.
+ *
+ * Composition:
+ *   AgentSDK state  →  SDKAgentRunner  →  ObservabilityMiddleware (events + file tracking)
+ *                                      →  BudgetMiddleware (token budget enforcement)
+ *                                      →  ContextFilterMiddleware (sliding window + truncation)
+ *                                      →  FactSheetMiddleware (structured working memory)
+ *                                      →  ProgressMiddleware (stuck/loop detection)
+ *                                      →  TodoSyncMiddleware (feature-flagged)
+ *                                      →  SearchSignalMiddleware (feature-flagged)
+ *                                      →  ReflectionMiddleware (feature-flagged)
+ *                                      →  TaskClassifierMiddleware (feature-flagged)
+ *                                      →  MiddlewarePipeline
+ *                                      →  ToolManager (ToolPacks)
+ *                                      →  ToolExecutor  (guards + processors)
+ *                                      →  LoopContextImpl
+ *                                      →  ExecutionLoop (LinearExecutionLoop)
+ *                                      →  SubAgentOrchestrator (child agents)
+ *
+ * Tier escalation:
+ *   - Runner iterates small → medium → large
+ *   - If LoopResult.outcome === 'escalate', move to next tier
+ *   - If LoopResult.outcome === 'complete', build TaskResult and return
+ *
+ * Mode routing:
+ *   - mode === 'execute' → run the loop directly
+ *   - any other mode    → delegate to getModeHandler() (plan/edit/debug)
+ *     getModeHandler still needs a ToolRegistry for legacy mode handlers.
+ *     We bridge via a thin ToolRegistry adapter wrapping ToolManager.
+ *
+ * Observability (from AgentConfig):
+ *   - onEvent   → forwarded via ObservabilityMiddleware (agent:start/end, llm:*, tool:*, etc.)
+ *   - memory    → context injected into system prompt via SystemPromptBuilder
+ *   - conversationHistory → injected into messages before first user turn
+ *   - filesRead/Modified/Created → tracked by ObservabilityMiddleware in run.meta
+ *   - workingDir → WorkspaceDiscovery enriches system prompt with repo map
+ */
+
+declare class SDKAgentRunner implements IAgentRunner {
+    private readonly config;
+    private readonly sdk;
+    readonly agentId: string;
+    private readonly abortController;
+    private readonly injectedMessages;
+    private readonly runMetricsEmitter;
+    /** Accumulated token count for the current execution. Promoted to class field for budget cap access by spawnChildAgent. */
+    private totalTokens;
+    constructor(config: AgentConfig, sdk: AgentSDK);
+    execute(task: string): Promise<TaskResult>;
+    requestStop(): void;
+    injectUserContext(message: string): void;
+    private runExecuteMode;
+    private executeWithTier;
+    private extractTurnText;
+    private loadConversationMessages;
+    private buildLLMTools;
+    /**
+     * Spawn a child agent with budget cap, tool filtering, and structured results.
+     *
+     * Budget cap: childBudget = parentRemainingBudget × request.budgetFraction.
+     * If parent has no budget (maxTokens=0), child also runs without budget.
+     *
+     * Tool filtering: request.allowedTools → childConfig.allowedTools → child's
+     * ToolContext.allowedTools, which gates tool registration in createToolRegistry().
+     */
+    private spawnChildAgent;
+    private runWithModeHandler;
+    private withMetrics;
+    private makeEmitContext;
+    private recordTierEscalation;
+    private emitRunKpis;
+    private getAnalytics;
+    private failResult;
+    private getSessionFactsHint;
+    private shouldInjectSessionFacts;
+    private deriveDriftDomains;
+    private evaluateQualityGate;
+}
+
+/**
+ * ToolExecutor — normalizers + guards + output processors pipeline around ToolManager.
+ *
+ * Execution order per tool call:
+ *   1. Build ToolExecCtx
+ *   2. normalize()       — each InputNormalizer in order; transforms input
+ *   3. validateInput()   — each guard in order; 'reject' → error output, stop chain
+ *   4. toolManager.execute(name, input)
+ *   5. validateOutput()  — each guard in order; 'sanitize' → replace output
+ *   6. process()         — each output processor in order
+ *   7. Return ToolOutput
+ */
+
+declare class ToolExecutor {
+    private readonly toolManager;
+    private readonly guards;
+    private readonly processors;
+    private readonly normalizers;
+    constructor(toolManager: ToolManager, guards: ReadonlyArray<ToolGuard>, processors: ReadonlyArray<OutputProcessor>, normalizers?: ReadonlyArray<InputNormalizer>);
+    getToolManager(): ToolManager;
+    execute(calls: ToolCallInput[], run: RunContext): Promise<ToolOutput[]>;
+    private executeSingle;
+}
+
+/**
+ * LoopContextImpl — implements LoopContext from @kb-labs/agent-sdk.
+ *
+ * Provides the infrastructure primitives that LinearExecutionLoop calls:
+ *   - appendMessage()   — the only way to mutate message history
+ *   - callLLM()         — LLM call with beforeLLMCall/afterLLMCall middleware
+ *   - executeTools()    — tool execution with beforeToolExec/afterToolExec middleware
+ *
+ * All business logic lives in the ExecutionLoop (LinearExecutionLoop).
+ * LoopContextImpl is intentionally stateless between calls.
+ */
+
+declare class LoopContextImpl implements LoopContext$1 {
+    private readonly messages;
+    private readonly llm;
+    private readonly pipeline;
+    private readonly executor;
+    private readonly onTokensConsumed;
+    private readonly runEvaluator;
+    readonly run: RunContext;
+    constructor(run: RunContext, messages: LLMMessage[], // mutable backing array
+    llm: ILLM, pipeline: MiddlewarePipeline, executor: ToolExecutor, onTokensConsumed: (delta: number) => void, runEvaluator: (run: RunContext, snapshot: IterationSnapshot) => Promise<RunEvaluation | null>);
+    appendMessage(message: LLMMessage): void;
+    beforeIteration(): Promise<ControlAction>;
+    afterIteration(): Promise<void>;
+    callLLM(): Promise<LLMCallResult>;
+    executeTools(calls: ToolCallInput[]): Promise<ToolOutput[]>;
+    /** Execute a single tool call with middleware hooks. */
+    private _executeSingleTool;
+    private static readonly OUTPUT_PERSIST_THRESHOLD;
+    private static readonly OUTPUT_PREVIEW_LENGTH;
+    /**
+     * Tools whose output is NEVER persisted to disk — agent needs full content.
+     * Inspired by Claude Code: Read tool has maxResultSizeChars=Infinity.
+     * Size control for these tools happens at tool level (trimOutput, maxOutputChars),
+     * not at loop level.
+     */
+    private static readonly PERSIST_EXEMPT_TOOLS;
+    /**
+     * If output exceeds threshold, persist to disk and return preview + path.
+     * Otherwise return output as-is.
+     */
+    private _maybePersistOutput;
+    evaluateRun(snapshot: IterationSnapshot): Promise<RunEvaluation | null>;
+}
+
+/**
+ * RunContext factory + ContextMeta implementation.
+ *
+ * RunContext is the top-level context shared across an entire agent run.
+ * It is created once per tier attempt by SDKAgentRunner.
+ *
+ * Key invariant: messages is a readonly view of a mutable backing array.
+ * The only legal mutation path is LoopContextImpl.appendMessage().
+ */
+
+declare class ContextMetaImpl implements ContextMeta {
+    private readonly store;
+    get<T>(namespace: string, key: string): T | undefined;
+    set<T>(namespace: string, key: string, value: T): void;
+    getNamespace(namespace: string): Record<string, unknown>;
+}
+interface CreateRunContextOptions {
+    config: AgentConfig;
+    tier: LLMTier;
+    tools: LLMTool[];
+    abortController: AbortController;
+    requestId?: string;
+}
+/**
+ * Creates a fresh RunContext for one tier attempt.
+ * Returns the context AND the mutable backing array for LoopContextImpl.
+ */
+declare function createRunContext(options: CreateRunContextOptions): {
+    run: RunContext;
+    messages: LLMMessage[];
+};
+
+declare function createSessionMemoryBridge(workingDir: string, sessionId?: string): SessionMemoryBridge | undefined;
+
+export { type AgentBehaviorPolicy, AgentRegistry, type AgentRunner, type AgentTypeDefinition, type AnalyticsCallbacks, AnalyticsMiddleware, BudgetMiddleware, type BudgetPolicy, type CapabilityType, type ChangeSnapshot, type ChangeTrackingConfig, ChangeTrackingMiddleware, ContextFilterMiddleware, type ContextFilterMwConfig, ContextMetaImpl, DebugModeHandler, type DelegationStrategy, EditModeHandler, type EmitContext, ExecuteModeHandler, ExecutionLoop, type ExecutionPhase, ExecutionStateMachine, type IterationContext, type KpiBaseline, type KpiBaselinePersister, type LedgerStep, type LegacySpawnRequest, type LegacySpawnResult, type LegacyToolRegistry, LinearExecutionLoop, type LoopContext, LoopContextImpl, type LoopLLMResponse, type LoopToolCall, type LoopToolResult, MiddlewarePipeline, type ModeHandler, type ModeHandlerFactory, type ModeRegistration, ModeRegistry, ObservabilityMiddleware, type OrchestratorConfig, ParallelExecutor, type ParallelExecutorConfig, type PipelineOptions, PlanArtifactWriter, PlanDocumentService, PlanExecutor, PlanGenerator, PlanModeHandler, PlanOutputValidator, type PlanValidationResult, PlanValidator, type ProgressCallbacks, ProgressMiddleware, type ReflectionCallbacks, ReflectionMiddleware, type RegisterOptions, type RegressionMetrics, type RubricScore, type RunKpiPayload, type RunMetrics, RunMetricsEmitter, SDKAgentRunner, type SearchSignalCallbacks, SearchSignalMiddleware, type SearchSignalMwState, SessionManager, type SpawnFn, SpecModeHandler, type SpecRubricScore, type SpecValidationResult, SpecValidator, type SpecValidatorIssue, type StepStatus, StopConditionEvaluator, type StopEvalContext, type StopEvalResponse, SubAgentOrchestrator, type SubAgentRequest, type SubAgentResult, SystemPromptBuilder, type SystemPromptInput, type TaskClassification, type TaskClassifierCallbacks, TaskClassifierMiddleware, type TaskIntent, TaskLedger, TaskMiddleware, type TaskMiddlewareConfig, type TierEscalation, type TodoSyncCallbacks, TodoSyncMiddleware, type TokenPartitionStrategy, ToolExecutor, ToolManager, type ToolManagerOptions, type ToolOutcome, type ToolOutcomeInput, type ToolPackRef, type ValidatorIssue, type WorkspaceDiscoveryResult, type WorkspaceRepoNode, bootstrapAgentSDK, clearProcessKpiBaselines, createAsyncTaskToolPack, createCoreToolPack, createDefaultAgentBehaviorPolicy, createKBLabsToolPack, createPlanResultMapper, createPlanRuntimeProfile, createRunContext, createSessionMemoryBridge, detectQualityRegression, discoverWorkspace, evaluateStopConditions, extractToolErrorCode, getFileChangeSummaries, getKpiBaselineKey, getModeHandler, getModeHandlerFromRegistry, globalAgentRegistry, loadProjectInstructions, mapToolToCapability, modeRegistry, updateKpiBaseline };