@robota-sdk/agent-sdk 3.0.0-beta.59 → 3.0.0-beta.60

package/dist/node/index.d.ts

@@ -1,8 +1,8 @@
-import { ITerminalOutput, ISessionLogger, TPermissionHandler, Session, SessionStore, FileSessionLogger } from '@robota-sdk/agent-sessions';
-export { ISpinner, ITerminalOutput } from '@robota-sdk/agent-sessions';
-import { TToolArgs, IHistoryEntry, IContextWindowState, TUniversalValue, THooksConfig, IToolWithEventService, IAIProvider, TPermissionMode, IHookTypeExecutor, IHookDefinition, IHookInput, IHookResult, TTrustLevel, TSessionEndReason, TUniversalMessage } from '@robota-sdk/agent-core';
+import { ICompactEvent, ITerminalOutput, ISessionLogger, TPermissionHandler, Session, SessionStore, FileSessionLogger } from '@robota-sdk/agent-sessions';
+export { ICompactEvent, ISpinner, ITerminalOutput, TCompactTrigger } from '@robota-sdk/agent-sessions';
+import { TUniversalValue, TSessionEndReason, TPermissionMode, IToolWithEventService, IContextWindowState, IProviderProfileConfig, IProviderDefinition, IProviderSetupStepDefinition, TProviderSetupField, IProviderProbeResult, TToolArgs, IHistoryEntry, THooksConfig, IAIProvider, IHookTypeExecutor, IHookDefinition, IHookInput, IHookResult, TTrustLevel, TUniversalMessage } from '@robota-sdk/agent-core';
 export { IAIProvider, IContextTokenUsage, IContextWindowState, IHistoryEntry, IHookInput, IPermissionLists, THookEvent, THooksConfig, TPermissionDecision, TPermissionMode, TRUST_TO_MODE, TToolArgs, TTrustLevel, chatEntryToMessage, evaluatePermission, getMessagesForAPI, isChatEntry, messageToHistoryEntry, runHooks } from '@robota-sdk/agent-core';
-import { IBackgroundTaskManager, TBackgroundTaskStatus, IBackgroundTaskError, TBackgroundTaskEvent, ISubagentRunner, IBackgroundTaskRunner, IBackgroundTaskListFilter, IBackgroundTaskState, IBackgroundTaskInput, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, ISubagentJobState, TBackgroundTaskIsolation, ISubagentJobResult, ISubagentManager } from '@robota-sdk/agent-runtime';
+import { IBackgroundTaskManager, TBackgroundTaskStatus, IBackgroundTaskError, IBackgroundTaskListFilter, IBackgroundTaskState, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, TBackgroundTaskEvent, ISubagentRunner, IBackgroundTaskRunner, IBackgroundTaskInput, ISubagentJobState, TBackgroundTaskIsolation, ISubagentJobResult, ISubagentManager } from '@robota-sdk/agent-runtime';
 export { BackgroundTaskError, BackgroundTaskManager, IAgentBackgroundTaskRequest, IBackgroundTaskError, IBackgroundTaskHandle, IBackgroundTaskInput, IBackgroundTaskListFilter, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, IBackgroundTaskManager, IBackgroundTaskManagerOptions, IBackgroundTaskRequest, IBackgroundTaskResult, IBackgroundTaskRunner, IBackgroundTaskStart, IBackgroundTaskState, IBaseBackgroundTaskRequest, IPreparedSubagentWorktree, IProcessBackgroundTaskRequest, ISerializableProviderProfile, ISubagentJobHandle, ISubagentJobResult, ISubagentJobStart, ISubagentJobState, ISubagentManager, ISubagentManagerOptions, ISubagentRunner, ISubagentSpawnRequest, ISubagentWorktreeAdapter, ISubagentWorktreePrepareRequest, IWorktreeSubagentRunnerOptions, SubagentManager, TBackgroundPermissionPolicy, TBackgroundPrimitive, TBackgroundTaskErrorCategory, TBackgroundTaskEvent, TBackgroundTaskEventListener, TBackgroundTaskIdFactory, TBackgroundTaskIsolation, TBackgroundTaskKind, TBackgroundTaskMode, TBackgroundTaskRunnerEvent, TBackgroundTaskStatus, TBackgroundTaskTimeoutReason, TBackgroundTaskTransitionEvent, TSubagentJobMode, TSubagentJobStatus, WorktreeSubagentRunner, createWorktreeSubagentRunner, getBackgroundTaskTransitions, isTerminalBackgroundTaskStatus, transitionBackgroundTaskStatus } from '@robota-sdk/agent-runtime';
 import { createZodFunctionTool } from '@robota-sdk/agent-tools';
 export { TToolResult } from '@robota-sdk/agent-tools';
@@ -62,41 +62,454 @@ interface ICommandSource {
     getCommands(): ICommand[];
 }
 
-/** Registry for system commands. */
-declare class SystemCommandExecutor {
-    private readonly commands;
-    constructor(commands?: ISystemCommand[]);
-    /** Register an additional command. */
-    register(command: ISystemCommand): void;
-    /** Execute a command by name. Returns null if command not found. */
-    execute(name: string, session: InteractiveSession, args: string): Promise<ICommandResult | null>;
-    /** List all registered commands. */
-    listCommands(): ISystemCommand[];
-    listModelInvocableCommands(): ICapabilityDescriptor[];
-    isModelInvocable(name: string): boolean;
-    executeModelInvocable(name: string, session: InteractiveSession, args: string): Promise<ICommandResult | null>;
-    /** Check if a command exists. */
-    hasCommand(name: string): boolean;
+declare const STATUSLINE_COMMAND_DESCRIPTION = "Configure TUI status-line visibility and fields such as model, context, tokens, session, and git branch.";
+declare const STATUSLINE_COMMAND_ARGUMENT_HINT = "on | off | reset | git on | git off";
+interface IStatusLineCommandSettings {
+    enabled: boolean;
+    gitBranch: boolean;
+}
+type TStatusLineCommandSettingsPatch = Partial<IStatusLineCommandSettings> & Record<string, TUniversalValue>;
+declare const DEFAULT_STATUS_LINE_COMMAND_SETTINGS: Readonly<IStatusLineCommandSettings>;
+declare function buildStatusLineCommandSubcommands(source?: string): ICommand[];
+declare function isStatusLineCommandSettingsPatch(value: Record<string, TUniversalValue>): value is TStatusLineCommandSettingsPatch;
+
+type TCommandEffect = {
+    type: 'model-change-requested';
+    modelId: string;
+} | {
+    type: 'language-change-requested';
+    language: string;
+} | {
+    type: 'settings-reset-requested';
+} | {
+    type: 'session-exit-requested';
+    reason?: TSessionEndReason;
+    message?: string;
+} | {
+    type: 'session-restart-requested';
+    reason: TSessionEndReason;
+    message: string;
+} | {
+    type: 'plugin-tui-requested';
+} | {
+    type: 'plugin-registry-reload-requested';
+} | {
+    type: 'session-picker-requested';
+} | {
+    type: 'session-renamed';
+    name: string;
+} | {
+    type: 'conversation-history-cleared';
+} | {
+    type: 'statusline-settings-patch';
+    patch: TStatusLineCommandSettingsPatch;
+};
+
+/** Choice option for command-owned follow-up prompts. */
+interface ICommandChoicePromptOption {
+    value: string;
+    label: string;
+}
+/** Generic prompt descriptor rendered by host UIs for command interactions. */
+type TCommandInteractionPrompt = {
+    kind: 'choice';
+    title: string;
+    options: readonly ICommandChoicePromptOption[];
+    maxVisible?: number;
+} | {
+    kind: 'text';
+    title: string;
+    placeholder?: string;
+    allowEmpty?: boolean;
+    masked?: boolean;
+    validate?: (value: string) => string | undefined;
+};
+/** Stateful command continuation owned by the command module. */
+interface ICommandInteraction {
+    prompt: TCommandInteractionPrompt;
+    submit(value: string): Promise<ICommandResult> | ICommandResult;
+    cancel?(): Promise<ICommandResult> | ICommandResult;
+}
+
+type TCommandResultDataValue = TUniversalValue | object | readonly object[];
+/** Result of a system command execution. */
+interface ICommandResult {
+    /** Human-readable output message */
+    message: string;
+    /** Command completed successfully */
+    success: boolean;
+    /** Additional structured data (command-specific diagnostics only) */
+    data?: Record<string, TCommandResultDataValue>;
+    /** Typed host effects requested by the command */
+    effects?: readonly TCommandEffect[];
+    /** Command-owned follow-up prompt and continuation */
+    interaction?: ICommandInteraction;
+}
+
+type TBackgroundJobWaitPolicy = 'detached' | 'wait_all' | 'wait_any' | 'manual';
+type TBackgroundJobGroupStatus = 'running' | 'completed';
+interface IBackgroundJobResultEnvelope {
+    taskId: string;
+    label: string;
+    status: TBackgroundTaskStatus;
+    summary?: string;
+    outputRef?: string;
+    error?: IBackgroundTaskError;
+    startedAt?: string;
+    completedAt?: string;
+}
+interface IBackgroundJobGroupState {
+    id: string;
+    parentSessionId: string;
+    waitPolicy: TBackgroundJobWaitPolicy;
+    taskIds: string[];
+    status: TBackgroundJobGroupStatus;
+    createdAt: string;
+    updatedAt: string;
+    label?: string;
+    completedAt?: string;
+    results: IBackgroundJobResultEnvelope[];
+}
+interface IBackgroundJobGroupSummary {
+    groupId: string;
+    status: TBackgroundJobGroupStatus;
+    total: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    pending: number;
+    lines: string[];
+}
+interface IBackgroundJobGroupCreateRequest {
+    parentSessionId: string;
+    waitPolicy: TBackgroundJobWaitPolicy;
+    taskIds: string[];
+    label?: string;
+}
+type TBackgroundJobGroupEvent = {
+    type: 'background_job_group_created';
+    group: IBackgroundJobGroupState;
+} | {
+    type: 'background_job_group_updated';
+    group: IBackgroundJobGroupState;
+} | {
+    type: 'background_job_group_completed';
+    group: IBackgroundJobGroupState;
+};
+type TBackgroundJobGroupEventListener = (event: TBackgroundJobGroupEvent) => void;
+type TBackgroundJobGroupIdFactory = (request: IBackgroundJobGroupCreateRequest) => string;
+interface IBackgroundJobOrchestratorOptions {
+    manager: IBackgroundTaskManager;
+    now?: () => string;
+    idFactory?: TBackgroundJobGroupIdFactory;
+    initialGroups?: readonly IBackgroundJobGroupState[];
+}
+declare class BackgroundJobOrchestrator {
+    private readonly manager;
+    private readonly now;
+    private readonly idFactory;
+    private readonly unsubscribeManager;
+    private readonly listeners;
+    private readonly groups;
+    private sequence;
+    constructor(options: IBackgroundJobOrchestratorOptions);
+    createGroup(request: IBackgroundJobGroupCreateRequest): IBackgroundJobGroupState;
+    listGroups(): IBackgroundJobGroupState[];
+    getGroup(groupId: string): IBackgroundJobGroupState | undefined;
+    waitGroup(groupId: string): Promise<IBackgroundJobGroupState>;
+    subscribe(listener: TBackgroundJobGroupEventListener): () => void;
+    dispose(): void;
+    private nextGroupId;
+    private restoreGroup;
+    private createRecord;
+    private captureExistingTerminalTasks;
+    private handleTaskEvent;
+    private captureTask;
+    private evaluateCompletion;
+    private emit;
+}
+declare function summarizeBackgroundJobGroup(group: IBackgroundJobGroupState): IBackgroundJobGroupSummary;
+
+declare const PLUGIN_COMMAND_DESCRIPTION = "Manage plugins";
+declare const PLUGIN_COMMAND_ARGUMENT_HINT = "manage | install <name@marketplace> | uninstall <name@marketplace> | enable <name@marketplace> | disable <name@marketplace> | marketplace <action>";
+declare const RELOAD_PLUGINS_COMMAND_DESCRIPTION = "Reload all plugin resources";
+type TPluginInstallScope = 'user' | 'project';
+interface ICommandInstalledPlugin {
+    name: string;
+    description: string;
+    enabled: boolean;
+}
+interface ICommandAvailablePlugin {
+    name: string;
+    description: string;
+    installed: boolean;
+}
+interface ICommandMarketplaceSource {
+    name: string;
+    type: string;
+}
+interface ICommandPluginReloadResult {
+    loadedPluginCount: number;
+}
+interface ICommandPluginAdapter {
+    listInstalled(): Promise<readonly ICommandInstalledPlugin[]>;
+    listAvailablePlugins(marketplace: string): Promise<readonly ICommandAvailablePlugin[]>;
+    install(pluginId: string, scope?: TPluginInstallScope): Promise<void>;
+    uninstall(pluginId: string): Promise<void>;
+    enable(pluginId: string): Promise<void>;
+    disable(pluginId: string): Promise<void>;
+    marketplaceAdd(source: string): Promise<string>;
+    marketplaceRemove(name: string): Promise<void>;
+    marketplaceUpdate(name: string): Promise<void>;
+    marketplaceList(): Promise<readonly ICommandMarketplaceSource[]>;
+    reloadPlugins(): Promise<ICommandPluginReloadResult>;
+}
+declare function createPluginTuiRequestedEffect(): TCommandEffect;
+declare function createPluginRegistryReloadRequestedEffect(): TCommandEffect;
+declare function resolvePluginCommandAdapter(context: ICommandHostContext): ICommandPluginAdapter | undefined;
+declare function buildPluginCommandSubcommands(): ICommand[];
+
+interface ICommandSettingsDocument {
+    [key: string]: TUniversalValue;
+}
+interface ICommandSettingsAdapter<TSettings extends ICommandSettingsDocument = ICommandSettingsDocument> {
+    read(): TSettings;
+    write(settings: TSettings): void;
+}
+interface ICommandProcessAdapter {
+    requestExit(reason?: TSessionEndReason): void;
+    requestRestart(reason: TSessionEndReason, message: string): void;
+}
+interface ICommandPickerAdapter<TItem extends ICommandSettingsDocument> {
+    pick(items: readonly TItem[]): Promise<TItem | undefined> | TItem | undefined;
+}
+interface ICommandPermissionModeAdapter {
+    getPermissionMode(): TPermissionMode;
+    setPermissionMode(mode: TPermissionMode): void;
+    listSessionAllowedTools(): readonly string[];
+}
+interface ICommandHostAdapters {
+    settings?: ICommandSettingsAdapter;
+    process?: ICommandProcessAdapter;
+    permissionMode?: ICommandPermissionModeAdapter;
+    plugin?: ICommandPluginAdapter;
+}
+
+interface IEditCheckpointRecorder {
+    captureFile(filePath: string): Promise<void> | void;
+}
+interface IEditCheckpointTurnInput {
+    sessionId: string;
+    prompt: string;
+}
+interface IEditCheckpointSummary {
+    id: string;
+    sessionId: string;
+    sequence: number;
+    prompt: string;
+    createdAt: string;
+    fileCount: number;
+}
+interface IEditCheckpointFileRecord {
+    originalPath: string;
+    existed: boolean;
+    snapshotFile?: string;
+}
+interface IEditCheckpointManifest extends IEditCheckpointSummary {
+    version: 1;
+    files: IEditCheckpointFileRecord[];
+}
+type TEditCheckpointFileRestoreAction = 'restore-preimage' | 'delete-created-file';
+interface IEditCheckpointFileInspection {
+    originalPath: string;
+    relativePath: string;
+    existed: boolean;
+    restoreAction: TEditCheckpointFileRestoreAction;
+    snapshotAvailable: boolean;
+    snapshotSizeBytes?: number;
+}
+interface IEditCheckpointInspectionPlan {
+    checkpointIds: string[];
+    fileCount: number;
+}
+interface IEditCheckpointInspection {
+    target: IEditCheckpointSummary;
+    capturedFiles: IEditCheckpointFileInspection[];
+    restoreToCheckpoint: IEditCheckpointInspectionPlan;
+    rollbackThroughCheckpoint: IEditCheckpointInspectionPlan;
+}
+interface IEditCheckpointRestoreResult {
+    target: IEditCheckpointSummary;
+    restoredCheckpointCount: number;
+    restoredFileCount: number;
+    removedCheckpointCount: number;
+}
+
+interface IEditCheckpointStoreOptions {
+    cwd: string;
+    now?: () => Date;
+}
+declare class EditCheckpointStore {
+    private readonly cwd;
+    private readonly rootDir;
+    private readonly now;
+    private activeTurn;
+    constructor(options: IEditCheckpointStoreOptions);
+    beginTurn(input: IEditCheckpointTurnInput): Promise<IEditCheckpointSummary>;
+    captureFile(filePath: string): Promise<void>;
+    finalizeTurn(): Promise<IEditCheckpointSummary | undefined>;
+    list(sessionId: string): IEditCheckpointSummary[];
+    inspect(sessionId: string, checkpointId: string): IEditCheckpointInspection;
+    restoreToCheckpoint(sessionId: string, checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+    rollbackThroughCheckpoint(sessionId: string, checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+    private createFileRecord;
+    private restoreFile;
+    private loadManifests;
+    private nextSequence;
+    private writeManifest;
+    private sessionDir;
+    private checkpointDir;
+}
+
+declare function wrapEditCheckpointTools(tools: readonly IToolWithEventService[], recorder: IEditCheckpointRecorder): IToolWithEventService[];
+
+declare const MEMORY_INDEX_MAX_LINES = 200;
+declare const MEMORY_INDEX_MAX_BYTES: number;
+type TMemoryType = 'user' | 'feedback' | 'project' | 'reference';
+interface IStartupMemory {
+    content: string;
+    path: string;
+    lineCount: number;
+    truncated: boolean;
+}
+interface IMemoryTopicSummary {
+    name: string;
+    path: string;
+}
+interface IProjectMemorySummary {
+    indexPath: string;
+    topicsPath: string;
+    topics: IMemoryTopicSummary[];
+}
+interface IAppendMemoryInput {
+    type: TMemoryType;
+    topic: string;
+    text: string;
+}
+interface IAppendMemoryResult {
+    indexPath: string;
+    topicPath: string;
+    topic: string;
+    deduplicated: boolean;
+}
+declare function isMemoryType(value: string): value is TMemoryType;
+declare class ProjectMemoryStore {
+    private readonly cwd;
+    private readonly now;
+    constructor(cwd: string, now?: () => Date);
+    getIndexPath(): string;
+    getTopicsPath(): string;
+    loadStartupMemory(): IStartupMemory;
+    list(): IProjectMemorySummary;
+    readTopic(topic: string): string;
+    append(input: IAppendMemoryInput): IAppendMemoryResult;
+}
+
+type TMemoryCandidateStatus = 'pending' | 'approved' | 'rejected' | 'saved' | 'skipped';
+interface IMemoryCandidate {
+    id: string;
+    type: TMemoryType;
+    topic: string;
+    text: string;
+    sourceMessageIds: string[];
+    confidence: number;
+    createdAt: string;
+    reason: string;
+}
+interface IMemoryPendingRecord extends IMemoryCandidate {
+    status: TMemoryCandidateStatus;
+    updatedAt: string;
+    decisionReason?: string;
+}
+interface IMemoryReference {
+    topic: string;
+    path: string;
+    score: number;
+    truncated: boolean;
+}
+interface IMemoryEvent {
+    type: 'memory_candidate_extracted' | 'memory_candidate_queued' | 'memory_candidate_saved' | 'memory_candidate_skipped' | 'memory_candidate_approved' | 'memory_candidate_rejected' | 'memory_retrieved';
+    at: string;
+    candidateId?: string;
+    topic?: string;
+    reason?: string;
+    data?: Record<string, TUniversalValue>;
+}
+
+type TAutoCompactThreshold$1 = number | false;
+declare const DEFAULT_AUTO_COMPACT_THRESHOLD = 0.835;
+declare const AUTO_COMPACT_THRESHOLD_SETTINGS_KEY = "autoCompactThreshold";
+interface ICompactContextResult {
+    before: IContextWindowState;
+    after: IContextWindowState;
+}
+/** Read context-window state through the command host facade. */
+declare function readCommandContextState(context: ICommandHostContext): IContextWindowState;
+/** Read the effective automatic compact policy through the command host facade. */
+declare function readAutoCompactThreshold(context: ICommandHostContext): TAutoCompactThreshold$1;
+/** Read the source of the effective automatic compact policy. */
+declare function readAutoCompactThresholdSource(context: ICommandHostContext): TAutoCompactThresholdSource;
+/** Update the active session's automatic compact policy through the command host facade. */
+declare function setCommandAutoCompactThreshold(context: ICommandHostContext, threshold: TAutoCompactThreshold$1, source: TAutoCompactThresholdSource): void;
+/** Persist an automatic compact policy value through the host settings adapter, when present. */
+declare function writeAutoCompactThresholdSetting(context: ICommandHostContext, threshold: TAutoCompactThreshold$1): boolean;
+/** Remove the persisted automatic compact policy through the host settings adapter, when present. */
+declare function resetAutoCompactThresholdSetting(context: ICommandHostContext): boolean;
+/** Run manual compaction through the command host facade and return before/after state. */
+declare function compactCommandContext(context: ICommandHostContext, instructions?: string): Promise<ICompactContextResult>;
+
+interface ICommandListEntry {
+    name: string;
+    description: string;
+}
+type TAutoCompactThresholdSource = 'default' | 'settings' | 'session';
+interface ICommandSessionRuntime {
+    clearHistory(): void;
+    compact(instructions?: string): Promise<void>;
+    getContextState(): IContextWindowState;
+    getPermissionMode(): TPermissionMode;
+    setPermissionMode(mode: TPermissionMode): void;
+    getSessionId(): string;
+    getMessageCount(): number;
+    getSessionAllowedTools(): readonly string[];
+    getAutoCompactThreshold?(): number | false;
+    setAutoCompactThreshold?(threshold: TAutoCompactThreshold$1): void;
+}
+interface ICommandHostContext {
+    clearConversationHistory?(): void;
+    getSession(): ICommandSessionRuntime;
+    getContextState(): IContextWindowState;
+    getAutoCompactThreshold(): TAutoCompactThreshold$1;
+    getAutoCompactThresholdSource?(): TAutoCompactThresholdSource;
+    setAutoCompactThreshold?(threshold: TAutoCompactThreshold$1, source?: TAutoCompactThresholdSource): void;
+    getCommandHostAdapters?(): ICommandHostAdapters;
+    compactContext(instructions?: string): Promise<void>;
+    getCwd(): string;
+    listCommands?(): ICommandListEntry[];
+    listEditCheckpoints(): IEditCheckpointSummary[];
+    inspectEditCheckpoint?(checkpointId: string): IEditCheckpointInspection;
+    restoreEditCheckpoint(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+    rollbackEditCheckpoint(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+    getUsedMemoryReferences(): IMemoryReference[];
+    recordMemoryEvent(event: IMemoryEvent): void;
+    listBackgroundTasks(filter?: IBackgroundTaskListFilter): IBackgroundTaskState[];
+    readBackgroundTaskLog(taskId: string, cursor?: IBackgroundTaskLogCursor): Promise<IBackgroundTaskLogPage>;
+    cancelBackgroundTask(taskId: string, reason?: string): Promise<void>;
+    closeBackgroundTask(taskId: string): Promise<void>;
 }
 
-/**
- * System commands — SDK-level command execution logic.
- *
- * Pure functions that operate on InteractiveSession.
- * No React, no TUI, no framework dependencies.
- * CLI wraps these as slash commands with UI chrome.
- */
-
-/** Result of a system command execution. */
-interface ICommandResult {
-    /** Human-readable output message */
-    message: string;
-    /** Command completed successfully */
-    success: boolean;
-    /** Additional structured data (command-specific) */
-    data?: Record<string, unknown>;
-}
-/** A system command with name, description, and execute logic. */
+type TSystemCommandLifecycle = 'inline' | 'blocking' | 'background';
+/** A user-visible command with descriptor metadata and execute logic. */
 interface ISystemCommand {
     name: string;
     description: string;
@@ -104,10 +517,10 @@ interface ISystemCommand {
     userInvocable?: boolean;
     argumentHint?: string;
     safety?: TCapabilitySafety;
-    execute(session: InteractiveSession, args: string): Promise<ICommandResult> | ICommandResult;
+    subcommands?: readonly ICommand[];
+    lifecycle?: TSystemCommandLifecycle;
+    execute(context: ICommandHostContext, args: string): Promise<ICommandResult> | ICommandResult;
 }
-/** Built-in system commands. */
-declare function createSystemCommands(): ISystemCommand[];
 
 type TCommandModuleSessionRequirement = 'agent-runtime';
 /** Composable command capability module. */
@@ -124,10 +537,213 @@ interface ICommandModule {
     readonly sessionRequirements?: readonly TCommandModuleSessionRequirement[];
 }
 
+interface IProviderProfileSettings extends IProviderProfileConfig {
+    [key: string]: TUniversalValue;
+}
+interface ILegacyProviderSettings {
+    [key: string]: TUniversalValue;
+    name?: string;
+    model?: string;
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    options?: Record<string, TUniversalValue>;
+}
+type TProviderSettingsDocument = Record<string, TUniversalValue> & {
+    currentProvider?: string;
+    providers?: Record<string, IProviderProfileSettings>;
+    provider?: ILegacyProviderSettings;
+};
+interface IProviderSetupInput {
+    profile: string;
+    type: string;
+    model?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    baseURL?: string;
+    timeout?: number;
+    setCurrent?: boolean;
+}
+interface IProviderSetupPatch {
+    currentProvider?: string;
+    providers: Record<string, IProviderProfileSettings>;
+}
+interface IProviderSettingsBuildOptions {
+    providerDefinitions?: readonly IProviderDefinition[];
+}
+declare function upsertProviderProfile(settings: TProviderSettingsDocument, profileName: string, profile: IProviderProfileSettings): TProviderSettingsDocument;
+declare function setCurrentProvider(settings: TProviderSettingsDocument, profileName: string): TProviderSettingsDocument;
+declare function validateProviderProfile(profileName: string, profile: IProviderProfileSettings, options?: IProviderSettingsBuildOptions): void;
+declare function buildProviderSetupPatch(input: IProviderSetupInput, options?: IProviderSettingsBuildOptions): IProviderSetupPatch;
+declare function buildProviderProfile(input: IProviderSetupInput, options?: IProviderSettingsBuildOptions): IProviderProfileSettings;
+declare function mergeProviderPatch(settings: TProviderSettingsDocument, patch: IProviderSetupPatch): TProviderSettingsDocument;
+
+interface IProviderCommandSettingsAdapter {
+    readMergedSettings(): TProviderSettingsDocument;
+    readTargetSettings(): TProviderSettingsDocument;
+    writeTargetSettings(settings: TProviderSettingsDocument): void;
+}
+interface IProviderCommandModuleOptions {
+    providerDefinitions: readonly IProviderDefinition[];
+    settings: IProviderCommandSettingsAdapter;
+}
+
+type TProviderSetupType = string;
+type TPromptInput = (label: string, masked?: boolean) => Promise<string>;
+interface IProviderSetupPromptStep extends IProviderSetupStepDefinition {
+    key: TProviderSetupField;
+}
+interface IProviderSetupFlowState {
+    type: TProviderSetupType;
+    steps: readonly IProviderSetupPromptStep[];
+    stepIndex: number;
+    values: Partial<Record<TProviderSetupField, string>>;
+}
+type TProviderSetupFlowSubmitResult = {
+    status: 'next';
+    state: IProviderSetupFlowState;
+} | {
+    status: 'complete';
+    input: IProviderSetupInput;
+} | {
+    status: 'error';
+    state: IProviderSetupFlowState;
+    message: string;
+};
+declare function createProviderSetupFlow(type: TProviderSetupType, providerDefinitions: readonly IProviderDefinition[]): IProviderSetupFlowState;
+declare function formatProviderSetupSelectionPrompt(providerDefinitions: readonly IProviderDefinition[]): string;
+declare function resolveProviderSetupSelection(rawValue: string, providerDefinitions: readonly IProviderDefinition[]): TProviderSetupType;
+declare function getProviderSetupStep(state: IProviderSetupFlowState): IProviderSetupPromptStep;
+declare function submitProviderSetupValue(state: IProviderSetupFlowState, rawValue: string): TProviderSetupFlowSubmitResult;
+declare function runProviderSetupPromptFlow(type: TProviderSetupType, promptInput: TPromptInput, providerDefinitions: readonly IProviderDefinition[]): Promise<IProviderSetupInput>;
+declare function formatProviderSetupPromptLabel(step: IProviderSetupPromptStep): string;
+declare function formatProviderSetupChoiceLabel(definition: IProviderDefinition): string;
+declare function validateProviderSetupValue(step: IProviderSetupPromptStep, value: string): string | undefined;
+
+declare function isEnvReference(value: string): boolean;
+declare function formatEnvReference(name: string): string;
+declare function resolveEnvReference(value: string): string | undefined;
+declare function hasUsableSecretReference(value: string | undefined): boolean;
+
+declare function testProviderProfileCommand(currentProvider: string | undefined, providers: Record<string, IProviderProfileSettings> | undefined, profileArg: string | undefined, options: IProviderCommandModuleOptions): Promise<ICommandResult>;
+declare function probeProviderProfile(profile: IProviderProfileConfig): Promise<IProviderProbeResult>;
+
+declare const HELP_COMMAND_DESCRIPTION = "Show available commands";
+declare function formatCommandHelpMessage(context: ICommandHostContext): string;
+
+declare const BACKGROUND_COMMAND_DESCRIPTION = "List and control background tasks";
+declare const BACKGROUND_COMMAND_USAGE = "Usage: background list | background read <task-id> [offset] | background cancel <task-id> | background close <task-id>";
+declare function buildBackgroundCommandSubcommands(): ICommand[];
+declare function formatCommandBackgroundTask(task: IBackgroundTaskState): string;
+declare function formatCommandBackgroundTaskList(tasks: IBackgroundTaskState[]): string;
+declare function parseCommandBackgroundLogCursor(value?: string): IBackgroundTaskLogCursor | undefined;
+declare function listCommandBackgroundTasks(context: ICommandHostContext, filter?: IBackgroundTaskListFilter): IBackgroundTaskState[];
+declare function readCommandBackgroundTaskLog(context: ICommandHostContext, taskId: string, cursor?: IBackgroundTaskLogCursor): Promise<IBackgroundTaskLogPage>;
+declare function cancelCommandBackgroundTask(context: ICommandHostContext, taskId: string, reason?: string): Promise<void>;
+declare function closeCommandBackgroundTask(context: ICommandHostContext, taskId: string): Promise<void>;
+
+declare const MODEL_COMMAND_DESCRIPTION = "Change AI model";
+declare const MODEL_COMMAND_ARGUMENT_HINT = "<model-id>";
+declare function buildModelCommandSubcommands(source?: string): ICommand[];
+
+declare const LANGUAGE_COMMAND_DESCRIPTION = "Set response language";
+declare const LANGUAGE_COMMAND_ARGUMENT_HINT = "<code>";
+declare const RECOMMENDED_RESPONSE_LANGUAGES: readonly [{
+    readonly code: "ko";
+    readonly description: "Korean";
+}, {
+    readonly code: "en";
+    readonly description: "English";
+}, {
+    readonly code: "ja";
+    readonly description: "Japanese";
+}, {
+    readonly code: "zh";
+    readonly description: "Chinese";
+}];
+type TRecommendedResponseLanguage = (typeof RECOMMENDED_RESPONSE_LANGUAGES)[number]['code'];
+declare function buildLanguageCommandSubcommands(source?: string): ICommand[];
+declare function parseLanguageArgument(args: string): string | undefined;
+declare function formatLanguageUsageMessage(commandName?: string): string;
+
+declare const PERMISSION_MODE_COMMAND_DESCRIPTION = "Show/change permission mode";
+declare const PERMISSION_MODE_ARGUMENT_HINT = "plan | default | acceptEdits | bypassPermissions";
+declare const PERMISSIONS_COMMAND_DESCRIPTION = "Show permission rules";
+interface IPermissionsCommandState {
+    readonly mode: TPermissionMode;
+    readonly sessionAllowed: readonly string[];
+}
+declare const VALID_PERMISSION_MODES: readonly TPermissionMode[];
+declare function buildPermissionModeSubcommands(source?: string): ICommand[];
+declare function parsePermissionModeArgument(args: string): string | undefined;
+declare function isPermissionMode(value: string): value is TPermissionMode;
+declare function formatInvalidPermissionModeMessage(): string;
+declare function resolvePermissionModeAdapter(context: ICommandHostContext): ICommandPermissionModeAdapter;
+declare function readCommandPermissionMode(context: ICommandHostContext): TPermissionMode;
+declare function writeCommandPermissionMode(context: ICommandHostContext, mode: TPermissionMode): void;
+declare function listCommandSessionAllowedTools(context: ICommandHostContext): readonly string[];
+declare function readCommandPermissionsState(context: ICommandHostContext): IPermissionsCommandState;
+declare function formatCommandPermissionsMessage(state: IPermissionsCommandState): string;
+
+declare const CLEAR_COMMAND_DESCRIPTION = "Clear conversation history";
+declare const RENAME_COMMAND_DESCRIPTION = "Rename the current session";
+declare const RENAME_COMMAND_USAGE = "Usage: rename <name>";
+declare const RESUME_COMMAND_DESCRIPTION = "Resume a previous session";
+declare const COST_COMMAND_DESCRIPTION = "Show session info";
+declare const EXIT_COMMAND_DESCRIPTION = "Exit CLI";
+interface ICommandSessionInfo {
+    sessionId: string;
+    messageCount: number;
+}
+declare function clearConversationHistory(context: ICommandHostContext): void;
+declare function parseSessionNameArgument(args: string): string | undefined;
+declare function createSessionRenamedEffect(name: string): TCommandEffect;
+declare function createSessionPickerRequestedEffect(): TCommandEffect;
+declare function createSessionExitRequestedEffect(): TCommandEffect;
+declare function readCommandSessionInfo(context: ICommandHostContext): ICommandSessionInfo;
+
+declare const REWIND_COMMAND_DESCRIPTION = "List, inspect, restore, or rollback edit checkpoints.";
+declare const REWIND_COMMAND_ARGUMENT_HINT = "list | inspect CHECKPOINT_ID | restore CHECKPOINT_ID | code CHECKPOINT_ID | rollback CHECKPOINT_ID";
+declare function buildRewindCommandSubcommands(source?: string): ICommand[];
+declare function listCommandEditCheckpoints(context: ICommandHostContext): readonly IEditCheckpointSummary[];
+declare function inspectCommandEditCheckpoint(context: ICommandHostContext, checkpointId: string): IEditCheckpointInspection;
+declare function restoreCommandEditCheckpoint(context: ICommandHostContext, checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+declare function rollbackCommandEditCheckpoint(context: ICommandHostContext, checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+
+declare const MEMORY_COMMAND_DESCRIPTION = "Project memory command. Use it to inspect project memory when stored context may help, save durable preferences, project conventions, feedback, or references worth reusing across sessions, review pending candidates, and report memory provenance. Do not store secrets, credentials, or transient facts.";
+declare const MEMORY_COMMAND_ARGUMENT_HINT = "list | show [topic] | add <user|feedback|project|reference> <topic> <text> | pending | approve <id> | reject <id> | used";
+declare const MEMORY_COMMAND_USAGE = "Usage: memory list | memory show [topic] | memory add <user|feedback|project|reference> <topic> <text> | memory pending | memory approve <id> | memory reject <id> | memory used";
+interface ICommandProjectMemoryStore {
+    list(): IProjectMemorySummary;
+    loadStartupMemory(): IStartupMemory;
+    readTopic(topic: string): string;
+    append(input: IAppendMemoryInput): IAppendMemoryResult;
+}
+interface ICommandPendingMemoryStore {
+    get(id: string): IMemoryPendingRecord | undefined;
+    list(status?: TMemoryCandidateStatus): IMemoryPendingRecord[];
+    mark(id: string, status: TMemoryCandidateStatus, reason: string): IMemoryPendingRecord;
+    upsert(candidate: IMemoryCandidate, status: TMemoryCandidateStatus, reason: string): void;
+}
+interface ICommandMemoryStores {
+    project: ICommandProjectMemoryStore;
+    pending: ICommandPendingMemoryStore;
+}
+
+declare function buildMemoryCommandSubcommands(source?: string): ICommand[];
+declare function createCommandProjectMemoryStore(cwd: string, now?: () => Date): ICommandProjectMemoryStore;
+declare function createCommandPendingMemoryStore(cwd: string, now?: () => Date): ICommandPendingMemoryStore;
+declare function createCommandMemoryStores(context: ICommandHostContext, now?: () => Date): ICommandMemoryStores;
+declare function isCommandMemoryType(value: string): value is TMemoryType;
+declare function hasSensitiveCommandMemoryContent(text: string): boolean;
+declare function listCommandUsedMemoryReferences(context: ICommandHostContext): readonly IMemoryReference[];
+declare function recordCommandMemoryEvent(context: ICommandHostContext, event: Omit<IMemoryEvent, 'at'>, now?: () => Date): void;
+
 /** Aggregates commands from multiple sources */
 declare class CommandRegistry {
     private sources;
     addSource(source: ICommandSource): void;
+    replaceSource(name: string, source?: ICommandSource): void;
     addModule(module: ICommandModule): void;
     /** Get all commands, optionally filtered by prefix */
     getCommands(filter?: string): ICommand[];
@@ -138,13 +754,14 @@ declare class CommandRegistry {
     getCapabilityDescriptors(): ICapabilityDescriptor[];
 }
 
-/** Command source for built-in commands */
+/** Command source for SDK-owned built-in commands. */
 declare class BuiltinCommandSource implements ICommandSource {
     readonly name = "builtin";
     private readonly commands;
-    constructor();
+    constructor(systemCommands?: readonly ISystemCommand[]);
     getCommands(): ICommand[];
 }
+declare function createBuiltinCommandModule(): ICommandModule;
 
 interface IFrontmatter {
     name?: string;
@@ -536,6 +1153,28 @@ declare class PluginCommandSource implements ICommandSource {
     getCommands(): ICommand[];
 }
 
+/** Registry for system commands. */
+declare class SystemCommandExecutor {
+    private readonly commands;
+    constructor(commands?: ISystemCommand[]);
+    /** Register an additional command. */
+    register(command: ISystemCommand): void;
+    /** Execute a command by name. Returns null if command not found. */
+    execute(name: string, session: ICommandHostContext, args: string): Promise<ICommandResult | null>;
+    getCommand(name: string): ISystemCommand | undefined;
+    executeCommand(command: ISystemCommand, session: ICommandHostContext, args: string): Promise<ICommandResult>;
+    /** List all registered commands. */
+    listCommands(): ISystemCommand[];
+    listModelInvocableCommands(): ICapabilityDescriptor[];
+    isModelInvocable(name: string): boolean;
+    executeModelInvocable(name: string, session: ICommandHostContext, args: string): Promise<ICommandResult | null>;
+    /** Check if a command exists. */
+    hasCommand(name: string): boolean;
+}
+
+/** Built-in system commands. */
+declare function createSystemCommands(): ISystemCommand[];
+
 /**
  * Build a skill prompt from slash command input.
  * Supports variable substitution and shell command preprocessing.
@@ -608,90 +1247,6 @@ interface ISkillExecutionResult {
  */
 declare function executeSkill(skill: ICommand, args: string, callbacks: ISkillExecutionCallbacks, context?: SkillPromptContext): Promise<ISkillExecutionResult>;
 
-type TBackgroundJobWaitPolicy = 'detached' | 'wait_all' | 'wait_any' | 'manual';
-type TBackgroundJobGroupStatus = 'running' | 'completed';
-interface IBackgroundJobResultEnvelope {
-    taskId: string;
-    label: string;
-    status: TBackgroundTaskStatus;
-    summary?: string;
-    outputRef?: string;
-    error?: IBackgroundTaskError;
-    startedAt?: string;
-    completedAt?: string;
-}
-interface IBackgroundJobGroupState {
-    id: string;
-    parentSessionId: string;
-    waitPolicy: TBackgroundJobWaitPolicy;
-    taskIds: string[];
-    status: TBackgroundJobGroupStatus;
-    createdAt: string;
-    updatedAt: string;
-    label?: string;
-    completedAt?: string;
-    results: IBackgroundJobResultEnvelope[];
-}
-interface IBackgroundJobGroupSummary {
-    groupId: string;
-    status: TBackgroundJobGroupStatus;
-    total: number;
-    completed: number;
-    failed: number;
-    cancelled: number;
-    pending: number;
-    lines: string[];
-}
-interface IBackgroundJobGroupCreateRequest {
-    parentSessionId: string;
-    waitPolicy: TBackgroundJobWaitPolicy;
-    taskIds: string[];
-    label?: string;
-}
-type TBackgroundJobGroupEvent = {
-    type: 'background_job_group_created';
-    group: IBackgroundJobGroupState;
-} | {
-    type: 'background_job_group_updated';
-    group: IBackgroundJobGroupState;
-} | {
-    type: 'background_job_group_completed';
-    group: IBackgroundJobGroupState;
-};
-type TBackgroundJobGroupEventListener = (event: TBackgroundJobGroupEvent) => void;
-type TBackgroundJobGroupIdFactory = (request: IBackgroundJobGroupCreateRequest) => string;
-interface IBackgroundJobOrchestratorOptions {
-    manager: IBackgroundTaskManager;
-    now?: () => string;
-    idFactory?: TBackgroundJobGroupIdFactory;
-    initialGroups?: readonly IBackgroundJobGroupState[];
-}
-declare class BackgroundJobOrchestrator {
-    private readonly manager;
-    private readonly now;
-    private readonly idFactory;
-    private readonly unsubscribeManager;
-    private readonly listeners;
-    private readonly groups;
-    private sequence;
-    constructor(options: IBackgroundJobOrchestratorOptions);
-    createGroup(request: IBackgroundJobGroupCreateRequest): IBackgroundJobGroupState;
-    listGroups(): IBackgroundJobGroupState[];
-    getGroup(groupId: string): IBackgroundJobGroupState | undefined;
-    waitGroup(groupId: string): Promise<IBackgroundJobGroupState>;
-    subscribe(listener: TBackgroundJobGroupEventListener): () => void;
-    dispose(): void;
-    private nextGroupId;
-    private restoreGroup;
-    private createRecord;
-    private captureExistingTerminalTasks;
-    private handleTaskEvent;
-    private captureTask;
-    private evaluateCompletion;
-    private emit;
-}
-declare function summarizeBackgroundJobGroup(group: IBackgroundJobGroupState): IBackgroundJobGroupSummary;
-
 /**
  * Types for InteractiveSession — event-driven session wrapper.
  */
@@ -750,6 +1305,7 @@ interface IInteractiveSessionEvents {
     complete: (result: IExecutionResult) => void;
     error: (error: Error) => void;
     context_update: (state: IContextWindowState) => void;
+    compact: (event: ICompactEvent) => void;
     interrupted: (result: IExecutionResult) => void;
     background_task_event: (event: TBackgroundTaskEvent) => void;
     background_job_group_event: (event: TBackgroundJobGroupEvent) => void;
@@ -832,6 +1388,8 @@ interface IResolvedConfig {
             ref?: string;
         };
     }>;
+    /** Auto-compact threshold as a 0-1 fraction. Set false to disable automatic compaction. */
+    autoCompactThreshold?: number | false;
 }
 
 interface ILoadedContext {
@@ -1034,36 +1592,36 @@ interface ISystemPromptParams {
     commandDescriptors?: ICapabilityDescriptor[];
 }
 
-interface IEditCheckpointRecorder {
-    captureFile(filePath: string): Promise<void> | void;
-}
-interface IEditCheckpointTurnInput {
-    sessionId: string;
-    prompt: string;
-}
-interface IEditCheckpointSummary {
-    id: string;
-    sessionId: string;
-    sequence: number;
-    prompt: string;
-    createdAt: string;
-    fileCount: number;
+type TReversibleExecutionIsolation = 'none' | 'worktree' | 'provider-sandbox';
+type TReversibleRollbackLayer = 'none' | 'edit-checkpoint' | 'worktree' | 'provider-sandbox';
+type TReversibleSideEffect = 'none' | 'file-mutation' | 'shell-process' | 'subagent' | 'unknown';
+type TReversibleSafetyStatus = 'reversible' | 'read-only' | 'requires-checkpoint' | 'requires-isolation' | 'unknown';
+interface IReversibleExecutionOptions {
+    mode: 'local-first';
+    isolation?: TReversibleExecutionIsolation;
+    enforceUntrackedSideEffects?: boolean;
 }
-interface IEditCheckpointFileRecord {
-    originalPath: string;
-    existed: boolean;
-    snapshotFile?: string;
+interface IReversibleToolSafetyContext {
+    checkpointAvailable: boolean;
+    isolation: TReversibleExecutionIsolation;
 }
-interface IEditCheckpointManifest extends IEditCheckpointSummary {
-    version: 1;
-    files: IEditCheckpointFileRecord[];
+interface IReversibleToolSafetyInput {
+    toolName: string;
+    toolArgs?: TToolArgs;
+    context: IReversibleToolSafetyContext;
 }
-interface IEditCheckpointRestoreResult {
-    target: IEditCheckpointSummary;
-    restoredCheckpointCount: number;
-    restoredFileCount: number;
-    removedCheckpointCount: number;
+interface IReversibleToolSafetyReport {
+    toolName: string;
+    reversible: boolean;
+    sideEffect: TReversibleSideEffect;
+    rollbackLayer: TReversibleRollbackLayer;
+    status: TReversibleSafetyStatus;
+    message: string;
 }
+declare function evaluateReversibleToolSafety(input: IReversibleToolSafetyInput): IReversibleToolSafetyReport;
+declare function wrapReversibleExecutionTools(tools: readonly IToolWithEventService[], options: IReversibleExecutionOptions & {
+    checkpointAvailable: boolean;
+}): IToolWithEventService[];
 
 /**
  * Session factory — assembles a fully-configured Session from config, context,
@@ -1074,6 +1632,7 @@ interface IEditCheckpointRestoreResult {
  * expects as pre-constructed dependencies.
  */
 
+type TAutoCompactThreshold = number | false;
 /** Options for the createSession factory */
 interface ICreateSessionOptions {
     /** Resolved CLI configuration (model, API key, permissions) */
@@ -1121,8 +1680,12 @@ interface ICreateSessionOptions {
     }) => void;
     /** Callback when context is compacted */
     onCompact?: (summary: string) => void;
+    /** Callback with structured compaction metadata */
+    onCompactEvent?: (event: ICompactEvent) => void;
     /** Instructions to include in the compaction prompt (e.g. from CLAUDE.md) */
     compactInstructions?: string;
+    /** Auto-compact threshold as a 0-1 fraction. Set false to disable automatic compaction. */
+    autoCompactThreshold?: TAutoCompactThreshold;
     /** Custom system prompt builder function */
     systemPromptBuilder?: (params: ISystemPromptParams) => string;
     /** Custom tool descriptions for the system prompt */
@@ -1149,6 +1712,8 @@ interface ICreateSessionOptions {
     commandDescriptors?: ICapabilityDescriptor[];
     /** Recorder used to snapshot files before Write/Edit tools mutate them. */
     editCheckpointRecorder?: IEditCheckpointRecorder;
+    /** Opt-in local-first reversible execution policy for write/shell tools. */
+    reversibleExecution?: IReversibleExecutionOptions;
 }
 
 /**
@@ -1229,63 +1794,6 @@ declare function createSubagentLogger(parentSessionId: string, _agentId: string,
  */
 declare function resolveSubagentLogDir(parentSessionId: string, baseLogsDir: string): string;
 
-declare const MEMORY_INDEX_MAX_LINES = 200;
-declare const MEMORY_INDEX_MAX_BYTES: number;
-type TMemoryType = 'user' | 'feedback' | 'project' | 'reference';
-interface IStartupMemory {
-    content: string;
-    path: string;
-    lineCount: number;
-    truncated: boolean;
-}
-interface IMemoryTopicSummary {
-    name: string;
-    path: string;
-}
-interface IProjectMemorySummary {
-    indexPath: string;
-    topicsPath: string;
-    topics: IMemoryTopicSummary[];
-}
-interface IAppendMemoryInput {
-    type: TMemoryType;
-    topic: string;
-    text: string;
-}
-interface IAppendMemoryResult {
-    indexPath: string;
-    topicPath: string;
-    topic: string;
-    deduplicated: boolean;
-}
-declare function isMemoryType(value: string): value is TMemoryType;
-declare class ProjectMemoryStore {
-    private readonly cwd;
-    private readonly now;
-    constructor(cwd: string, now?: () => Date);
-    getIndexPath(): string;
-    getTopicsPath(): string;
-    loadStartupMemory(): IStartupMemory;
-    list(): IProjectMemorySummary;
-    readTopic(topic: string): string;
-    append(input: IAppendMemoryInput): IAppendMemoryResult;
-}
-
-interface IMemoryReference {
-    topic: string;
-    path: string;
-    score: number;
-    truncated: boolean;
-}
-interface IMemoryEvent {
-    type: 'memory_candidate_extracted' | 'memory_candidate_queued' | 'memory_candidate_saved' | 'memory_candidate_skipped' | 'memory_candidate_approved' | 'memory_candidate_rejected' | 'memory_retrieved';
-    at: string;
-    candidateId?: string;
-    topic?: string;
-    reason?: string;
-    data?: Record<string, TUniversalValue>;
-}
-
 /**
  * Session initialization helpers for InteractiveSession.
  *
@@ -1316,6 +1824,8 @@ interface IInteractiveSessionStandardOptions {
     subagentRunnerFactory?: TSubagentRunnerFactory;
     /** Optional command modules composed into this session. */
     commandModules?: readonly ICommandModule[];
+    /** Host adapters available to composed command modules. */
+    commandHostAdapters?: ICommandHostAdapters;
     /** Model-visible command descriptors derived from the composed command executor. */
     commandDescriptors?: readonly ICapabilityDescriptor[];
     /** Model command execution bridge. */
@@ -1324,6 +1834,8 @@ interface IInteractiveSessionStandardOptions {
     isModelCommandInvocable?: (command: string) => boolean;
     /** Preloaded config to avoid duplicate discovery when caller needs it too. */
     config?: IResolvedConfig;
+    /** Opt-in local-first reversible execution policy for write/shell tools. */
+    reversibleExecution?: IReversibleExecutionOptions;
 }
 /** Test/advanced construction: inject pre-built session directly. */
 interface IInteractiveSessionInjectedOptions {
@@ -1339,6 +1851,8 @@ interface IInteractiveSessionInjectedOptions {
     forkSession?: boolean;
     /** Optional command modules composed into this injected session. */
     commandModules?: readonly ICommandModule[];
+    /** Host adapters available to composed command modules. */
+    commandHostAdapters?: ICommandHostAdapters;
 }
 /** Union of standard and injected construction options. */
 type IInteractiveSessionOptions = IInteractiveSessionStandardOptions | IInteractiveSessionInjectedOptions;
@@ -1388,6 +1902,8 @@ declare class InteractiveSession {
     private backgroundJobUnsubscribe;
     private backgroundJobOrchestrator;
     private readonly commandModules;
+    private readonly commandHostAdapters?;
+    private autoCompactThresholdSource;
     private shuttingDown;
     private shutdownPromise;
     constructor(options: IInteractiveSessionOptions);
@@ -1398,16 +1914,8 @@ declare class InteractiveSession {
     off<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
     private emit;
     submit(input: string, displayInput?: string, rawInput?: string): Promise<void>;
-    executeCommand(name: string, args: string): Promise<{
-        message: string;
-        success: boolean;
-        data?: Record<string, unknown>;
-    } | null>;
-    executeModelCommand(name: string, args: string): Promise<{
-        message: string;
-        success: boolean;
-        data?: Record<string, unknown>;
-    } | null>;
+    executeCommand(name: string, args: string): Promise<ICommandResult | null>;
+    executeModelCommand(name: string, args: string): Promise<ICommandResult | null>;
     executeSkillCommand(skill: ICommand, args: string, displayInput?: string, rawInput?: string): Promise<ISkillExecutionResult>;
     listCommands(): Array<{
         name: string;
@@ -1428,11 +1936,19 @@ declare class InteractiveSession {
     getStreamingText(): string;
     getActiveTools(): IToolState[];
     getContextState(): IContextWindowState;
+    getAutoCompactThreshold(): number | false;
+    getAutoCompactThresholdSource(): TAutoCompactThresholdSource;
+    setAutoCompactThreshold(threshold: TAutoCompactThreshold$1, source?: TAutoCompactThresholdSource): void;
+    getCommandHostAdapters(): ICommandHostAdapters;
+    clearConversationHistory(): void;
+    compactContext(instructions?: string): Promise<void>;
     getName(): string | undefined;
     getCwd(): string;
     getSession(): Session;
     listEditCheckpoints(): IEditCheckpointSummary[];
+    inspectEditCheckpoint(checkpointId: string): IEditCheckpointInspection;
     restoreEditCheckpoint(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+    rollbackEditCheckpoint(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
     getUsedMemoryReferences(): IMemoryReference[];
     recordMemoryEvent(event: IMemoryEvent): void;
     listBackgroundTasks(filter?: IBackgroundTaskListFilter): IBackgroundTaskState[];
@@ -1484,11 +2000,13 @@ declare class InteractiveSession {
     private resolveForkAgentDefinition;
     private runSkillInFork;
     private applyForkSkillResult;
+    private executeForegroundCommand;
     private executePrompt;
     private getEditCheckpointStore;
     private beginEditCheckpointTurn;
     private finalizeEditCheckpointTurn;
     private handleTextDelta;
+    private handleCompactEvent;
     private handleToolExecution;
     private clearStreaming;
     private flushStreaming;
@@ -1529,32 +2047,6 @@ interface ICreateQueryOptions {
  */
 declare function createQuery(options: ICreateQueryOptions): (prompt: string) => Promise<string>;
 
-interface IEditCheckpointStoreOptions {
-    cwd: string;
-    now?: () => Date;
-}
-declare class EditCheckpointStore {
-    private readonly cwd;
-    private readonly rootDir;
-    private readonly now;
-    private activeTurn;
-    constructor(options: IEditCheckpointStoreOptions);
-    beginTurn(input: IEditCheckpointTurnInput): Promise<IEditCheckpointSummary>;
-    captureFile(filePath: string): Promise<void>;
-    finalizeTurn(): Promise<IEditCheckpointSummary | undefined>;
-    list(sessionId: string): IEditCheckpointSummary[];
-    restoreToCheckpoint(sessionId: string, checkpointId: string): Promise<IEditCheckpointRestoreResult>;
-    private createFileRecord;
-    private restoreFile;
-    private loadManifests;
-    private nextSequence;
-    private writeManifest;
-    private sessionDir;
-    private checkpointDir;
-}
-
-declare function wrapEditCheckpointTools(tools: readonly IToolWithEventService[], recorder: IEditCheckpointRecorder): IToolWithEventService[];
-
 type TSelfHostingVerificationPhase = 'checkpoint' | 'edit' | 'handoff' | 'verify' | 'recover';
 type TSelfHostingLoopState = 'idle' | 'checkpointed' | 'editing' | 'verifying' | 'passed' | 'failed' | 'rolled_back' | 'cancelled';
 type TSelfHostingLoopEvent = 'checkpoint_created' | 'edits_started' | 'edits_applied' | 'verify_passed' | 'verify_failed' | 'rollback_completed' | 'cancelled';
@@ -1698,4 +2190,4 @@ declare function updateTaskFileStatus(taskPath: string, status: TTaskFileStatus,
  */
 declare function promptForApproval(terminal: ITerminalOutput, toolName: string, toolArgs: TToolArgs): Promise<boolean>;
 
-export { AgentExecutor, BUILT_IN_AGENTS, BackgroundJobOrchestrator, BuiltinCommandSource, BundlePluginInstaller, BundlePluginLoader, CommandRegistry, EditCheckpointStore, type IAgentDefinition, type IAgentExecutorOptions, type IAgentSession, type IAgentToolDeps, type IAppendMemoryInput, type IAppendMemoryResult, type IBackgroundJobGroupCreateRequest, type IBackgroundJobGroupState, type IBackgroundJobGroupSummary, type IBackgroundJobOrchestratorOptions, type IBackgroundJobResultEnvelope, type IBackgroundProcessToolDeps, type IBundlePluginFeatures, type IBundlePluginInstallerOptions, type IBundlePluginManifest, type IBundleSkill, type ICapabilityDescriptor, type ICommand, type ICommandExecutionToolDeps, type ICommandModule, type ICommandResult, type ICommandSource, type ICreateQueryOptions, type IDiffLine, type IEditCheckpointFileRecord, type IEditCheckpointManifest, type IEditCheckpointRecorder, type IEditCheckpointRestoreResult, type IEditCheckpointSummary, type IEditCheckpointTurnInput, type IExecutionResult, type IForkExecutionOptions, type IInProcessSubagentRunnerDeps, type IInstalledPluginRecord, type IInstalledPluginsRegistry, type IInteractiveSessionEvents, type IInteractiveSessionOptions, type IInteractiveSessionShutdownOptions, type IKnownMarketplaceEntry, type IKnownMarketplacesRegistry, type ILoadedBundlePlugin, type IMarketplaceClientOptions, type IMarketplaceManifest, type IMarketplacePluginEntry, type IMarketplaceSource, type IPluginSettings, type IProjectMemorySummary, type IPromptExecutorOptions, type IPromptProvider, type ISelfHostingVerificationPlan, type ISelfHostingVerificationPlanInput, type ISelfHostingVerificationStep, type ISkillExecutionCallbacks, type ISkillExecutionResult, type IStartupMemory, type ISubagentOptions, type ISubagentPromptOptions, type ISystemCommand, type ITaskContextFile, type ITaskSelectionOptions, type IToolState, type IToolSummary, type ITransportAdapter, type IUpdateTaskFileStatusOptions, type IUsageSnapshot, InteractiveSession, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MarketplaceClient, PluginCommandSource, PluginSettingsStore, ProjectMemoryStore, PromptExecutor, SkillCommandSource, type SkillPromptContext, SystemCommandExecutor, type TBackgroundJobGroupEvent, type TBackgroundJobGroupEventListener, type TBackgroundJobGroupIdFactory, type TBackgroundJobGroupStatus, type TBackgroundJobWaitPolicy, type TCapabilityKind, type TCapabilitySafety, type TCommandModuleSessionRequirement, type TEnabledPlugins, type TInteractiveEventName, type TInteractivePermissionHandler, type TMemoryType, type TPermissionResultValue, type TProviderFactory, type TSelfHostingLoopEvent, type TSelfHostingLoopState, type TSelfHostingVerificationPhase, type TSessionFactory, type TSubagentRunnerFactory, type TTaskFileStatus, assembleSubagentPrompt, buildSkillPrompt, createAgentTool, createBackgroundProcessTool, createCommandExecutionTool, createDefaultTools, createQuery, createSubagentLogger, createSubagentSession, createSystemCommands, discoverTaskFiles, executeSkill, formatTaskContext, getBuiltInAgent, getForkWorkerSuffix, getSubagentSuffix, isMemoryType, loadTaskContext, parseFrontmatter, parseTaskFile, planSelfHostingVerification, preprocessShellCommands, projectPaths, promptForApproval, readCurrentGitBranch, resolveSubagentLogDir, retrieveAgentToolDeps, selectRelevantTasks, storeAgentToolDeps, substituteVariables, summarizeBackgroundJobGroup, transitionSelfHostingLoop, updateTaskFileStatus, userPaths, wrapEditCheckpointTools };
+export { AUTO_COMPACT_THRESHOLD_SETTINGS_KEY, AgentExecutor, BACKGROUND_COMMAND_DESCRIPTION, BACKGROUND_COMMAND_USAGE, BUILT_IN_AGENTS, BackgroundJobOrchestrator, BuiltinCommandSource, BundlePluginInstaller, BundlePluginLoader, CLEAR_COMMAND_DESCRIPTION, COST_COMMAND_DESCRIPTION, CommandRegistry, DEFAULT_AUTO_COMPACT_THRESHOLD, DEFAULT_STATUS_LINE_COMMAND_SETTINGS, EXIT_COMMAND_DESCRIPTION, EditCheckpointStore, HELP_COMMAND_DESCRIPTION, type IAgentDefinition, type IAgentExecutorOptions, type IAgentSession, type IAgentToolDeps, type IAppendMemoryInput, type IAppendMemoryResult, type IBackgroundJobGroupCreateRequest, type IBackgroundJobGroupState, type IBackgroundJobGroupSummary, type IBackgroundJobOrchestratorOptions, type IBackgroundJobResultEnvelope, type IBackgroundProcessToolDeps, type IBundlePluginFeatures, type IBundlePluginInstallerOptions, type IBundlePluginManifest, type IBundleSkill, type ICapabilityDescriptor, type ICommand, type ICommandAvailablePlugin, type ICommandChoicePromptOption, type ICommandExecutionToolDeps, type ICommandHostAdapters, type ICommandHostContext, type ICommandInstalledPlugin, type ICommandInteraction, type ICommandListEntry, type ICommandMarketplaceSource, type ICommandMemoryStores, type ICommandModule, type ICommandPendingMemoryStore, type ICommandPermissionModeAdapter, type ICommandPickerAdapter, type ICommandPluginAdapter, type ICommandPluginReloadResult, type ICommandProcessAdapter, type ICommandProjectMemoryStore, type ICommandResult, type ICommandSessionInfo, type ICommandSessionRuntime, type ICommandSettingsAdapter, type ICommandSettingsDocument, type ICommandSource, type ICompactContextResult, type ICreateQueryOptions, type IDiffLine, type IEditCheckpointFileInspection, type IEditCheckpointFileRecord, type IEditCheckpointInspection, type IEditCheckpointInspectionPlan, type IEditCheckpointManifest, type IEditCheckpointRecorder, type IEditCheckpointRestoreResult, type IEditCheckpointSummary, type IEditCheckpointTurnInput, type IExecutionResult, type IForkExecutionOptions, type IInProcessSubagentRunnerDeps, type IInstalledPluginRecord, type IInstalledPluginsRegistry, type IInteractiveSessionEvents, type IInteractiveSessionOptions, type IInteractiveSessionShutdownOptions, type IKnownMarketplaceEntry, type IKnownMarketplacesRegistry, type ILegacyProviderSettings, type ILoadedBundlePlugin, type IMarketplaceClientOptions, type IMarketplaceManifest, type IMarketplacePluginEntry, type IMarketplaceSource, type IMemoryCandidate, type IMemoryEvent, type IMemoryPendingRecord, type IMemoryReference, type IPermissionsCommandState, type IPluginSettings, type IProjectMemorySummary, type IPromptExecutorOptions, type IPromptProvider, type IProviderCommandModuleOptions, type IProviderCommandSettingsAdapter, type IProviderProfileSettings, type IProviderSettingsBuildOptions, type IProviderSetupFlowState, type IProviderSetupInput, type IProviderSetupPatch, type IProviderSetupPromptStep, type IReversibleExecutionOptions, type IReversibleToolSafetyContext, type IReversibleToolSafetyInput, type IReversibleToolSafetyReport, type ISelfHostingVerificationPlan, type ISelfHostingVerificationPlanInput, type ISelfHostingVerificationStep, type ISkillExecutionCallbacks, type ISkillExecutionResult, type IStartupMemory, type IStatusLineCommandSettings, type ISubagentOptions, type ISubagentPromptOptions, type ISystemCommand, type ITaskContextFile, type ITaskSelectionOptions, type IToolState, type IToolSummary, type ITransportAdapter, type IUpdateTaskFileStatusOptions, type IUsageSnapshot, InteractiveSession, LANGUAGE_COMMAND_ARGUMENT_HINT, LANGUAGE_COMMAND_DESCRIPTION, MEMORY_COMMAND_ARGUMENT_HINT, MEMORY_COMMAND_DESCRIPTION, MEMORY_COMMAND_USAGE, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MODEL_COMMAND_ARGUMENT_HINT, MODEL_COMMAND_DESCRIPTION, MarketplaceClient, PERMISSIONS_COMMAND_DESCRIPTION, PERMISSION_MODE_ARGUMENT_HINT, PERMISSION_MODE_COMMAND_DESCRIPTION, PLUGIN_COMMAND_ARGUMENT_HINT, PLUGIN_COMMAND_DESCRIPTION, PluginCommandSource, PluginSettingsStore, ProjectMemoryStore, PromptExecutor, RECOMMENDED_RESPONSE_LANGUAGES, RELOAD_PLUGINS_COMMAND_DESCRIPTION, RENAME_COMMAND_DESCRIPTION, RENAME_COMMAND_USAGE, RESUME_COMMAND_DESCRIPTION, REWIND_COMMAND_ARGUMENT_HINT, REWIND_COMMAND_DESCRIPTION, STATUSLINE_COMMAND_ARGUMENT_HINT, STATUSLINE_COMMAND_DESCRIPTION, SkillCommandSource, type SkillPromptContext, SystemCommandExecutor, type TAutoCompactThreshold$1 as TAutoCompactThreshold, type TAutoCompactThresholdSource, type TBackgroundJobGroupEvent, type TBackgroundJobGroupEventListener, type TBackgroundJobGroupIdFactory, type TBackgroundJobGroupStatus, type TBackgroundJobWaitPolicy, type TCapabilityKind, type TCapabilitySafety, type TCommandEffect, type TCommandInteractionPrompt, type TCommandModuleSessionRequirement, type TCommandResultDataValue, type TEditCheckpointFileRestoreAction, type TEnabledPlugins, type TInteractiveEventName, type TInteractivePermissionHandler, type TMemoryCandidateStatus, type TMemoryType, type TPermissionResultValue, type TPluginInstallScope, type TPromptInput, type TProviderFactory, type TProviderSettingsDocument, type TProviderSetupFlowSubmitResult, type TProviderSetupType, type TRecommendedResponseLanguage, type TReversibleExecutionIsolation, type TReversibleRollbackLayer, type TReversibleSafetyStatus, type TReversibleSideEffect, type TSelfHostingLoopEvent, type TSelfHostingLoopState, type TSelfHostingVerificationPhase, type TSessionFactory, type TStatusLineCommandSettingsPatch, type TSubagentRunnerFactory, type TSystemCommandLifecycle, type TTaskFileStatus, VALID_PERMISSION_MODES, assembleSubagentPrompt, buildBackgroundCommandSubcommands, buildLanguageCommandSubcommands, buildMemoryCommandSubcommands, buildModelCommandSubcommands, buildPermissionModeSubcommands, buildPluginCommandSubcommands, buildProviderProfile, buildProviderSetupPatch, buildRewindCommandSubcommands, buildSkillPrompt, buildStatusLineCommandSubcommands, cancelCommandBackgroundTask, clearConversationHistory, closeCommandBackgroundTask, compactCommandContext, createAgentTool, createBackgroundProcessTool, createBuiltinCommandModule, createCommandExecutionTool, createCommandMemoryStores, createCommandPendingMemoryStore, createCommandProjectMemoryStore, createDefaultTools, createPluginRegistryReloadRequestedEffect, createPluginTuiRequestedEffect, createProviderSetupFlow, createQuery, createSessionExitRequestedEffect, createSessionPickerRequestedEffect, createSessionRenamedEffect, createSubagentLogger, createSubagentSession, createSystemCommands, discoverTaskFiles, evaluateReversibleToolSafety, executeSkill, formatCommandBackgroundTask, formatCommandBackgroundTaskList, formatCommandHelpMessage, formatCommandPermissionsMessage, formatEnvReference, formatInvalidPermissionModeMessage, formatLanguageUsageMessage, formatProviderSetupChoiceLabel, formatProviderSetupPromptLabel, formatProviderSetupSelectionPrompt, formatTaskContext, getBuiltInAgent, getForkWorkerSuffix, getProviderSetupStep, getSubagentSuffix, hasSensitiveCommandMemoryContent, hasUsableSecretReference, inspectCommandEditCheckpoint, isCommandMemoryType, isEnvReference, isMemoryType, isPermissionMode, isStatusLineCommandSettingsPatch, listCommandBackgroundTasks, listCommandEditCheckpoints, listCommandSessionAllowedTools, listCommandUsedMemoryReferences, loadTaskContext, mergeProviderPatch, parseCommandBackgroundLogCursor, parseFrontmatter, parseLanguageArgument, parsePermissionModeArgument, parseSessionNameArgument, parseTaskFile, planSelfHostingVerification, preprocessShellCommands, probeProviderProfile, projectPaths, promptForApproval, readAutoCompactThreshold, readAutoCompactThresholdSource, readCommandBackgroundTaskLog, readCommandContextState, readCommandPermissionMode, readCommandPermissionsState, readCommandSessionInfo, readCurrentGitBranch, recordCommandMemoryEvent, resetAutoCompactThresholdSetting, resolveEnvReference, resolvePermissionModeAdapter, resolvePluginCommandAdapter, resolveProviderSetupSelection, resolveSubagentLogDir, restoreCommandEditCheckpoint, retrieveAgentToolDeps, rollbackCommandEditCheckpoint, runProviderSetupPromptFlow, selectRelevantTasks, setCommandAutoCompactThreshold, setCurrentProvider, storeAgentToolDeps, submitProviderSetupValue, substituteVariables, summarizeBackgroundJobGroup, testProviderProfileCommand, transitionSelfHostingLoop, updateTaskFileStatus, upsertProviderProfile, userPaths, validateProviderProfile, validateProviderSetupValue, wrapEditCheckpointTools, wrapReversibleExecutionTools, writeAutoCompactThresholdSetting, writeCommandPermissionMode };