@caupulican/pi-adaptative 0.81.39 → 0.81.41

package/dist/core/agent-session.d.ts

@@ -1,9 +1,9 @@
-import type { Agent, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, StreamIdleOptions, ThinkingLevel } from "@caupulican/pi-agent-core";
+import type { Agent, AgentMessage, AgentState, StreamIdleOptions, ThinkingLevel } from "@caupulican/pi-agent-core";
 import { type CustomMessage } from "@caupulican/pi-agent-core";
-import { type BranchSummaryEntry, type CompactionResult, type SessionManager } from "@caupulican/pi-agent-core/node";
-import type { CacheRetention, ImageContent, Message, Model, StopReason, TextContent, TextToolProtocolVariant, Usage } from "@caupulican/pi-ai";
-import type { CapabilityEnvelope, EvidenceBundle, LearningDecision, WorkerRequest, WorkerResult } from "./autonomy/contracts.ts";
-import type { LaneRecord, LaneTerminalStatus } from "./autonomy/lane-tracker.ts";
+import type { BranchSummaryEntry, CompactionResult, SessionManager } from "@caupulican/pi-agent-core/node";
+import type { Api, ImageContent, Model, TextContent, Usage } from "@caupulican/pi-ai";
+import type { CapabilityEnvelope, EvidenceBundle, LearningDecision, WorkerClaim, WorkerRequest } from "./autonomy/contracts.ts";
+import type { LaneRecord } from "./autonomy/lane-tracker.ts";
 import type { AutonomyDiagnosticSnapshot, AutonomyStatusSnapshot, GateOutcomeHistoryEntry } from "./autonomy/status.ts";
 import type { BashResult } from "./bash-executor.ts";
 import type { CurationTelemetrySnapshot } from "./context/brain-curator.ts";
@@ -18,30 +18,27 @@ import type { ContextGcReport } from "./context-gc.ts";
 import type { SessionCostSummary } from "./cost/cost-summary.ts";
 import type { DailyUsageTotals } from "./cost/daily-usage.ts";
 import { type CostGuardDecision } from "./cost-guard.ts";
-import type { WorkerRunOutcome } from "./delegation/worker-runner.ts";
-import type { ContextUsage, ExtensionCommandContextActions, ExtensionContext, ExtensionErrorListener, ExtensionRunner, ExtensionUIContext, InputSource, ReplacedSessionContext, SessionStartEvent, ShutdownHandler, ToolDefinition, ToolInfo } from "./extensions/index.ts";
+import type { WorkerDelegationRequest } from "./delegation/worker-delegation-request.ts";
+import type { ContextUsage, ExtensionRunner, ReplacedSessionContext, ToolDefinition, ToolInfo } from "./extensions/index.ts";
 import { type ChannelProvider, GatewayRegistry, type JobSchedulerProvider } from "./gateways/channel-provider.ts";
-import type { GoalContinuationPrompt, GoalContinuationPromptLimits } from "./goals/goal-continuation-prompt.ts";
-import { type GoalRuntimeSnapshot, type GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
-import { type GoalState } from "./goals/goal-state.ts";
+import type { GoalStateRevision } from "./goals/goal-lifecycle.ts";
+import type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
+import type { GoalState } from "./goals/goal-state.ts";
 import type { LearningAuditRecord } from "./learning/learning-audit.ts";
 import type { DemandSignals, ReflectionResult } from "./learning/reflection-engine.ts";
 import { type CurationProposals } from "./learning/skill-curator.ts";
 import type { MemoryProvider } from "./memory/memory-provider.ts";
 import { type LaneWorkerRefusal, type ModelCapabilityProfile } from "./model-capability.ts";
 import type { ModelRegistry } from "./model-registry.ts";
-import { type NativeToolProbeGrade } from "./models/adaptation-store.ts";
 import type { StoredFitnessReport } from "./models/fitness-store.ts";
 import type { PrismLlamaCppRuntime } from "./models/llamacpp-runtime.ts";
-import type { LocalRuntimeDeps, OllamaRuntime, TransformersRuntime } from "./models/local-runtime.ts";
+import type { OllamaRuntime, TransformersRuntime } from "./models/local-runtime.ts";
 import { type PromptTemplate } from "./prompt-templates.ts";
 import type { ModelFitnessReport } from "./research/model-fitness.ts";
-import type { ResearchRunResult } from "./research/research-runner.ts";
-import { collectWorkspaceSources } from "./research/workspace-collector.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
-import { type ToolArgumentValidationStats } from "./session-analytics.ts";
-import type { ResourceProfileFilterSettings, SettingsManager } from "./settings-manager.ts";
+import type { SettingsManager } from "./settings-manager.ts";
 import { type TaskStepsState } from "./tasks/task-state.ts";
+import { type ToolProbeReport } from "./tool-protocol-controller.ts";
 import type { BashOperations } from "./tools/bash.ts";
 /**
  * Test hook: override the stream-idle bounds so a stall can be provoked in-suite without a
@@ -50,381 +47,9 @@ import type { BashOperations } from "./tools/bash.ts";
  * may be set or changed at any time before the request that should observe it.
  */
 export declare function setStreamIdleOptionsForTests(opts: Partial<StreamIdleOptions> | undefined): void;
-/** Parsed skill block from a user message */
-export interface ParsedSkillBlock {
-    name: string;
-    location: string;
-    content: string;
-    userMessage: string | undefined;
-}
-/**
- * Parse a skill block from message text.
- * Returns null if the text doesn't contain a skill block.
- */
-export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
-/** Session-specific events that extend the core AgentEvent */
-export type AgentSessionEvent = Exclude<AgentEvent, {
-    type: "agent_end";
-}> | {
-    type: "agent_end";
-    messages: AgentMessage[];
-    willRetry: boolean;
-} | {
-    type: "queue_update";
-    steering: readonly string[];
-    followUp: readonly string[];
-    commands: readonly string[];
-} | {
-    type: "compaction_start";
-    reason: "manual" | "threshold" | "overflow";
-} | {
-    type: "session_info_changed";
-    name: string | undefined;
-} | {
-    type: "thinking_level_changed";
-    level: ThinkingLevel;
-} | {
-    type: "warning";
-    message: string;
-} | {
-    type: "compaction_end";
-    reason: "manual" | "threshold" | "overflow";
-    result: CompactionResult | undefined;
-    aborted: boolean;
-    willRetry: boolean;
-    errorMessage?: string;
-    /**
-     * Benign no-op explanation for auto-compaction (e.g. "nothing to compact yet"). Auto
-     * bails must never be silent: without a result, either errorMessage (real failure) or
-     * skipReason (harmless skip) is set so the UI can show why nothing changed.
-     */
-    skipReason?: string;
-} | {
-    type: "auto_retry_start";
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-    errorMessage: string;
-} | {
-    type: "auto_retry_end";
-    success: boolean;
-    attempt: number;
-    finalError?: string;
-} | {
-    type: "routing_start";
-} | {
-    type: "routing_end";
-} | {
-    type: "delegate_workers";
-    active: number;
-    queued: number;
-    running: number;
-    completedSinceFlush: number;
-    failedSinceFlush: number;
-    terminalSinceFlush: Array<{
-        laneId: string;
-        status: LaneTerminalStatus;
-        reasonCode?: string;
-    }>;
-};
-/** Listener function for agent session events */
-export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-export interface AgentSessionConfig {
-    agent: Agent;
-    sessionManager: SessionManager;
-    settingsManager: SettingsManager;
-    cwd: string;
-    /** User-level agent state directory for generated runtime artifacts. */
-    agentDir?: string;
-    /** Models to cycle through with Ctrl+P (from --models flag) */
-    scopedModels?: Array<{
-        model: Model<any>;
-        thinkingLevel?: ThinkingLevel;
-    }>;
-    /** Resource loader for skills, prompts, themes, context files, system prompt */
-    resourceLoader: ResourceLoader;
-    /** SDK custom tools registered outside extensions */
-    customTools?: ToolDefinition[];
-    /** Model registry for API key resolution and model discovery */
-    modelRegistry: ModelRegistry;
-    /** Initial active built-in tool names. Default: [read, bash, edit, write, context_audit, goal] */
-    initialActiveToolNames?: string[];
-    /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
-    allowedToolNames?: string[];
-    /** Optional denylist of tool names. When provided, these tool names are not exposed. */
-    excludedToolNames?: string[];
-    /** Optional resource-profile allow/block filters for tool names. */
-    toolProfileFilter?: ResourceProfileFilterSettings;
-    /**
-     * Whether the model/thinking level came from an explicit launch flag. When false, the active
-     * profile's model/thinking is re-applied on reload() so live profile edits take effect; when
-     * true, the explicit launch-time choice is preserved.
-     */
-    isExplicitModel?: boolean;
-    isExplicitThinking?: boolean;
-    /** True when this session is a spawned subagent/child — gates durable memory writes. */
-    isChildSession?: boolean;
-    /**
-     * Override base tools (useful for custom runtimes).
-     *
-     * These are synthesized into minimal ToolDefinitions internally so AgentSession can keep
-     * a definition-first registry even when callers provide plain AgentTool instances.
-     */
-    baseToolsOverride?: Record<string, AgentTool>;
-    /** Mutable ref used by Agent to access the current ExtensionRunner */
-    extensionRunnerRef?: {
-        current?: ExtensionRunner;
-    };
-    /** Session start event metadata emitted when extensions bind to this runtime. */
-    sessionStartEvent?: SessionStartEvent;
-    /**
-     * Pointer-first workspace source collector for the autonomous research lane. Injected in unit
-     * tests so they don't spawn a real ripgrep child (which would escape fake timers); production
-     * defaults to the real, best-effort collector.
-     */
-    collectWorkspaceSources?: typeof collectWorkspaceSources;
-    /**
-     * Injected fetch/spawn/exists for the local (Ollama) runtime health-check + boot used by the
-     * model router before a turn routed to a local model (see LocalRuntimeController.ensureLocalModelReady).
-     * Unit tests inject fakes so they never hit a real network/process; production defaults to the real ones.
-     */
-    localRuntimeDeps?: LocalRuntimeDeps;
-}
-export interface ExtensionBindings {
-    uiContext?: ExtensionUIContext;
-    mode?: ExtensionContext["mode"];
-    commandContextActions?: ExtensionCommandContextActions;
-    abortHandler?: () => void;
-    shutdownHandler?: ShutdownHandler;
-    onError?: ExtensionErrorListener;
-}
-/** Options for AgentSession.prompt() */
-export interface PromptOptions {
-    /** Whether to expand file-based prompt templates and skills (default: true). */
-    expandPromptTemplates?: boolean;
-    /** Whether slash commands should be handled before sending to the model. Defaults to expandPromptTemplates. */
-    processSlashCommands?: boolean;
-    /** Image attachments */
-    images?: ImageContent[];
-    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */
-    streamingBehavior?: "steer" | "followUp";
-    /** Source of input for extension input event handlers. Defaults to "interactive". */
-    source?: InputSource;
-    /** Internal hook used by RPC mode to observe prompt preflight acceptance or rejection. */
-    preflightResult?: (success: boolean) => void;
-    /** Whether an idle active goal should auto-inject bounded continuation prompts after this prompt settles. Default: true. */
-    autoContinueGoal?: boolean;
-}
-export type ToolProbeVerdict = "native" | "text-protocol" | "none";
-export interface ToolProbeResult {
-    model: string;
-    verdict: ToolProbeVerdict;
-    variant?: TextToolProtocolVariant;
-    nativeGrade?: NativeToolProbeGrade;
-    diagnostic?: string;
-}
-export interface ToolProbeReport {
-    results: ToolProbeResult[];
-    table: string;
-}
-/** Result from cycleModel() */
-export interface ModelCycleResult {
-    model: Model<any>;
-    thinkingLevel: ThinkingLevel;
-    /** Whether cycling through scoped models (--models flag) or all available */
-    isScoped: boolean;
-}
-/** Session statistics for /session command */
-export interface CompactionGateStats {
-    gateFailures: number;
-    deterministicGapFills: number;
-    compactionsWithGateFailures: number;
-}
-export interface SessionStats {
-    sessionFile: string | undefined;
-    sessionId: string;
-    userMessages: number;
-    assistantMessages: number;
-    toolCalls: number;
-    toolResults: number;
-    totalMessages: number;
-    tokens: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        total: number;
-    };
-    cost: number;
-    contextUsage?: ContextUsage;
-    toolArgumentValidation: ToolArgumentValidationStats;
-    compactionGates: CompactionGateStats;
-}
-/** customType for spawned-usage roll-up entries (Cost Aggregation, Model A). */
-export declare const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
-/**
- * customType for a persisted runaway-loop-backstop entry: the agent loop stopped a turn stuck
- * repeating one identical tool-call signature. This is the session-log/telemetry sink for
- * {@link Agent.onRunawayStop} — see `_installAgentToolHooks`.
- */
-export declare const RUNAWAY_STOP_CUSTOM_TYPE = "runaway_stop";
-/** Payload persisted for a {@link RUNAWAY_STOP_CUSTOM_TYPE} entry. */
-export interface RunawayStopRecord {
-    signature: string;
-    repeats: number;
-    model?: string;
-    provider?: string;
-    at: string;
-}
-/**
- * customType for a persisted tool-validation-escalation entry: the agent loop bounced the same
- * tool-call validation failure enough times to escalate. This is the session-log/telemetry sink for
- * {@link Agent.onToolValidationEscalation} — see `_installAgentToolHooks`.
- */
-export declare const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = "tool_validation_escalation";
-/** Payload persisted for a {@link TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE} entry. */
-export interface ToolValidationEscalationRecord {
-    tool: string;
-    signature: string;
-    repeats: number;
-    model: string;
-    provider: string;
-    at: string;
-}
-/**
- * A single spawned/subagent usage report, persisted as a `CustomEntry`
- * (`customType: "spawned_usage"`). Persistence-only — does NOT enter LLM context.
- *
- * Single-hop invariant: each report MUST already include the reporter's own usage AND its
- * accumulated sub-usage. A child rolls up its grandchildren, then reports once to its direct
- * parent. Only the direct parent records the report — never a grandparent — so cost cannot be
- * double-counted across levels.
- */
-export interface SpawnedUsageReport {
-    /** Cumulative usage attributed to the spawned session (own + its own sub-usage). */
-    usage: Usage;
-    /** Human-readable source label for diagnostics (e.g. subagent name). */
-    label?: string;
-    /** Session id of the reporting child, if known. */
-    sourceSessionId?: string;
-    /** Stable id used to de-duplicate re-reports (retries, double agent_end). */
-    reportId?: string;
-}
-/** Aggregated spawned-usage totals derived from `spawned_usage` custom entries. */
-export interface SpawnedUsageTotals {
-    /** Summed `usage.cost.total` across all recorded reports. */
-    cost: number;
-    /** Number of distinct reports recorded. */
-    reports: number;
-}
-/**
- * Options for {@link AgentSession.runIsolatedCompletion} — an LLM call fully isolated from the main
- * session. With no tools it is one-shot (reflection); lane callers may supply a bounded child loop.
- */
-export interface IsolatedCompletionOptions {
-    /** System prompt for the isolated call. */
-    systemPrompt: string;
-    /** The isolated conversation (e.g. the reflection prompt). NOT the main session history. */
-    messages: Message[];
-    /** Model to use. Defaults to the session model; callers should pass a cheap model. */
-    model?: Model<any>;
-    /** Thinking level. Defaults to "off" to keep the call cheap. */
-    thinkingLevel?: ThinkingLevel;
-    /** Output token cap. */
-    maxTokens?: number;
-    /** Fresh tools owned by the isolated child. Omitted/empty preserves one-shot behavior. */
-    tools?: AgentTool[];
-    /** Maximum assistant turns for a tool-enabled child loop. Ignored by one-shot calls. */
-    maxTurns?: number;
-    /**
-     * Optional tool-free finalization prompt. When the bounded child loop exhausts its turns on an
-     * assistant tool-call message with no text, one final provider call receives the gathered transcript
-     * plus this prompt so useful work is not discarded solely for lacking a terminal summary.
-     */
-    finalTextPrompt?: string;
-    /** Child-only capability/path gate. Never inherited from the foreground session. */
-    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
-    /** Child-only result observer (for example, successful scoped-write accounting). */
-    afterToolCall?: AgentLoopConfig["afterToolCall"];
-    /** Abort signal. */
-    signal?: AbortSignal;
-    /**
-     * Prompt-cache retention for this isolated call. REQUIRED — the provider-level default is
-     * `"short"`, the opposite of this primitive's old implicit default, so a caller that forgot to
-     * set it would silently pay full input price forever. Pass `"none"` explicitly to preserve full
-     * isolation (no caching); callers whose `systemPrompt` is STATIC across calls (e.g. reflection,
-     * #33) should pass `"short"`/`"long"` so the provider reuses the cached prefix and bills only the
-     * variable tail.
-     */
-    cacheRetention: CacheRetention;
-    /**
-     * Lane/caller kind (e.g. `"reflection"`, `"research"`, `"worker"`, `"fitness"`) used to derive this
-     * call's synthetic cache-affinity key (see {@link computeLaneAffinityKey}). Omitted callers fall
-     * back to {@link DEFAULT_ISOLATED_LANE_KIND} — still a stable, namespaced key, just not
-     * lane-differentiated. Never the real session id.
-     */
-    laneKind?: string;
-}
-/** Fallback {@link IsolatedCompletionOptions.laneKind} for callers that do not tag their lane. */
-export declare const DEFAULT_ISOLATED_LANE_KIND = "isolated";
-/**
- * Derive a STABLE synthetic cache-affinity key for an isolated completion lane. Isolated calls
- * deliberately never carry the real session id (see reflection-controller.ts's isolation invariants —
- * an isolated call must not entangle with the main session), which today also means every isolated
- * call looks like a brand-new, uncorrelated session to providers with session-affinity headers /
- * `prompt_cache_key` (anthropic.ts's `x-session-affinity`, openai-responses.ts /
- * openai-completions.ts's `prompt_cache_key`), defeating their cache routing.
- *
- * This key is deterministic per `(laneKind, model, systemPrompt)` — the SAME lane calling the SAME
- * model with the SAME (static) system prompt always gets the SAME key, so repeat calls route to the
- * same cache-warm backend — while remaining fully synthetic: it is a salted hash, namespaced with a
- * `lane:` prefix, and never derived from or equal to the real session id.
- */
-export declare function computeLaneAffinityKey(laneKind: string, model: Model<any> | undefined, systemPrompt: string): string;
-/** Result of an isolated completion: the text, the usage spent, and the stop reason. */
-export interface IsolatedCompletionResult {
-    text: string;
-    usage: Usage;
-    stopReason: StopReason;
-}
-export interface ResearchLaneRunOutcome {
-    /** False when the pass was skipped before starting (see skipReason). */
-    started: boolean;
-    skipReason?: string;
-    /** Terminal lane record when the pass ran. */
-    record?: LaneRecord;
-    result?: ResearchRunResult;
-}
-export interface WorkerDelegationRunOutcome {
-    /** False when the delegation was skipped before starting (see skipReason). */
-    started: boolean;
-    skipReason?: string;
-    /** Terminal lane record when the delegation ran. */
-    record?: LaneRecord;
-    outcome?: WorkerRunOutcome;
-}
-export interface GoalContinuationOnceOptions {
-    maxStallTurns: number;
-    promptLimits?: GoalContinuationPromptLimits;
-}
-export interface GoalContinuationOnceResult {
-    submitted: boolean;
-    snapshot: GoalRuntimeSnapshot;
-    prompt?: GoalContinuationPrompt;
-}
-export type GoalContinuationLoopStopReason = "continuation_not_allowed" | "max_turns_reached" | "wall_clock_budget_reached" | "goal_state_not_advanced" | "goal_budget_exhausted" | "already_continuing" | "session_disposed" | "goal_tool_unavailable" | "worker_in_flight";
-export interface GoalContinuationLoopOptions extends GoalContinuationOnceOptions {
-    maxTurns: number;
-    /** 0 or undefined disables wall-clock budget. */
-    maxWallClockMinutes?: number;
-    /** Test seam for wall-clock budget enforcement. Defaults to Date.now. */
-    now?: () => number;
-}
-export interface GoalContinuationLoopResult {
-    turnsSubmitted: number;
-    stopReason: GoalContinuationLoopStopReason;
-    finalSnapshot: GoalRuntimeSnapshot;
-}
+export * from "./agent-session-contracts.ts";
+import type { AgentSessionConfig, AgentSessionEventListener, ExtensionBindings, GoalContinuationLoopOptions, GoalContinuationLoopResult, GoalContinuationOnceOptions, GoalContinuationOnceResult, IsolatedCompletionOptions, IsolatedCompletionResult, ModelCycleResult, PromptOptions, ResearchLaneRunOutcome, SessionStats, SpawnedUsageTotals, WorkerDelegationRunOutcome } from "./agent-session-contracts.ts";
+export type { ToolProbeReport, ToolProbeResult, ToolProbeVerdict } from "./tool-protocol-controller.ts";
 export declare class AgentSession {
     readonly agent: Agent;
     readonly sessionManager: SessionManager;
@@ -444,12 +69,8 @@ export declare class AgentSession {
      * switching from a small-window model back to a large one restores the full requested set.
      */
     private _requestedActiveToolNames;
-    private _compactionAbortController;
-    private _autoCompactionAbortController;
-    private _overflowRecoveryAttempted;
     private _unboundToolGrantWarnings;
     private _branchSummaryAbortController;
-    private _retryController;
     private readonly _modelSelection;
     private readonly _bash;
     private readonly _profileFilter;
@@ -466,39 +87,26 @@ export declare class AgentSession {
     private _agentDir;
     private _collectWorkspaceSources;
     private readonly _localRuntimeController;
-    private readonly _modelAdaptationStore;
+    private readonly _toolProtocol;
     private _prefixWarmer;
     private readonly _completedPrefixWarms;
-    private readonly _repairModeSessionCounts;
-    private readonly _textProtocolParseFailures;
-    private _textProtocolParseObservedThisTurn;
-    /** Total text-protocol parse-failure events observed this session, backing the
-     * {@link TEXT_TOOL_PROTOCOL_STEER_INTERVAL} throttle on {@link _maybeInjectTextProtocolCorrectiveSteer}. */
-    private _textProtocolCorrectiveSteerCount;
-    /** Monotonic counter backing tool-probe/text-protocol-calibration spawned-usage reportIds
-     * (see {@link _nextProbeUsageReportId}); guarantees each probe/calibration completion in the
-     * session lands in the cost ledger exactly once, even across repeated /toolprobe invocations. */
-    private _toolProbeUsageReportSeq;
-    /** Anti-loop: modelKeys the evidence-gated auto-probe has already fired for THIS session (see
-     * {@link _maybeAutoProbeOnValidationEscalation}), so a burst of validation-escalation events for
-     * the same still-failing model never re-fires the probe more than once per session. */
-    private readonly _autoProbedModels;
-    private _textProtocolValidationOutcomeThisTurn;
     /** Assembles the session's base system prompt from live session state (see
      * system-prompt-builder.ts); owns the paired _baseSystemPromptOptions. */
     private readonly _systemPromptBuilder;
     /** Autonomy telemetry sink + status/diagnostic snapshots (see autonomy-telemetry.ts); owns
      * the latest gate outcome and the bounded gate-outcome history. */
     private readonly _autonomyTelemetry;
-    /** Goal auto-continue + research lane + scout-worker delegation + model-fitness probe (see
+    /** Goal auto-continue + research lane + profile-bound worker delegation + model-fitness probe (see
      * background-lane-controller.ts); owns the lane timers/guards, the last research-lane skip
      * reason, the live LaneTracker, and the in-flight research/worker abort controllers. */
     private readonly _backgroundLanes;
+    private readonly _humanInput;
     /** Plug-and-play memory subsystem (see memory-controller.ts); owns the OKF retrieval provider, the
      * latest retrieval/prompt-inclusion reports, the reload-safe MemoryManager, the recall
      * effectiveness tracker, and the extension-contributed pending providers. */
     private readonly _memory;
     private readonly _compactionSupport;
+    private readonly _compaction;
     /** Per-turn context-shaping subsystem (see context-pipeline.ts); owns the latest
      * audit/policy/correlation/enforcement/gc reports, the brain-curation sidecar + its skip reasons,
      * and the tool-output artifact store. Invoked stage-by-stage from the context transform. */
@@ -528,19 +136,19 @@ export declare class AgentSession {
      * used by the status report. Its parallel routed drive path delegates every turn back to
      * {@link _runAgentPrompt} so the drive loop stays host-side. */
     private readonly _modelRouter;
-    private readonly _billingFailover;
+    private readonly _foregroundRecovery;
     private readonly _failureCorpus;
     private readonly _toolRecoveryLogger;
     private readonly _toolRecoveryEventLogPath;
     private _skillCuratorInstance?;
     private _disposed;
+    private _disposeCompletion;
     private readonly _reflectionAbort;
     /** Native reflection engine + learning-apply/rollback path (see reflection-controller.ts); owns no
      * session state, applies durable writes through the bundled memory tool and the session log. */
     private readonly _reflection;
-    /** Bounded goal auto-continuation loop (see goal-loop-controller.ts); reads goal state fresh
-     * each pass and re-enters the session's own prompt path. */
-    private readonly _goalContinuation;
+    /** Durable goal lifecycle, accounting, and raw continuation loop. */
+    private readonly _goals;
     private readonly _isChildSession;
     private _baseToolsOverride?;
     private _sessionStartEvent;
@@ -600,7 +208,8 @@ export declare class AgentSession {
      * The ceiling is turn-cumulative: the next foreground call's projection is folded together with
      * background/research/worker/reflection spend recorded SINCE THIS TURN BEGAN — {@link getSpawnedUsage}'s
      * already-recorded rollup (the same read-side-deduped total the footer's SUBAGENTS line uses) minus the
-     * baseline snapshotted at the top of `_promptUnserialized` ({@link _costGuardTurnBaselineUsd}) — so a
+     * baseline snapshotted before a new turn enters routing in `_promptUnserialized`
+     * ({@link _costGuardTurnBaselineUsd}) — so a
      * turn that is cheap in the foreground but has spent heavily via background lanes THIS turn still trips
      * the warning, while a prior turn's background spend does not keep every later turn's guard stuck
      * "over". A background lane that finishes mid-turn is attributed to whichever turn it completes in.
@@ -630,67 +239,14 @@ export declare class AgentSession {
     restorePromotedSkill(name: string): boolean;
     private _installAgentTurnRefresh;
     private _createAgentContextSnapshot;
-    private _modelAdaptationKeyFor;
-    private _toolRepairSettings;
-    private _applyToolRepairLayerSettings;
-    private _getModelAdaptationRulesForPrompt;
-    private _textProtocolFlag;
-    private _streamForToolProbe;
-    /** Builds a reportId that uniquely identifies one probe/calibration completion within the
-     * session: the model, a caller-supplied `kind` (e.g. "read-task", "echo", or
-     * "text-protocol:<variant>"), and a monotonic sequence number. The sequence number (not
-     * wall-clock time or randomness) is what guarantees no collision even when the same model+kind
-     * is probed again later in the session (e.g. a repeated /toolprobe run), so genuine repeat spend
-     * is never silently deduped away. */
-    private _nextProbeUsageReportId;
-    private _resolveProbeStreamCountingUsage;
-    private _textProtocolCalibrationContext;
-    private _messageHasToolCallWithStringArgument;
-    private _nativeToolProbeSystemPrompt;
-    private _runNativeReadTaskProbeTrial;
-    private _runNativeEchoToolProbeTrial;
-    private _gradeNativeToolCallingForModel;
-    private _runTextProtocolTrial;
-    private _calibrateTextToolProtocolForModel;
-    private _ensureTextToolProtocolForActiveModel;
-    private _modelRef;
-    /** The persisted `/toolprobe` verdict on record for this model, if any (undefined = unprobed). */
-    private _toolProbeVerdict;
-    private _formatToolProbeReport;
-    private _storeToolProbe;
+    /** Compatibility seam retained for focused auto-probe regressions. */
     private _probeToolCallingForModel;
-    private _resolveToolProbeModels;
+    /** Compatibility seam retained for focused protocol-selection doctrine regressions. */
+    private _resolveModelToolProtocol;
     probeToolCalling(target?: string): Promise<ToolProbeReport>;
-    /**
-     * The text-protocol circuit breaker. Every parse failure (from either the
-     * live per-completion {@link Agent.onTextToolProtocolParse} callback or the post-hoc detection in
-     * {@link _recordTextToolProtocolParseOutcomeFromLastAssistant}) gets a throttled one-line
-     * corrective steer for the next turn. On the 3rd consecutive SAME-SIGNATURE failure — graded
-     * evidence a model genuinely cannot speak this dialect, not a single bad turn — the breaker also
-     * demotes the persisted tool-probe verdict to "none" so {@link _textProtocolFlag} reads false next
-     * turn and native is attempted instead of thrashing on a protocol this model has proven it can't
-     * follow.
-     */
-    private _handleTextToolProtocolParse;
-    /**
-     * A phone model whose envelope fails to parse gets no corrective guidance today —
-     * the runaway-loop backstop only trips on repeated PARSED tool-call signatures (agent-loop.ts), so
-     * an every-turn unparseable-prose model never trips it. Inject a one-line reminder of the envelope
-     * shape as a nextTurn message, reusing {@link formatVariantEnvelope} so the reminder can never
-     * drift from the grammar the primer actually teaches. Throttled to the first failure this session
-     * and then every {@link TEXT_TOOL_PROTOCOL_STEER_INTERVAL}th after — the breaker above is what
-     * actually demotes a genuinely-failing model at the 3rd same-signature failure; this is guidance,
-     * not a second counter.
-     */
-    private _maybeInjectTextProtocolCorrectiveSteer;
-    private _handleTextToolProtocolValidationOutcome;
-    private _recordTextToolProtocolParseOutcomeFromLastAssistant;
-    private _looksLikeTextToolProtocolAttempt;
-    private _tagModelAdaptationRuleTeaching;
-    private _repairSessionCount;
-    private _handleModelAdaptationTelemetry;
     /** Tool-build call-site delegation to {@link ContextPipeline.getToolArtifactStore}. */
     private _getToolArtifactStore;
+    private _getSessionImageStore;
     /**
      * Context-transform hot-path delegation to {@link ContextPipeline.runContextAudit}. Kept as a
      * one-line method (not inlined) so the transform stays the single owner of the pass ordering.
@@ -779,12 +335,6 @@ export declare class AgentSession {
     private _applyContextGc;
     /** Read-only inspection of the latest context-gc report (delegates to {@link ContextPipeline.getContextGcReport}). */
     getContextGcReport(messages?: AgentMessage[]): ContextGcReport;
-    /**
-     * Context-transform hot-path delegation to {@link ContextPipeline.estimateCurrentContextTokens}. Kept
-     * as a one-line method (not inlined) so the transform stays the single owner of the pass ordering;
-     * also feeds the per-turn cost guard.
-     */
-    private _estimateCurrentContextTokens;
     private _installAgentToolHooks;
     /**
      * The runaway-loop backstop ({@link Agent.maxStallTurns}) stopped a turn stuck repeating one
@@ -793,11 +343,6 @@ export declare class AgentSession {
      * warning through the same event the context-window/compaction backstops use.
      */
     private _handleRunawayStop;
-    /** Anti-loop: true when this model's persisted tool-probe verdict was written within the
-     * auto-probe freshness window ({@link AUTO_TOOL_PROBE_FRESHNESS_MS}) — covers a very recent
-     * explicit `/toolprobe` run or a fresh circuit-breaker demote from an EARLIER session, complementing
-     * the in-session {@link _autoProbedModels} latch. */
-    private _hasFreshToolProbeVerdict;
     /**
      * Evidence-gated native→phone auto-probe for a LOCAL/MANAGED model (never cloud — see
      * {@link isLocalOrManagedRouterModel}) that just crossed the tool-argument-validation escalation
@@ -808,7 +353,7 @@ export declare class AgentSession {
      * "native" and is never phoned) entirely OFF the hot path — fired here but never awaited by the
      * caller, so a slow or failing probe can never block or throw the user's in-flight turn.
      * Anti-loop: skipped when this session already auto-probed this model, or a fresh persisted
-     * verdict already exists ({@link _hasFreshToolProbeVerdict}) — otherwise a model that keeps
+     * verdict already exists (enforced by {@link ToolProtocolController}) — otherwise a model that keeps
      * failing validation every turn would re-fire the (multi-completion) probe every single turn.
      */
     private _maybeAutoProbeOnValidationEscalation;
@@ -839,7 +384,6 @@ export declare class AgentSession {
     private _emit;
     private _notifyWorkerTerminalHandoff;
     private _emitQueueUpdate;
-    private _lastAssistantMessage;
     /**
      * User messages already painted to the UI by an early, synthetic `message_start` fired from
      * `_promptUnserialized` — before the model-router judge's bounded LLM call — so the prompt
@@ -891,10 +435,12 @@ export declare class AgentSession {
      * Call this when completely done with the session.
      */
     dispose(): void;
+    /** Dispose synchronously-visible state, then await all session-owned asynchronous shutdowns. */
+    disposeAndWait(): Promise<void>;
     /** Full agent state */
     get state(): AgentState;
     /** Current model (may be undefined if not yet selected) */
-    get model(): Model<any> | undefined;
+    get model(): Model<Api> | undefined;
     /** Current thinking level */
     get thinkingLevel(): ThinkingLevel;
     /** Whether agent is currently streaming a response */
@@ -929,7 +475,7 @@ export declare class AgentSession {
      * Changes take effect on the next agent turn.
      *
      * artifact_retrieve is auto-activated as a companion whenever an artifact-producing tool
-     * (grep, find, or run_toolkit_script) ends up in the resulting active set and artifact_retrieve
+     * (grep, find, run_toolkit_script, or ask_question) ends up in the resulting active set and artifact_retrieve
      * is registered (i.e. not excluded/
      * blocked/outside an allowlist -- the registry itself is built with that same filter,
      * so registry presence already tracks "allowed"). This is enforced here, not just in
@@ -956,12 +502,12 @@ export declare class AgentSession {
     get sessionName(): string | undefined;
     /** Scoped models for cycling (from --models flag) */
     get scopedModels(): ReadonlyArray<{
-        model: Model<any>;
+        model: Model<Api>;
         thinkingLevel?: ThinkingLevel;
     }>;
     /** Update scoped models for cycling */
     setScopedModels(scopedModels: Array<{
-        model: Model<any>;
+        model: Model<Api>;
         thinkingLevel?: ThinkingLevel;
     }>): void;
     /** File-based prompt templates */
@@ -976,6 +522,12 @@ export declare class AgentSession {
      */
     private _buildSystemPromptForToolNames;
     private _runAgentPrompt;
+    /**
+     * Re-enter an interrupted ask_question call from its durable request snapshot. Pending requests
+     * are presented again; already-checkpointed answers are replayed without asking twice. The
+     * original toolCallId is preserved so provider tool-call ordering remains valid on /resume.
+     */
+    resumePendingHumanInput(): Promise<boolean>;
     /**
      * Shared {@link OllamaRuntime} for a given server, lazily created and cached by baseUrl so every
      * caller — the router's readiness gate and any host UI's own model-lifecycle commands (e.g.
@@ -1105,7 +657,7 @@ export declare class AgentSession {
      * Abort current operation and wait for agent to become idle.
      */
     abort(): Promise<void>;
-    setModel(model: Model<any>, options?: {
+    setModel(model: Model<Api>, options?: {
         persistSettings?: boolean;
     }): Promise<void>;
     /** Re-resolve startup profile model/thinking after allowed extension providers are bound. */
@@ -1156,7 +708,18 @@ export declare class AgentSession {
     private _checkContextWindowUsageWarning;
     private _checkCompaction;
     private _measureLiveContextTokensForCompaction;
+    /**
+     * Internal: Run auto-compaction with events.
+     */
     private _runAutoCompaction;
+    /**
+     * Run one compaction attempt, retrying retryable provider failures (stream stalls,
+     * 429/5xx, network drops) with the session's retry policy. The reliability kernel
+     * classifies a stall as retryable by design (see withStreamIdleWatchdog); without this
+     * loop a single transient killed the whole compaction while ordinary turns survived the
+     * same failure via auto-retry. Caller aborts are never retried; sleepAbortable rejects
+     * with the abort reason if the signal fires mid-backoff.
+     */
     private _compactWithRetry;
     /**
      * Toggle auto-compaction setting.
@@ -1202,14 +765,6 @@ export declare class AgentSession {
      * Falls back to full reload if any individual load/unload fails.
      */
     reconcileLoadedExtensions(): Promise<void>;
-    /**
-     * Check if an error is retryable (transient provider/network failures). Billing/quota and auth
-     * are terminal; context overflow is handled by compaction, not retry. The verdict comes from the
-     * reliability kernel's classifier, fed the host-computed context-overflow flag.
-     */
-    private _classifyAssistantError;
-    private _isRetryableError;
-    private _prepareRetry;
     /**
      * Cancel in-progress retry.
      */
@@ -1270,26 +825,30 @@ export declare class AgentSession {
      *
      * @returns the id of the appended custom entry
      */
-    saveGoalStateSnapshot(state: GoalState): string;
+    saveGoalStateSnapshot(state: GoalState, expected?: GoalStateRevision): string;
+    /** Persist a branch-scoped tombstone and stop goal-owned execution without resurrecting old state. */
+    clearGoalStateSnapshot(state: GoalState, now: string): string;
     /**
      * Retrieve the latest valid goal state snapshot from the session log.
      */
     getGoalStateSnapshot(): GoalState | undefined;
     /**
-     * Persist one submitted continuation pass's turn/wall-clock/spend contribution onto the active
-     * goal's durable cumulative budget (see `GoalState.continuationTurnsUsed` et al.). This is the
+     * Persist one submitted continuation pass's exact turn/wall-clock/token/spend contribution onto the active
+     * goal's durable cumulative accounting (see `GoalState.continuationTurnsUsed` et al.). This is the
      * "persistence dep" `GoalLoopController` calls once per pass actually submitted — it, not the
-     * loop controller, is where USD gets attributed: it reads the session's OWN cumulative model
-     * spend (`getCostSummary().ownCost` — deliberately excludes worker/subagent spend, which is
-     * tracked and budgeted separately) and threads that single absolute reading into a
-     * `record_continuation_budget` event; the pure reducer in `goal-state.ts` derives the delta.
+     * loop controller, is where usage gets attributed: it scans only assistant messages appended on
+     * the active branch after the pass's captured cursor. Compaction cannot erase or reattribute that
+     * append-only interval, and unrelated foreground turns outside the interval are excluded.
      * A no-op when no goal state exists (defensive — in practice this is only ever called right
      * after a pass the loop already confirmed was submitted against an active goal).
      */
     recordGoalContinuationPass(pass: {
         turns: number;
         wallClockMs: number;
+        usageCursor: string | null;
     }): void;
+    /** Restore runtime intent without mutating persisted goal lifecycle state. */
+    restoreGoalRuntimeAfterResume(): void;
     /** Save native task-step state to the active session log. */
     saveTaskStepsStateSnapshot(state: TaskStepsState): string;
     /** Retrieve the latest valid native task-step state from the active session log. */
@@ -1301,9 +860,10 @@ export declare class AgentSession {
      */
     saveEvidenceBundleSnapshot(bundle: EvidenceBundle): string;
     /**
-     * Retrieve the latest valid evidence bundle snapshot from the session log.
+     * Retrieve the latest valid evidence bundle snapshot from the active branch.
      */
     getEvidenceBundleSnapshot(): EvidenceBundle | undefined;
+    /** Retrieve all valid evidence bundle snapshots from the active branch. */
     getEvidenceBundleSnapshots(): EvidenceBundle[];
     /** Live lane records tracked by this process (running and terminal). */
     getLaneRecords(): LaneRecord[];
@@ -1311,8 +871,8 @@ export declare class AgentSession {
     private _recordGateOutcome;
     /** Copies of the bounded gate-outcome history, oldest first, latest last. */
     getGateOutcomeHistory(): GateOutcomeHistoryEntry[];
-    saveWorkerResultSnapshot(result: WorkerResult, request?: WorkerRequest): string;
-    getWorkerResultSnapshots(): WorkerResult[];
+    saveWorkerClaimSnapshot(claim: WorkerClaim, request?: WorkerRequest): string;
+    getWorkerClaimSnapshots(): WorkerClaim[];
     saveLearningDecisionSnapshot(decision: LearningDecision): string;
     getLearningDecisionSnapshots(): LearningDecision[];
     /**
@@ -1347,14 +907,10 @@ export declare class AgentSession {
         goalId?: string;
     }): Promise<ResearchLaneRunOutcome>;
     /**
-     * Run one bounded scout-worker delegation. Delegates to {@link BackgroundLaneController};
+     * Run one bounded profile-bound worker delegation. Delegates to {@link BackgroundLaneController};
      * consumed by the `delegate` tool.
      */
-    runWorkerDelegationOnce(request: {
-        instructions: string;
-        systemPrompt?: string;
-        memoryRead?: boolean;
-    }): Promise<WorkerDelegationRunOutcome>;
+    runWorkerDelegationOnce(request: WorkerDelegationRequest): Promise<WorkerDelegationRunOutcome>;
     /**
      * Probe a candidate model against the subagent contracts. Delegates to
      * {@link BackgroundLaneController}; probe spend is reported through spawned-usage accounting.
@@ -1378,7 +934,7 @@ export declare class AgentSession {
      * continuation. Delegates to {@link BackgroundLaneController.continueGoalLoopExclusive}, the
      * single-flight guard that prevents two goal loops from racing to submit prompts through the
      * same session (which throws "Agent is already processing" from the second submission). Do not
-     * call `this._goalContinuation.continueGoalLoop` directly from here — that bypasses the guard.
+     * call `this._goals.continueLoop` directly from here — that bypasses the guard.
      */
     continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult>;
     /**
@@ -1393,7 +949,7 @@ export declare class AgentSession {
     runReflectionPass(input: {
         signals: DemandSignals;
         recentTurnText: string;
-        model?: Model<any>;
+        model?: Model<Api>;
         thinkingLevel?: ThinkingLevel;
         signal?: AbortSignal;
         /** Stable id so a duplicate scheduling/retry of the same pass can't double-count its cost. */