apex-code 0.0.1-alpha.8 → 0.0.4

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

@@ -13,24 +13,35 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import type { ImageContent, Model, TextContent } from "@earendil-works/pi-ai/compat";
-import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "apex-code-agent-core";
+import type { Agent, AgentEvent, AgentMessage, AgentState, AgentStopReason, AgentTool, ThinkingLevel } from "apex-code-agent-core";
 import { type BashResult } from "./bash-executor.ts";
+import type { CheckpointSettings } from "./checkpoints/git-checkpoints.ts";
+import { type SessionCheckpoints } from "./checkpoints/session-checkpoints.ts";
 import { type CompactionResult } from "./compaction/index.ts";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, type ExtensionMode, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
+import { type FormatterRunOutcome } from "./formatter-lifecycle.ts";
+import type { HookRuntime } from "./hooks/types.ts";
+import type { McpRuntime } from "./mcp/runtime.ts";
 import type { CustomMessage } from "./messages.ts";
 import type { ModelRuntime } from "./model-runtime.ts";
 import { type PermissionGateOptions } from "./permissions/gate.ts";
+import type { PermissionResponder } from "./permissions/responder.ts";
 import { type EffectiveModeResolution } from "./permissions/startup.ts";
 import type { PermissionMode } from "./permissions/store.ts";
 import { type PromptTemplate } from "./prompt-templates.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
 import type { BranchSummaryEntry, SessionEntry, SessionManager } from "./session-manager.ts";
 import type { SettingsManager } from "./settings-manager.ts";
+import type { BackgroundShellRegistry } from "./tools/background-shell.ts";
 import { type BashOperations } from "./tools/bash.ts";
 import type { EvidenceSink } from "./tools/contract.ts";
+import { type ToolContractSnapshotEntry } from "./tools/contract-snapshot.ts";
 import type { DiagnosticsOperations } from "./tools/diagnostics.ts";
 import type { LspOperations } from "./tools/lsp.ts";
 import type { WebSearchOperations } from "./tools/web-search.ts";
+import { type VerificationCompletionStatus, type VerificationRecord } from "./verification-lifecycle.ts";
+import { type GitObserveOptions } from "./workspace/git-observer.ts";
+import { type WorkspaceStateRecord } from "./workspace/state.ts";
 /** Parsed skill block from a user message */
 export interface ParsedSkillBlock {
     name: string;
@@ -50,6 +61,8 @@ export type AgentSessionEvent = Exclude<AgentEvent, {
     type: "agent_end";
     messages: AgentMessage[];
     willRetry: boolean;
+    /** Structured terminal outcome of the run (budget exhaustion, abort, error, completion). */
+    stopReason?: AgentStopReason;
 } | {
     type: "agent_settled";
 } | {
@@ -172,12 +185,38 @@ export interface AgentSessionConfig {
      * `baseToolsOverride` is set.
      */
     lspOperations?: LspOperations;
+    /** Assembled MCP subsystem, present only when at least one server is configured. */
+    mcpRuntime?: McpRuntime;
     /**
      * Optional `web_search` backend. Absent leaves the tool on its unconfigured
      * operations, which throw a model-readable "not configured" error rather than
      * returning zero results. Ignored when `baseToolsOverride` is set.
      */
     webSearchOperations?: WebSearchOperations;
+    /**
+     * Git-backed worktree checkpoints. Absent, or present with `enabled` unset, captures
+     * nothing and runs no `git` subprocess.
+     */
+    checkpointSettings?: CheckpointSettings;
+    /**
+     * Declarative hooks (spec 2026-08-31-declarative-hooks). Absent constructs
+     * nothing: no subprocess, no behavior change. Assembled by `createAgentSession`
+     * from the merged settings -- project-scope entries only appear once trusted,
+     * because untrusted project settings are not loaded at all.
+     */
+    hookRuntime?: HookRuntime;
+    /**
+     * Background-shell registry (spec 2026-08-31-background-shell.md). Absent
+     * constructs nothing. Created by `createAgentSession` when not supplied and
+     * disposed with the session, so background children never outlive it.
+     */
+    backgroundShellRegistry?: BackgroundShellRegistry;
+    /**
+     * Optional headless permission bridge (ACP, spec 2026-08-31-acp-adapter.md):
+     * consulted before the interactive TUI responder. Absent keeps today's
+     * behavior -- asks without a responder fail closed.
+     */
+    permissionResponderFactory?: () => PermissionResponder | undefined;
 }
 export interface ExtensionBindings {
     uiContext?: ExtensionUIContext;
@@ -200,6 +239,11 @@ export interface PromptOptions {
     /** Internal hook used by RPC mode to observe prompt preflight acceptance or rejection. */
     preflightResult?: (success: boolean) => void;
 }
+/** Options for model/thinking mutations. */
+export interface ModelMutationOptions {
+    /** Persist the new value to global defaults. Defaults to session-only. */
+    persist?: boolean;
+}
 /** Result from cycleModel() */
 export interface ModelCycleResult {
     model: Model<any>;
@@ -226,6 +270,26 @@ export interface SessionStats {
     cost: number;
     contextUsage?: ContextUsage;
 }
+/** Explicit workspace policy for `/tree` and `/fork`-family navigation (spec § 4). */
+export type TreeWorkspacePolicy = "keep" | "restore" | "fail-if-drifted" | "cancel";
+/** What the navigation did to the workspace, reported separately from the conversation move. */
+export interface TreeWorkspaceOutcome {
+    policy: TreeWorkspacePolicy;
+    outcome: "unchanged" | "restored" | "refused-drifted" | "missing-checkpoint" | "failed";
+    /** Checkpoint of the pre-restore state; present when a restore overwrote anything. */
+    preRestoreCheckpoint?: {
+        entryId: string;
+        commit: string;
+    };
+    warnings: string[];
+}
+export interface TreeNavigationResult {
+    editorText?: string;
+    cancelled: boolean;
+    aborted?: boolean;
+    summaryEntry?: BranchSummaryEntry;
+    workspace?: TreeWorkspaceOutcome;
+}
 export declare class AgentSession {
     readonly agent: Agent;
     readonly sessionManager: SessionManager;
@@ -242,9 +306,12 @@ export declare class AgentSession {
     private _followUpMessages;
     /** Messages queued to be included with the next user prompt as context ("asides"). */
     private _pendingNextTurnMessages;
+    /** Context-only custom messages queued during a run, flushed once the current turn's tool results are in. */
+    private _pendingCustomMessages;
     private _compactionAbortController;
     private _autoCompactionAbortController;
     private _overflowRecoveryAttempted;
+    private _midRunCompactionNeeded;
     private _branchSummaryAbortController;
     private _retryAbortController;
     private _retryAttempt;
@@ -256,6 +323,21 @@ export declare class AgentSession {
     private _customTools;
     private _baseToolDefinitions;
     private _cwd;
+    /**
+     * Workspace observation adapter for compaction capture (WS.4). Injectable
+     * so tests can force capture outcomes without a real repository.
+     */
+    _workspaceObserver: (root: string, options?: GitObserveOptions) => Promise<WorkspaceStateRecord>;
+    /**
+     * WS.5: one workspace comparison is due at the next model-turn boundary.
+     * Set after a compaction stored an observation, or on construction when
+     * the session's latest observation has no later comparison (resume).
+     */
+    private _workspaceComparePending;
+    /** VF.4: verification lifecycle state, built lazily from policy settings. */
+    private _verificationTracker;
+    /** The workspace observation a verification result described, for staleness. */
+    private _verificationBaseline;
     private _extensionRunnerRef?;
     private _initialActiveToolNames?;
     private _allowedToolNames?;
@@ -266,6 +348,15 @@ export declare class AgentSession {
     private _evidenceSink?;
     private _diagnosticsOperations?;
     private _lspOperations?;
+    private _mcpRuntime?;
+    /** Configured MCP subsystem, or undefined when no server is configured. */
+    get mcpRuntime(): McpRuntime | undefined;
+    private readonly _checkpoints;
+    private readonly _hookRuntime;
+    private readonly _backgroundShellRegistry;
+    private readonly _permissionResponderFactory;
+    /** Worktree checkpoints for this session. Inert unless `checkpoints.enabled` is set. */
+    get checkpoints(): SessionCheckpoints;
     private _webSearchOperations?;
     private _extensionUIContext?;
     private _extensionMode;
@@ -296,7 +387,11 @@ export declare class AgentSession {
      * happens here instead of in wrappers.
      */
     private _installAgentToolHooks;
+    private _compactBeforeNextAssistantResponse;
     private _installAgentNextTurnRefresh;
+    /** Stop an over-threshold tool loop before it sends another provider request. */
+    private _installMidRunCompactionHook;
+    private _shouldStopForMidRunCompaction;
     /**
      * Installs the context pipeline settled in `docs/architecture/contracts.md` § 2:
      * deferred-schema resolution → tool-result eviction → compaction. Compaction
@@ -330,6 +425,7 @@ export declare class AgentSession {
     /** Emit an event to all listeners */
     private _emit;
     private _emitQueueUpdate;
+    private _emitSessionCompactFailed;
     private _getIdleWaitPromise;
     private _resolveIdleWaitIfIdle;
     private _emitAgentSettled;
@@ -376,6 +472,11 @@ export declare class AgentSession {
     /**
      * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
      */
+    /**
+     * The ADR 0010 projection over this session's registry: the one read every surface
+     * that *describes* the tool set consumes. Never an authorization input.
+     */
+    getToolContractSnapshot(): ToolContractSnapshotEntry[];
     getAllTools(): ToolInfo[];
     getToolDefinition(name: string): ToolDefinition | undefined;
     /**
@@ -459,8 +560,9 @@ export declare class AgentSession {
     /**
      * Send a custom message to the session. Creates a CustomMessageEntry.
      *
-     * Handles three cases:
+     * Handles four cases:
      * - Streaming: queues message, processed when loop pulls from queue
+     * - Streaming + triggerTurn false: appended to state/session once the current turn ends
      * - Not streaming + triggerTurn: appends to state/session, starts new turn
      * - Not streaming + no trigger: appends to state/session, no turn
      *
@@ -472,6 +574,12 @@ export declare class AgentSession {
         triggerTurn?: boolean;
         deliverAs?: "steer" | "followUp" | "nextTurn";
     }): Promise<void>;
+    private _appendCustomMessage;
+    /**
+     * Append custom messages queued while the agent was running.
+     * Called once the current turn's tool results are in agent state and session history.
+     */
+    private _flushPendingCustomMessages;
     /**
      * Send a user message to the agent. Always triggers a turn.
      * When the agent is streaming, use deliverAs to specify how to queue the message.
@@ -523,30 +631,33 @@ export declare class AgentSession {
     setPermissionMode(mode: PermissionMode): Promise<EffectiveModeResolution | undefined>;
     /**
      * Set model directly.
-     * Validates that auth is configured, saves to session and settings.
+     * Validates that auth is configured and saves to the session transcript.
+     * Persists to global defaults only when options.persist is true.
      * @throws Error if no auth is configured for the model
      */
-    setModel(model: Model<any>): Promise<void>;
+    setModel(model: Model<any>, options?: ModelMutationOptions): Promise<void>;
+    private _addPersistedDefaultToNonEmptyScope;
     /**
      * Cycle to next/previous model.
      * Uses scoped models (from --models flag) if available, otherwise all available models.
      * @param direction - "forward" (default) or "backward"
      * @returns The new model info, or undefined if only one model available
      */
-    cycleModel(direction?: "forward" | "backward"): Promise<ModelCycleResult | undefined>;
+    cycleModel(direction?: "forward" | "backward", options?: ModelMutationOptions): Promise<ModelCycleResult | undefined>;
     private _cycleScopedModel;
     private _cycleAvailableModel;
     /**
      * Set thinking level.
      * Clamps to model capabilities based on available thinking levels.
-     * Saves to session and settings only if the level actually changes.
+     * Saves the clamped level to the session transcript only if the level actually changes.
+     * Persists the requested level to global defaults only when options.persist is true.
      */
-    setThinkingLevel(level: ThinkingLevel): void;
+    setThinkingLevel(level: ThinkingLevel, options?: ModelMutationOptions): void;
     /**
      * Cycle to next thinking level.
      * @returns New level, or undefined if model doesn't support thinking
      */
-    cycleThinkingLevel(): ThinkingLevel | undefined;
+    cycleThinkingLevel(options?: ModelMutationOptions): ThinkingLevel | undefined;
     /**
      * Get available thinking levels for current model.
      * The provider will clamp to what the specific model supports internally.
@@ -569,9 +680,69 @@ export declare class AgentSession {
      * Saves to settings.
      */
     setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
+    /**
+     * Attempt exactly one workspace observation for a compaction (spec
+     * 2026-09-01-harness-correctness-and-workspace-state.md § 3 step 1).
+     * Returns undefined when observation is impossible; never throws and
+     * never fails the surrounding compaction.
+     */
+    _captureWorkspaceObservation(signal: AbortSignal | undefined): Promise<WorkspaceStateRecord | undefined>;
+    /** Session/artifact directories inside the workspace, relative paths. */
+    private _sessionExclusionPaths;
+    /**
+     * Build (once) and refresh the tracker from the raw per-source policy
+     * settings. ADR 0028: the loader consumes the sources separately and the
+     * trust gate decides whether the project source exists at all.
+     */
+    /**
+     * PS.1. Configured commands reach the same permission authority tool calls
+     * use. Undefined only when the session has no gate at all, which is the
+     * documented SDK default; a gated session always authorizes.
+     */
+    private _authorizeConfiguredCommand;
+    private _ensureVerificationTracker;
+    /**
+     * Run one configured verification policy now and report the resulting
+     * completion status. Unavailable when nothing is configured; the
+     * workspace observation after the run becomes the staleness baseline.
+     */
+    requestVerification(options?: {
+        policyId?: string;
+        signal?: AbortSignal;
+    }): Promise<VerificationCompletionStatus>;
+    /**
+     * VF.5: run one configured formatter policy now and report what it
+     * actually mutated. Undefined when no formatter policy matches. Any real
+     * mutation retires a prior verification record: the workspace the
+     * verification described no longer exists.
+     */
+    runConfiguredFormatter(options?: {
+        policyId?: string;
+        signal?: AbortSignal;
+    }): Promise<FormatterRunOutcome | undefined>;
+    /** The current completion status: verified, failed, unavailable, interrupted, or continued-unverified. */
+    verificationStatus(): VerificationCompletionStatus;
+    /** The live verification record with its bounded evidence, if any. */
+    verificationRecord(): VerificationRecord | undefined;
+    /** Record that the user chose to finish without verification. */
+    continueWithoutVerification(): void;
+    private _runVerificationTurnBoundary;
+    private _runWorkspaceComparisonBoundary;
+    private _runDefaultCompaction;
     /**
      * Manually compact the session context.
-     * Aborts current agent operation first.
+     *
+     * This is the manual entry point used by `/compact`, RPC, and extensions. It is
+     * separate from automatic threshold/overflow compaction, which enters through
+     * `_checkCompaction()` and `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * Aborts the current agent operation first. Manual compaction never retries or
+     * continues the interrupted agent turn.
+     *
      * @param customInstructions Optional instructions for the compaction summary
      */
     compact(customInstructions?: string): Promise<CompactionResult>;
@@ -682,12 +853,9 @@ export declare class AgentSession {
         customInstructions?: string;
         replaceInstructions?: boolean;
         label?: string;
-    }): Promise<{
-        editorText?: string;
-        cancelled: boolean;
-        aborted?: boolean;
-        summaryEntry?: BranchSummaryEntry;
-    }>;
+        workspacePolicy?: TreeWorkspacePolicy;
+    }): Promise<TreeNavigationResult>;
+    private _resolveTreeWorkspaceStep;
     /**
      * Get all user messages from session for fork selector.
      */