@ai-agent-forge/agent-forge 0.85.0

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

@@ -0,0 +1,1156 @@
+/**
+ * AgentSession - Core abstraction for agent lifecycle and session management.
+ *
+ * This class is shared between all run modes (interactive, print, rpc).
+ * It encapsulates:
+ * - Agent state access
+ * - Event subscription with automatic session persistence
+ * - Model and thinking level management
+ * - Compaction (manual and auto)
+ * - Bash execution
+ * - Session switching and branching
+ *
+ * Modes use this class and add their own I/O layer on top.
+ */
+import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@agent-forge/agent-core";
+import type { Api, Transport } from "@agent-forge/ai";
+import type { ImageContent, Model, TextContent } from "@agent-forge/ai/compat";
+import type { MemoryStorageComponentsV1 } from "@agent-forge/plugin-sdk";
+import type { DurableServiceV1 } from "../durable/durable-service.ts";
+import type { SummaryAttemptRecordV1 } from "../host/summary-retry.ts";
+import type { ObservabilityPlugin } from "../plugins/observability-types.ts";
+import { type CompactionCancelledResult } from "./agent-session-compaction.ts";
+import type { ReplacedSessionContext } from "./agent-session-runtime.ts";
+import type { BashResult } from "./bash-executor.ts";
+import type { CompactionResult } from "./compaction/index.ts";
+import type { AgentTaskSettledEventDataV1 } from "./extensions/bootstrap-lifecycle.ts";
+import type { TraceServiceV1 } from "./extensions/capability-runtime-types.ts";
+import { type AgentCompositionAPI, type AgentTaskAdapter, type AgentTaskSessionSummaryV1, type AgentTaskSessionViewV1, type CapabilityCommandResult, type CapabilityPluginFactory, type CapabilityPluginHandle, type CapabilityRuntime, type HostMode, type InteractionHostV1, type LoggerRecord, type OutputArtifactRef, type PluginManifest, type PromptOutcome, type SessionAPI, type SessionRevisionV1 } from "./extensions/index.ts";
+import type { ContextUsage, PluginConfig, SubagentCommunicationWiringV1 } from "./extensions/public-api.ts";
+import type { InputSource } from "./input-source.ts";
+import type { HostLogger } from "./logger.ts";
+import type { CustomMessage } from "./messages.ts";
+import type { ModelRuntime } from "./model-runtime.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 { SessionStartMetadata } from "./session-start.ts";
+import type { SettingsManager } from "./settings-manager.ts";
+import type { Skill } from "./skills.ts";
+import type { BashOperations } from "./tools/bash.ts";
+import type { ToolDefinition, ToolInfo } from "./tools/tool-definition.ts";
+/** 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;
+/**
+ * Custom entry type marking a cross-suite resume (设计 §10.1 最小可用版): the
+ * session was created under one suite but its context was reassembled under
+ * another. Entry data: `{ originalSuiteId, currentSuiteId }`.
+ */
+export declare const SUITE_MISMATCH_SESSION_ENTRY_TYPE = "suite_mismatch";
+/** Session-specific events that extend the core AgentEvent */
+export type AgentSessionEvent = Exclude<AgentEvent, {
+    type: "agent_end";
+}> | {
+    type: "agent_end";
+    messages: AgentMessage[];
+    willRetry: boolean;
+} | {
+    type: "agent_settled";
+} | {
+    type: "queue_update";
+    steering: readonly string[];
+    followUp: readonly string[];
+} | {
+    type: "compaction_start";
+    reason: "manual" | "threshold" | "overflow";
+} | {
+    type: "entry_appended";
+    entry: SessionEntry;
+} | {
+    type: "session_info_changed";
+    name: string | undefined;
+} | {
+    type: "thinking_level_changed";
+    level: ThinkingLevel;
+} | {
+    type: "compaction_end";
+    reason: "manual" | "threshold" | "overflow";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+} | {
+    type: "summarization_retry_scheduled";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "summarization_retry_attempt_start";
+    source: "branchSummary";
+} | {
+    type: "summarization_retry_attempt_start";
+    source: "compaction";
+    reason: "manual" | "threshold" | "overflow";
+} | {
+    type: "summarization_retry_finished";
+    source: {
+        source: "branchSummary";
+    } | {
+        source: "compaction";
+        reason: "manual" | "threshold" | "overflow";
+    };
+    attempts: readonly SummaryAttemptRecordV1[];
+} | {
+    type: "bash_execution_update";
+    id?: string;
+    delta: string;
+} | CapabilityCommandResultEvent;
+/** Result returned by a capability command, rendered by each host without TUI coupling. */
+export type CapabilityCommandResultEvent = {
+    type: "capability_command_result";
+    command: string;
+    source: string;
+    result: CapabilityCommandResult;
+};
+/** Listener function for agent session events */
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+/**
+ * Listener for each output artifact committed through this session's capability
+ * runtime. Host adapters mirror the payload into durable storage; the runtime
+ * itself stays storage-agnostic. `bytes` is the live buffer shared with the
+ * in-memory artifact store: listeners must treat it as read-only.
+ */
+export type OutputArtifactCommitListener = (artifact: {
+    readonly ref: OutputArtifactRef;
+    readonly bytes: Uint8Array;
+}) => void;
+/**
+ * Why a turn was aborted (adapted from codex's TurnAbortReason,
+ * protocol.rs:4173): "interrupted" is host/user intent, "replaced" is session
+ * teardown/reload. codex's "budget_limited" is deliberately omitted — turn
+ * budgets cap what the agent can do, so Agent Forge does not carry the concept.
+ */
+export type TurnAbortReason = "interrupted" | "replaced";
+export interface AgentSessionConfig {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settingsManager: SettingsManager;
+    cwd: string;
+    /** Models to cycle through with Ctrl+P (from --models flag) */
+    scopedModels?: Array<{
+        model: Model<Api>;
+        thinkingLevel?: ThinkingLevel;
+    }>;
+    /** Resource loader for extensions, skills, prompts, themes, context files, and system prompt */
+    resourceLoader: ResourceLoader;
+    /** SDK custom tools registered outside extensions */
+    customTools?: ToolDefinition[];
+    /** Canonical model/auth runtime used by coding-agent internals. */
+    modelRuntime: ModelRuntime;
+    /** Initial active built-in tool names. Default: [read, bash, edit, write] */
+    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[];
+    /**
+     * Plugin ids whose tools register normally but stay out of the default
+     * active (prompt-visible) set; the built-in tool_search tool discovers and
+     * activates them on demand. Explicit activation (allowlist, SDK, or
+     * setActiveTools) overrides the deferral.
+     */
+    deferredToolPluginIds?: readonly string[];
+    /**
+     * 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>;
+    /**
+     * Bootstrap plugin ids to SKIP at session construction (宪法 §1: bootstrap
+     * 插件可禁用）。Id values are the exported BOOTSTRAP_*_PLUGIN_ID constants
+     * ("agent-forge.bootstrap-tools" etc.). A disabled bootstrap plugin leaves
+     * its surface absent — visible via plugin rejections/diagnostics, never a
+     * silent kernel downgrade.
+     */
+    disabledBootstrapPlugins?: readonly string[];
+    /** Session start metadata dispatched to the capability lifecycle on session start. */
+    sessionStartEvent?: SessionStartMetadata;
+    /** Core capability mode; defaults to full-control for compatibility. */
+    capabilityMode?: HostMode;
+    /** Optional external context strategy name. Missing registrations fail at request time. */
+    contextStrategyName?: string;
+    /** Optional retry policy supplied by a capability plugin. Missing registrations fail when a retry is evaluated. */
+    retryPolicyName?: string;
+    /** Optional automatic compaction policy supplied by a capability plugin. */
+    compactionPolicyName?: string;
+    /** Optional provider overflow policy supplied by a capability plugin. */
+    overflowPolicyName?: string;
+    /** Optional branch summary policy supplied by a capability plugin. */
+    branchSummaryPolicyName?: string;
+    /**
+     * Optional post-run continuation strategy supplied by a capability plugin.
+     * Missing registrations fall back to the default continuation behavior.
+     */
+    runLoopStrategyName?: string;
+    /** Host adapter for isolated child agent tasks. Omitted hosts do not expose the agents capability. */
+    agentTaskAdapter?: AgentTaskAdapter;
+    /**
+     * Durable replay channel for agent task terminal outcomes (agent-result-replay-v1).
+     * Only meaningful alongside `agentTaskAdapter` (the replay feature requires the
+     * agents capability); stored on the instance so runtime rebuilds (reload) keep
+     * the wiring. The host owns the writer claim lifecycle.
+     */
+    agentTaskResults?: {
+        readonly store: DurableServiceV1;
+        readonly writerId: string;
+    };
+    /**
+     * Bounded read-only reader for persisted subagent session transcripts (D-060 S3).
+     * Only meaningful alongside `agentTaskAdapter`; the host enforces scoping (a
+     * session may only read transcripts whose parent is itself) by returning
+     * undefined for anything out of scope.
+     */
+    agentSessionReader?: (sessionId: string) => Promise<AgentTaskSessionViewV1 | undefined>;
+    /**
+     * Lister for this session's own subagent session summaries, newest first
+     * (D-060 model-face inventory). Only meaningful alongside `agentTaskAdapter`;
+     * the host scopes it to this session's children.
+     */
+    agentSessionLister?: () => Promise<AgentTaskSessionSummaryV1[]>;
+    /** Host adapter for the versioned AgentDefinition/AgentInstance facade. */
+    agentComposition?: AgentCompositionAPI;
+    /** Host adapter for cancellable interaction tasks. Omitted hosts do not expose the interaction capability. */
+    interactionHost?: InteractionHostV1;
+    /**
+     * Session-nature orientation text (suite persona, 设计 §6.2). Kept on the
+     * session so every system prompt rebuild (tool-set changes, extension
+     * resource refreshes) re-injects it.
+     */
+    orientationPrompt?: string;
+    /**
+     * Optional durable preference card injected right after the persona on
+     * every system prompt rebuild (kept on the session like
+     * {@link orientationPrompt}). The first-party memory plugin stopped using
+     * this channel when it moved into its own package (D-075 S4 fourth batch —
+     * its assistant card now rides the transformContext loop hook); the field
+     * stays a generic host-assembly face for embedders with their own card.
+     */
+    preferenceCard?: string;
+    /**
+     * Optional filter applied to the legacy capability-plugin skill surface
+     * (`runtime.listSkills()`) after duplicate-name exclusion. Default:
+     * identity (no filtering). The suite assembler wires filterSuiteSkills
+     * here; the session itself stays suite-unaware.
+     */
+    capabilitySkillsFilter?: (skills: Skill[]) => Skill[];
+    /**
+     * 宿主进程日志器（设计 §5）：注入后插件日志镜像、内建能力装载失败等会话级
+     * 事实落进程日志；缺省 = 宿主显式关闭进程日志（显式契约，非默认降级），
+     * 所有依赖它的打点为 no-op。
+     */
+    hostLogger?: HostLogger;
+    /**
+     * 插件日志镜像共享 ref（会话轨迹 plugin.log，设计 §7.2）：装配域 observability
+     * 插件工厂创建时写入镜像门面方法、插件 dispose 时置空；runtime 日志 sink 在
+     * 每条插件日志上先经它镜像进轨迹，再按级别落 hostLogger。
+     * 装配域写入、会话生命周期持有的可变共享 ref；空 = 无镜像（no-op）。
+     */
+    logRecordMirrorRef?: {
+        current?: (record: LoggerRecord) => void;
+    };
+    /**
+     * /metrics 命令的数据源共享 ref（observability 插件工厂创建时写入
+     * plugin.getMetrics、dispose 时置空；宿主装配完成后读取接进命令 options）。
+     * 空 = 插件未挂载（/metrics 显示未装配警告）。
+     */
+    observabilityGetMetricsRef?: {
+        current?: ObservabilityPlugin["getMetrics"];
+    };
+    /**
+     * Host agent directory (D-075 S4 second batch): surfaced to capability
+     * plugins as `api.host.agentDir` so disk-state plugins (e.g. the
+     * session-share config channel) can locate `<agentDir>/capabilities/`
+     * files. Absent on hosts without an agent dir.
+     */
+    agentDir?: string;
+    /**
+     * Subagent communication wiring (D-075 S4 third batch): surfaced to
+     * capability plugins as `api.host.communication`. The parent assembly
+     * injects `drainEscalations`; child (leaf) assemblies receive the
+     * post/drainInbox closures with the child identity bound by the parent
+     * scope. Absent = the delegation plugins stay default-off (D-060 S4).
+     */
+    communication?: SubagentCommunicationWiringV1;
+    /**
+     * Turn-scoped host context (D-075 S4 third batch): surfaced to capability
+     * plugins as `api.host.turnContext`. `backgroundDigestSink` receives the
+     * bounded JSON digest line of each settled background delegation;
+     * `getTurnCorrelationId` returns the parent turn's correlation id at
+     * submission time. Absent = no push notification or turn-lineage
+     * attribution for background delegations.
+     */
+    turnContext?: {
+        backgroundDigestSink?: (line: string) => void;
+        getTurnCorrelationId?: () => string | undefined;
+    };
+    /**
+     * Role ids associated with the active suite (D-075 S4 third batch):
+     * surfaced to capability plugins as `api.host.roleAssociations`. Role
+     * definitions are disk-only (`<agentDir>/roles/<id>.json`); only
+     * associated ids surface in the delegation tool menu. Absent = no roles.
+     */
+    roleAssociations?: readonly string[];
+    /**
+     * Memory storage components (D-075 S4 fourth batch): surfaced to capability
+     * plugins as `api.host.memoryStorage`. The first-party memory plugin binds
+     * the injected store/ledger factories and vector components in place of
+     * its built-in defaults. Absent = the plugin runs its own local
+     * implementation.
+     */
+    memoryStorage?: MemoryStorageComponentsV1;
+    /**
+     * Host trace service (D-075 S4 second batch): injected into the capability
+     * runtime as `api.trace`/`api.traceSinkOptions` so the installed
+     * observability package binds its trace sink; absent = plugins stay
+     * trace-free.
+     */
+    traceService?: TraceServiceV1;
+}
+/** Options for AgentSession.prompt() */
+export interface PromptOptions {
+    /** Whether to dispatch extension commands and expand skill commands and prompt templates (default: true) */
+    expandPromptTemplates?: 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 the input, reported in the input.received lifecycle facts. Defaults to "interactive". */
+    source?: InputSource;
+    /** 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<Api>;
+    thinkingLevel: ThinkingLevel;
+    /** Whether cycling through scoped models (--models flag) or all available */
+    isScoped: boolean;
+}
+/** Session statistics for /session command */
+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;
+}
+/**
+ * Core session orchestration adapter.
+ *
+ * The stable facade `CodingAgentFacadeV1` (docs/design/稳定门面统一入口设计.md)
+ * is the only supported consumption surface for product hosts. Direct
+ * consumption of this class is limited to registered carve-outs
+ * (tui-private-path-contract.test.ts allowlists and the §2.7/§2.9 deferred
+ * registrations in the design doc).
+ *
+ * @internal
+ */
+export declare class AgentSession {
+    readonly agent: Agent;
+    readonly sessionManager: SessionManager;
+    readonly settingsManager: SettingsManager;
+    private _scopedModels;
+    private _unsubscribeAgent?;
+    private _eventListeners;
+    private _isAgentRunActive;
+    private _idleWaitPromise;
+    private _resolveIdleWait;
+    /** Tracks pending steering messages for UI display. Removed when delivered. */
+    private _steeringMessages;
+    /** Tracks pending follow-up messages for UI display. Removed when delivered. */
+    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;
+    /** Serializes manual and automatic compaction, including their projections. */
+    private _compactionQueue;
+    private _compactionAbortController;
+    private _autoCompactionAbortController;
+    private _overflowRecoveryAttempted;
+    private _branchSummaryAbortController;
+    private _branchSummaryPromise;
+    private _resolveBranchSummaryPromise;
+    private _retryAbortController;
+    /** Cancellation boundary for retry/overflow policy decisions in the active agent loop. */
+    private _policyDecisionAbortController;
+    private _retryAttempt;
+    /** Cancellation signal for the capability command currently executing through prompt(). */
+    private _commandAbortController;
+    /**
+     * Parent-session cancel fence for agent tasks (D-044 §4.2). Consumed once
+     * per task creation through the runtime's `parentSignal` getter; replaced
+     * after every abort/runtime rebuild so later tasks bind to a fresh signal.
+     */
+    private _agentTaskScopeAbortController;
+    private _activeCapabilityCommand;
+    private _activeCompactionPromise;
+    /** Prevents new mutable work from entering while the session is being replaced. */
+    private _reloadInProgress;
+    /** Monotonic committed reload generation, distinct from disposal and bash fences. */
+    private _reloadGeneration;
+    /** Generation fence for context projections that may outlive a runtime replacement. */
+    private _contextEpoch;
+    private _contextTransitionAbortController;
+    /** Serializes context transitions and lets reload/dispose drain them before teardown. */
+    private _activeContextTransition;
+    /** Monotonic revision for the public context snapshot/commit facade. */
+    private _contextRevision;
+    /** Serializes public context commits so expectedRevision is a real CAS fence. */
+    private _contextCommitQueue;
+    private readonly _bashAbortControllers;
+    /** Whole bash operations, including their final session-history write. */
+    private readonly _activeBashPromises;
+    /** Fences mode-level bash results captured before a runtime replacement. */
+    private _bashEpoch;
+    private _pendingBashMessages;
+    private _turnIndex;
+    private _resourceLoader;
+    private _customTools;
+    private _deferredToolPluginIds;
+    /** Abort reason supplied to the in-flight abort(); consumed by the interruption marker. */
+    private _pendingAbortReason;
+    /** Set when the in-flight prompt run produced an aborted terminal assistant turn. */
+    private _currentRunAborted;
+    /** Most recent abort reason; persists after abort() returns so prompt() can report it. */
+    private _lastAbortReason;
+    private _baseToolDefinitions;
+    private _baseToolSources;
+    private _capabilityRuntime?;
+    /** Output-artifact commit listeners registered through {@link onOutputArtifactCommit}. */
+    private readonly _outputArtifactCommitListeners;
+    /**
+     * Stable commit dispatcher handed to every CapabilityRuntime this session
+     * builds; listeners registered on the session survive runtime rebuilds.
+     */
+    private readonly _dispatchOutputArtifactCommit;
+    private _bootstrapToolsHandle?;
+    private _bootstrapSkillsHandle?;
+    private _bootstrapRetryHandle?;
+    private _bootstrapCompactionHandle?;
+    private _bootstrapBranchSummaryHandle?;
+    private _bootstrapOverflowHandle?;
+    private _bootstrapAgentLoopHandle?;
+    private _bootstrapLifecycleHandle?;
+    private _capabilityPlugins;
+    private _inlineCapabilityPlugins;
+    private _isDisposingCapabilityPlugins;
+    /**
+     * 工具表变更钩子的两道门（见 _buildRuntime 的 onToolRegistryChange）：
+     * - `_toolRegistryHookReady`：构造期门。_buildRuntime 求值阶段 bootstrap 插件
+     *   注册即触发 notify，而此时内部状态未就绪（观察回调会抛），构造完成后既有
+     *   边界（_buildRuntime 尾部的显式 sync + refresh）已兜底，跳过不丢状态。
+     * - `_suspendToolRegistryHookRefresh`：插件卸载恢复链的中间态挂起位。恢复过程
+     *   会先删新注册、后恢复被替换者，中间 notify 的工具表是暂态（活跃名暂时缺
+     *   席）；该窗口内刷新会把缺席名从活动集永久剔除。装卸边界在 dispose 完成后
+     *   自行兜底刷新。
+     */
+    private _suspendToolRegistryHookRefresh;
+    private _toolRegistryHookReady;
+    private _disposePromise?;
+    private _cwd;
+    private _initialActiveToolNames?;
+    private _allowedToolNames?;
+    private _excludedToolNames?;
+    private _baseToolsOverride?;
+    private _disabledBootstrapPlugins?;
+    private _sessionStartEvent;
+    private _capabilityMode;
+    private _contextStrategyName?;
+    private _retryPolicyName;
+    private _compactionPolicyName;
+    private _branchSummaryPolicyName;
+    private _overflowPolicyName;
+    /** Post-run continuation strategy name; missing registrations fall back to the host candidate. */
+    private _runLoopStrategyName;
+    /**
+     * Internal loop-executor seam (D-043 G3); no public config, distinct from
+     * runLoopStrategyName (a per-continuation veto policy).
+     */
+    private _loopExecutor;
+    /** The agent's construction-time prepare adapter, captured once by the loop wiring. */
+    private _initialPrepareNextTurn?;
+    private _agentTaskAdapter?;
+    private _agentTaskResults?;
+    private _agentSessionReader?;
+    private _agentSessionLister?;
+    private _agentComposition?;
+    private _interactionHost?;
+    private _modelRuntime;
+    private _modelStreamCounter;
+    private _modelStreamState;
+    /** Correlation id shared by every in-turn lifecycle dispatch of the active prompt run. */
+    private _turnCorrelationId;
+    private _turnCorrelationCounter;
+    private _toolRegistry;
+    private _toolDefinitions;
+    private _toolPromptSnippets;
+    private _toolPromptGuidelines;
+    private _baseSystemPrompt;
+    private _baseSystemPromptOptions;
+    private _systemPromptOverride?;
+    private _orientationPrompt?;
+    private _preferenceCard?;
+    private _capabilitySkillsFilter?;
+    private _hostLogger?;
+    private _logRecordMirrorRef?;
+    private _observabilityGetMetricsRef?;
+    private _agentDir?;
+    private _communication?;
+    private _turnContext?;
+    private _roleAssociations?;
+    private _memoryStorage?;
+    private _traceService?;
+    constructor(config: AgentSessionConfig);
+    /**
+     * 当前回合的 correlation id（会话轨迹设计 §4.2）：活跃 prompt 回合内所有
+     * lifecycle 信封携带的同一 correlationId（与信封同源：loop-runner 在回合
+     * 开始写入 `_turnCorrelationId`、回合结束清除）；空闲时为 undefined。只读
+     * 事实，供宿主适配器做回合级关联（如 observability 的 llm.request traceId）。
+     */
+    getTurnCorrelationId(): string | undefined;
+    /**
+     * 宿主 digest sink 面（第 4 期轨迹闭合）：把一条后台委派结算行投递为
+     * agent.task.settled@1（父会话 sessionId 由派发助手补）。派发是非致命
+     * fire-and-forget；dispose 后 runtime 已 revoke，助手 no-op。
+     */
+    dispatchAgentTaskSettled(facts: {
+        taskSessionId: string;
+        taskId: string;
+        status: AgentTaskSettledEventDataV1["status"];
+        reasonCode?: string;
+    }): void;
+    get modelRuntime(): ModelRuntime;
+    /** Internal facade passed to the agent-session-* submodule functions. */
+    private get _internal();
+    /**
+     * Wire the default main loop onto the Agent instance.
+     *
+     * The four hook positions are composed from the runtime's loop-hook chains.
+     * Chains are read at execution time, so extension reload swaps in the new
+     * runtime without reinstalling the wiring. The legacy extension gate and the
+     * agent's construction-time context transform stay as chain heads (host
+     * wiring, not plugin capabilities); the default links come from the
+     * bootstrap agent-loop plugin and third-party links chain after them in
+     * registration order.
+     */
+    private _wireDefaultLoop;
+    /** Session-bound host state the default loop links read at execution time. */
+    private _createLoopWiring;
+    private _compactBeforeNextAssistantResponse;
+    /** Emit an event to all listeners */
+    private _emit;
+    private _emitQueueUpdate;
+    private _getIdleWaitPromise;
+    private _resolveIdleWaitIfIdle;
+    private _emitAgentSettled;
+    private _lastAssistantMessage;
+    private _pendingRetryDecision;
+    /** Internal handler for agent events - shared by subscribe and reconnect */
+    private _handleAgentEvent;
+    private _dispatchModelStreamLifecycle;
+    private _willRetryAfterAgentEnd;
+    /** Find the last assistant message in agent state (including aborted ones) */
+    private _findLastAssistantMessage;
+    private _emitLifecycleEvents;
+    /**
+     * Subscribe to agent events.
+     * Session persistence is handled internally (saves messages on message_end).
+     * Multiple listeners can be added. Returns unsubscribe function for this listener.
+     */
+    subscribe(listener: AgentSessionEventListener): () => void;
+    /** Disconnect from agent events during disposal. */
+    private _disconnectFromAgent;
+    /**
+     * Remove all listeners and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose(): Promise<void>;
+    /** Full agent state */
+    get state(): AgentState;
+    /** Current model (may be undefined if not yet selected) */
+    get model(): Model<Api> | undefined;
+    /** Current thinking level */
+    get thinkingLevel(): ThinkingLevel;
+    /** Whether the session is currently processing an agent run or post-run continuation. */
+    get isStreaming(): boolean;
+    /** Whether the session has no active agent run, retry, compaction, branch summarization, or queued continuation. */
+    get isIdle(): boolean;
+    /** Current effective system prompt (includes any per-turn extension modifications) */
+    get systemPrompt(): string;
+    /** Current retry attempt (0 if not retrying) */
+    get retryAttempt(): number;
+    /**
+     * Get the names of currently active tools.
+     * Returns the names of tools currently set on the agent.
+     */
+    getActiveToolNames(): string[];
+    /** Public capability runtime for external orchestration and plugin composition. */
+    getCapabilityRuntime(): CapabilityRuntime;
+    /**
+     * Observes every output artifact committed through this session's capability
+     * runtime. Host adapters mirror the payload into durable storage; the runtime
+     * itself carries no durable dependency. The registration survives runtime
+     * rebuilds (reload) because the session owns the dispatcher. Returns an
+     * unsubscribe function.
+     */
+    onOutputArtifactCommit(listener: OutputArtifactCommitListener): () => void;
+    get isDisposed(): boolean;
+    /** Public session facade for host adapters. It never exposes SessionManager internals. */
+    getSessionAPI(): SessionAPI;
+    /** Return all currently loaded capability plugins without exposing private session state. */
+    getCapabilityPlugins(): readonly CapabilityPluginHandle[];
+    /** Name of the externally selected context strategy, when configured. */
+    get contextStrategyName(): string | undefined;
+    private _requireContextStrategy;
+    private _requireIdleContextOperation;
+    private _beginContextTransitionFence;
+    private _isContextTransitionCurrent;
+    private _assertContextTransitionCurrent;
+    private _enqueueContextTransition;
+    private _copyContextMessages;
+    private _applyContextTransition;
+    private _dispatchContextReplacedLifecycle;
+    private _dispatchModelResponseLifecycle;
+    private _dispatchToolCommitLifecycle;
+    private _dispatchToolResultLifecycle;
+    private _dispatchSessionReloadLifecycle;
+    /** Snapshot the current session messages with the configured context strategy. */
+    snapshotContext(): Promise<unknown>;
+    /** Restore session messages from a strategy snapshot. */
+    restoreContext(snapshot: unknown): Promise<AgentMessage[]>;
+    /** Replace session messages through the configured context strategy. */
+    replaceContext(context: AgentMessage[]): Promise<AgentMessage[]>;
+    private _restoreContextTransition;
+    private _trackCapabilityPlugin;
+    /** Load an external capability manifest through the same runtime as first-party plugins. */
+    loadCapabilityPluginManifest(manifestPath: string, options?: {
+        readonly configOverride?: PluginConfig;
+    }): Promise<CapabilityPluginHandle>;
+    /**
+     * Load an in-memory capability plugin and attach its handle to this session.
+     * This is useful for embedders and deterministic fixtures that already own a
+     * validated manifest/factory pair; reload and dispose will release the handle.
+     */
+    loadCapabilityPlugin(manifest: PluginManifest, factory: CapabilityPluginFactory): Promise<CapabilityPluginHandle>;
+    /**
+     * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
+     */
+    getAllTools(): ToolInfo[];
+    getToolDefinition(name: string): ToolDefinition | undefined;
+    /**
+     * Set active tools by name.
+     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Also rebuilds the system prompt to reflect the new tool set.
+     * Changes take effect on the next agent turn.
+     */
+    setActiveToolsByName(toolNames: string[]): void;
+    /** Whether compaction or branch summarization is currently running */
+    get isCompacting(): boolean;
+    /** All messages including custom types like BashExecutionMessage */
+    get messages(): AgentMessage[];
+    /** Current steering mode */
+    get steeringMode(): "all" | "one-at-a-time";
+    /** Current follow-up mode */
+    get followUpMode(): "all" | "one-at-a-time";
+    /** Current session file path, or undefined if sessions are disabled */
+    get sessionFile(): string | undefined;
+    /** Current session ID */
+    get sessionId(): string;
+    /**
+     * /metrics 数据源共享 ref（config 原样透出；observability 插件工厂挂载时写入
+     * plugin.getMetrics、dispose 时置空）。宿主（TUI/RPC）经它惰性解引用接进
+     * 命令 options——空 = 插件未挂载。
+     */
+    get observabilityGetMetricsRef(): {
+        current?: ObservabilityPlugin["getMetrics"];
+    } | undefined;
+    /** Current session display name, if set */
+    get sessionName(): string | undefined;
+    /** Durable revision host fact (SessionManager entry sequence) for session boundaries. */
+    getRevision(): SessionRevisionV1;
+    /** Scoped models for cycling (from --models flag) */
+    get scopedModels(): ReadonlyArray<{
+        model: Model<Api>;
+        thinkingLevel?: ThinkingLevel;
+    }>;
+    /** Update scoped models for cycling */
+    setScopedModels(scopedModels: Array<{
+        model: Model<Api>;
+        thinkingLevel?: ThinkingLevel;
+    }>): void;
+    /** File-based prompt templates */
+    get promptTemplates(): ReadonlyArray<PromptTemplate>;
+    private _normalizePromptSnippet;
+    private _normalizePromptGuidelines;
+    private _rebuildSystemPrompt;
+    private _runAgentPrompt;
+    private _handlePostAgentRun;
+    private _runInputHandlers;
+    /**
+     * Send a prompt to the agent.
+     * - Handles legacy and capability plugin commands immediately, even during streaming
+     * - Expands file-based prompt templates by default
+     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - Validates model and API key before sending (when not streaming)
+     * @throws Error if streaming and no streamingBehavior specified
+     * @throws Error if no model selected or no API key available (when not streaming)
+     */
+    prompt(text: string, options?: PromptOptions): Promise<PromptOutcome>;
+    private _tryExecuteExtensionCommand;
+    /**
+     * Expand skill commands (/skill:name args) to their full content.
+     * Returns the expanded text, or the original text if not a skill command or skill not found.
+     * Emits errors via extension runner if file read fails.
+     */
+    private _expandSkillCommand;
+    private _queueUserInput;
+    /**
+     * Queue a steering message while the agent is running.
+     * Delivered after the current assistant turn finishes executing its tool calls,
+     * before the next LLM call.
+     * Expands skill commands and prompt templates. Errors on extension commands.
+     * @param images Optional image attachments to include with the message
+     * @param options Input source; defaults to interactive
+     * @throws Error if text is an extension command
+     */
+    steer(text: string, images?: ImageContent[], options?: {
+        source?: InputSource;
+    }): Promise<void>;
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     * Delivered only when agent has no more tool calls or steering messages.
+     * Expands skill commands and prompt templates. Errors on extension commands.
+     * @param images Optional image attachments to include with the message
+     * @param options Input source; defaults to interactive
+     * @throws Error if text is an extension command
+     */
+    followUp(text: string, images?: ImageContent[], options?: {
+        source?: InputSource;
+    }): Promise<void>;
+    private _queueSteer;
+    private _queueFollowUp;
+    /**
+     * Send a custom message to the session. Creates a CustomMessageEntry.
+     *
+     * 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
+     *
+     * @param message Custom message with customType, content, display, details
+     * @param options.triggerTurn If true and not streaming, triggers a new LLM turn
+     * @param options.deliverAs Delivery mode: "steer", "followUp", or "nextTurn"
+     */
+    sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
+        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.
+     *
+     * @param content User message content (string or content array)
+     * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     * @param options.expandPromptTemplates Whether to dispatch extension commands and expand skill commands and prompt templates. Default: false.
+     */
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
+        deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
+    }): Promise<void>;
+    /**
+     * Clear all queued messages and return them.
+     * Useful for restoring to editor when user aborts.
+     * @returns Object with steering and followUp arrays
+     */
+    clearQueue(): {
+        steering: string[];
+        followUp: string[];
+    };
+    /** Number of pending messages (includes both steering and follow-up) */
+    get pendingMessageCount(): number;
+    /** Get pending steering messages (read-only) */
+    getSteeringMessages(): readonly string[];
+    /** Get pending follow-up messages (read-only) */
+    getFollowUpMessages(): readonly string[];
+    get resourceLoader(): ResourceLoader;
+    /**
+     * Why the active turn was aborted, following codex's TurnAbortReason
+     * (protocol.rs:4173). The interruption marker's visible text stays fixed;
+     * the reason rides the marker `details` for hosts and plugins.
+     */
+    abort(reason?: TurnAbortReason): Promise<void>;
+    /**
+     * Abort without the interruption marker; used by internal flows (compaction,
+     * teardown) that abort for their own bookkeeping. Takes no reason: the abort
+     * reason only exists where the marker is written.
+     */
+    _abortInternal(): Promise<void>;
+    /**
+     * Append a model-visible marker after an abort that actually cut a turn
+     * short. transform-messages drops the aborted assistant message on replay,
+     * so without this marker the model has no way to learn that the
+     * interruption happened. Tool calls skipped mid-batch already carry their
+     * own persisted error results; this covers the streaming-interrupt case.
+     * The text is intentionally fixed (codex keeps INTERRUPTED_GUIDANCE stable
+     * across reasons); the abort reason rides `details` for host consumers.
+     */
+    private _appendTurnInterruptedMarker;
+    private _abortActiveCapabilityCommand;
+    private _cancelAndDrainForReload;
+    waitForIdle(): Promise<void>;
+    private _emitModelSelect;
+    /**
+     * Set model directly.
+     * 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<Api>, 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", options?: ModelMutationOptions): Promise<ModelCycleResult | undefined>;
+    private _cycleScopedModel;
+    private _cycleAvailableModel;
+    /**
+     * Set thinking level.
+     * Clamps to model capabilities based on available thinking levels.
+     * 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, options?: ModelMutationOptions): void;
+    /**
+     * Cycle to next thinking level.
+     * @returns New level, or undefined if model doesn't support thinking
+     */
+    cycleThinkingLevel(options?: ModelMutationOptions): ThinkingLevel | undefined;
+    /**
+     * Get available thinking levels for current model.
+     * The provider will clamp to what the specific model supports internally.
+     */
+    getAvailableThinkingLevels(): ThinkingLevel[];
+    /**
+     * Check if current model supports thinking/reasoning.
+     */
+    supportsThinking(): boolean;
+    private _getThinkingLevelForModelSwitch;
+    private _clampThinkingLevel;
+    private syncQueueModesFromSettings;
+    /**
+     * Set steering message mode.
+     * Saves to settings.
+     */
+    setSteeringMode(mode: "all" | "one-at-a-time"): void;
+    /**
+     * Set follow-up message mode.
+     * Saves to settings.
+     */
+    setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    /** Queue compaction work so canonical commit and runtime projection stay ordered. */
+    private _enqueueCompaction;
+    private _observeLifecycleDeliveryError;
+    /**
+     * Manually compact the session context.
+     *
+     * 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 use the selected compaction policy
+     * unless the hook cancels or supplies a custom result, then commit the result
+     * against the revision captured for that branch.
+     *
+     * 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 | CompactionCancelledResult>;
+    private _compactInternal;
+    /**
+     * Cancel in-progress compaction (manual or auto).
+     */
+    abortCompaction(): void;
+    /**
+     * Cancel in-progress branch summarization.
+     */
+    abortBranchSummary(): void;
+    /**
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
+     *
+     * Automatic cases:
+     * 1. Overflow with retry: a context-overflow error or recoverable length stop;
+     *    remove the failed assistant message, compact, and retry the turn once.
+     * 2. Overflow without retry: a successful response exceeded the configured
+     *    context window; compact but preserve the completed response.
+     * 3. Threshold without retry: valid or estimated context usage crossed the
+     *    configured threshold; compact without retrying the completed response.
+     *
+     * Each case calls `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, that method calls the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
+     */
+    private _checkCompaction;
+    /**
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths use the selected compaction
+     * policy after preparation and extension interception, then commit against the
+     * branch revision captured before asynchronous work.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
+     */
+    private _runAutoCompaction;
+    /**
+     * Toggle auto-compaction setting.
+     */
+    setAutoCompactionEnabled(enabled: boolean): void;
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled(): boolean;
+    /**
+     * Run the session-start boundary: dispatch session.start@1 to the capability
+     * runtime and run the resource discovery pass (contributed skills/prompts/
+     * themes). Hosts await this once after constructing (or rebinding to) a
+     * session, before the first prompt.
+     */
+    startSession(): Promise<void>;
+    private extendResourcesFromExtensions;
+    private buildExtensionResourcePaths;
+    private getExtensionSourceLabel;
+    private _refreshToolRegistry;
+    private _syncCapabilityTools;
+    private _getCapabilitySkills;
+    private _getAvailableSkills;
+    private _validateCapabilitySkillConflicts;
+    private _refreshBootstrapSkills;
+    private _disposeCapabilityPlugins;
+    /**
+     * 插件日志记录 → 宿主进程日志（会话轨迹第 2 期，设计 §7.2）：HostLogger 是
+     * debug/info/warn/error 四方法（无泛用 log），按记录级别映射调用；级别门槛由
+     * logger 自身过滤（"级别沿用宿主日志级别门槛"）。src 用 pluginId（宿主日志的
+     * 来源标记位）；sessionId 随行。LoggerRecord 当前无已填充的 correlationId
+     * （recordLog 不写该字段），不编造 traceId。
+     */
+    private _forwardLogRecordToHost;
+    private _buildRuntime;
+    reload(options?: {
+        beforeSessionStart?: () => void | Promise<void>;
+    }): Promise<void>;
+    /**
+     * Check if an error is retryable (overloaded, rate limit, server errors).
+     * Context overflow errors are NOT retryable (handled by compaction instead).
+     */
+    private _isRetryableError;
+    /**
+     * Prepare a retryable error for continuation with exponential backoff.
+     * @returns true if the caller should continue the agent, false otherwise
+     */
+    private _prepareRetry;
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry(): void;
+    /** Whether auto-retry is currently in progress */
+    get isRetrying(): boolean;
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled(): boolean;
+    /**
+     * Toggle auto-retry setting.
+     */
+    setAutoRetryEnabled(enabled: boolean): void;
+    /** Capture a mode-level bash epoch for an intercepted user_bash result. */
+    captureBashEpoch(): number;
+    /** Return whether a mode-level bash result still belongs to this runtime epoch. */
+    isBashEpochCurrent(epoch: number): boolean;
+    /** Dispatch the user.bash lifecycle facts for a `!`/`!!` user bash command. */
+    emitUserBash(excludeFromContext: boolean): void;
+    /**
+     * Execute a bash command.
+     * Adds result to agent context and session.
+     * @param command The bash command to execute
+     * @param onChunk Optional streaming callback for output
+     * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+     * @param options.id Optional identifier included in bash execution update events
+     * @param options.operations Custom BashOperations for remote execution
+     */
+    executeBash(command: string, onChunk?: (chunk: string) => void, options?: {
+        excludeFromContext?: boolean;
+        id?: string;
+        operations?: BashOperations;
+    }): Promise<BashResult>;
+    /**
+     * Record a bash execution result in session history.
+     * Used by executeBash and by extensions that handle bash execution themselves.
+     */
+    recordBashResult(command: string, result: BashResult, options?: {
+        excludeFromContext?: boolean;
+        epoch?: number;
+    }): void;
+    /**
+     * Cancel running bash command.
+     */
+    abortBash(): void;
+    /** Whether a bash command is currently running */
+    get isBashRunning(): boolean;
+    /** Whether there are pending bash messages waiting to be flushed */
+    get hasPendingBashMessages(): boolean;
+    /**
+     * Flush pending bash messages to agent state and session.
+     * Called after agent turn completes to maintain proper message ordering.
+     */
+    private _flushPendingBashMessages;
+    /**
+     * Set a display name for the current session.
+     */
+    setSessionName(name: string): void;
+    /**
+     * Record a cross-suite resume (设计 §10.1 最小可用版): the session was created
+     * under `originalSuiteId` but its context is being reassembled under
+     * `currentSuiteId` (assembly happens at session creation, so reassembly is
+     * the existing behavior). Appends a `suite_mismatch` custom entry as session
+     * protocol data so later debugging can trace the switch; context
+     * serialization/conversion is explicitly out of scope.
+     */
+    recordSuiteMismatch(originalSuiteId: string, currentSuiteId: string): void;
+    /**
+     * Navigate to a different node in the session tree.
+     * Unlike fork() which creates a new session file, this stays in the same file.
+     *
+     * @param targetId The entry ID to navigate to
+     * @param options.summarize Whether user wants to summarize abandoned branch
+     * @param options.customInstructions Custom instructions for summarizer
+     * @param options.replaceInstructions If true, customInstructions replaces the default prompt
+     * @param options.label Label to attach to the branch summary entry
+     * @returns Result with editorText (if user message) and cancelled status
+     */
+    navigateTree(targetId: string, options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+        replaceInstructions?: boolean;
+        label?: string;
+    }): Promise<{
+        editorText?: string;
+        cancelled: boolean;
+        aborted?: boolean;
+        summaryEntry?: BranchSummaryEntry;
+    }>;
+    /**
+     * Get all user messages from session for fork selector.
+     */
+    getUserMessagesForForking(): Array<{
+        entryId: string;
+        text: string;
+    }>;
+    /**
+     * Get session statistics. Aggregates over ALL session entries (including
+     * history that was compacted away), so token/cost totals reflect what was
+     * actually billed across the session.
+     */
+    getSessionStats(): SessionStats;
+    getContextUsage(): ContextUsage | undefined;
+    /**
+     * Export session to HTML.
+     * @param outputPath Optional output path (defaults to session directory)
+     * @param options Optional export presentation settings
+     * @returns Path to exported file
+     */
+    exportToHtml(outputPath?: string, options?: {
+        themeName?: string;
+    }): Promise<string>;
+    /**
+     * Export the current session branch to a JSONL file.
+     * Writes the session header followed by all entries on the current branch path.
+     * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
+     * @returns The resolved output file path.
+     */
+    exportToJsonl(outputPath?: string): string;
+    /**
+     * Get text content of last assistant message.
+     * Useful for /copy command.
+     * @returns Text content, or undefined if no assistant message exists
+     */
+    getLastAssistantText(): string | undefined;
+    createReplacedSessionContext(): ReplacedSessionContext;
+    /** Curated host surface (1B.7c): the only supported raw-integration point for product hosts. */
+    get host(): AgentSessionHostSurface;
+}
+/** Curated host surface over one AgentSession (1B.7c). Product hosts consume this instead of transitional raw fields. */
+export interface AgentSessionHostSurface {
+    /** Abort signal of the active agent run, when one is in flight. */
+    readonly abortSignal: AbortSignal | undefined;
+    readonly cwd: string;
+    readonly sessionName: string | undefined;
+    readonly entries: readonly SessionEntry[];
+    setTransport(transport: Transport): void;
+    /** Aborts the core agent loop without session-level teardown. */
+    abortAgent(): void;
+}
+//# sourceMappingURL=agent-session.d.ts.map