@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/dist/types/session/session-manager.d.ts

@@ -0,0 +1,988 @@
+import { type AgentMessage } from "@sayknow-cli/agent-core";
+import type { ConfiguredModelChainEntry as SharedConfiguredModelChainEntry } from "@sayknow-cli/agent-core/compaction";
+import type { ImageContent, Message, MessageAttribution, ServiceTier, TextContent } from "@sayknow-cli/ai";
+import * as native from "@sayknow-cli/natives";
+import type { TtsrInjectionRecord } from "../export/ttsr";
+import type { ManagedLegacyLocalMigrationSource } from "../internal-urls/local-protocol";
+import { ArtifactManager } from "./artifacts";
+import { type BlobPutResult, BlobStore } from "./blob-store";
+import { type ManagedMigrationPolicy } from "./internal/managed-session-scope";
+import { type ManagedDirectoryRoot, ManagedSessionDescendantStore } from "./internal/managed-session-storage";
+import { type BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages";
+import { type SessionManagerReadAccess, sessionManagerReadCapability } from "./session-manager-internal";
+import type { ManagedSessionSecurityContext, SessionStorage, SessionStorageStat, VerifiedSessionDeleteResult, VerifiedSessionDeleteTarget } from "./session-storage";
+export declare const CURRENT_SESSION_VERSION = 5;
+export interface SessionHeader {
+    type: "session";
+    version?: number;
+    id: string;
+    title?: string;
+    titleSource?: "auto" | "user";
+    timestamp: string;
+    cwd: string;
+    parentSession?: string;
+}
+export interface NewSessionOptions {
+    parentSession?: string;
+    /** Skip flushing the current session and delete it instead of saving. */
+    drop?: boolean;
+}
+export interface SessionEntryBase {
+    type: string;
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export interface ColdSpillRef {
+    kind: "cold_spill";
+    ref: string;
+    encoding: "utf8" | "json";
+    originalChars: number;
+    sha256: string;
+    bytes: number;
+}
+export interface EvictedContentMarker {
+    evictedAt: number;
+    reason: "compacted_history";
+    compactionEntryId: string;
+    firstKeptEntryId: string;
+    payloads: Record<string, ColdSpillRef>;
+}
+export interface EvictCompactedContentResult {
+    evictedEntries: number;
+    hotCharsRemoved: number;
+    coldBlobBytes: number;
+    payloadRefs: number;
+    alreadyEvictedEntries: number;
+    coldSpillWriteCount: number;
+    coldSpillReadCount: number;
+    residentTextReadCount: number;
+    residentImageReadCount: number;
+}
+export interface SessionManagerObservabilityStats {
+    coldSpillWriteCount: number;
+    coldSpillReadCount: number;
+    residentTextReadCount: number;
+    residentImageReadCount: number;
+    publicMaterializerCallCount: number;
+    getEntryMaterializerCallCount: number;
+    getBranchMaterializerCallCount: number;
+    getEntriesMaterializerCallCount: number;
+    materializedEntriesCachePopulateCount: number;
+    pathOnlyContextBuildCount: number;
+}
+export interface SessionMessageEntry extends SessionEntryBase {
+    type: "message";
+    message: AgentMessage;
+    /** Cold-spill marker: when present, heavy message content was moved to durable
+     *  content-addressed blobs after compaction. The marker is entry-level session
+     *  metadata (not a message field) so strict message types stay intact. */
+    evictedContent?: EvictedContentMarker;
+}
+export declare function associateSessionMessageEntryId(message: AgentMessage, entryId: string): void;
+export declare function getSessionMessageEntryId(message: AgentMessage): string | undefined;
+export declare function associateSessionMessageObservationId(message: AgentMessage, observationId: string): string;
+export declare function getSessionMessageObservationId(message: AgentMessage): string | undefined;
+export declare function associateSessionMessageViewportAnchorId(message: AgentMessage, anchorId: string): void;
+export declare function getSessionMessageViewportAnchorId(message: AgentMessage): string | undefined;
+/** Returns registered viewport anchors for durable user messages in session order. */
+export declare function getUserMessageViewportAnchorIds(messages: readonly AgentMessage[]): string[];
+export declare function transferSessionMessageIdentity(source: AgentMessage[], target: AgentMessage[]): void;
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+    type: "thinking_level_change";
+    thinkingLevel?: string | null;
+}
+export interface ModelChangeEntry extends SessionEntryBase {
+    type: "model_change";
+    /** Model in "provider/modelId" format */
+    model: string;
+    /** Role: "default" or an agent role. Undefined treated as "default" */
+    role?: string;
+    /** Requested model before a runtime substitution/fallback, in "provider/modelId" format. */
+    previousModel?: string;
+    /** Machine-readable reason for runtime model substitution/fallback. */
+    reason?: string;
+    /** Effective thinking level when the change was recorded. */
+    thinkingLevel?: string | null;
+}
+/** Persisted configured fallback chain for one model role. */
+export type ConfiguredModelChainEntry = SharedConfiguredModelChainEntry;
+export type ConfiguredModelChain = Pick<ConfiguredModelChainEntry, "role" | "entries" | "origin" | "identity" | "explicitHead" | "cleared">;
+export interface ServiceTierChangeEntry extends SessionEntryBase {
+    type: "service_tier_change";
+    serviceTier: ServiceTier | null;
+}
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+    type: "compaction";
+    summary: string;
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+    /** Hook-provided data to persist across compaction */
+    preserveData?: Record<string, unknown>;
+    /** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
+    fromExtension?: boolean;
+}
+export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
+    type: "branch_summary";
+    fromId: string;
+    summary: string;
+    /** Extension-specific data (not sent to LLM) */
+    details?: T;
+    /** True if generated by an extension, false if pi-generated */
+    fromExtension?: boolean;
+}
+/**
+ * Custom entry for extensions to store extension-specific data in the session.
+ * Use customType to identify your extension's entries.
+ *
+ * Purpose: Persist extension state across session reloads. On reload, extensions can
+ * scan entries for their customType and reconstruct internal state.
+ *
+ * Does NOT participate in LLM context (ignored by buildSessionContext).
+ * For injecting content into context, see CustomMessageEntry.
+ */
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+    type: "custom";
+    customType: string;
+    data?: T;
+}
+/** Label entry for user-defined bookmarks/markers on entries. */
+export interface LabelEntry extends SessionEntryBase {
+    type: "label";
+    targetId: string;
+    label: string | undefined;
+}
+/** TTSR injection entry - tracks which time-traveling rules have been injected this session. */
+export interface TtsrInjectionEntry extends SessionEntryBase {
+    type: "ttsr_injection";
+    /** Names of rules that were injected */
+    injectedRules: string[];
+    /** Rich rule injection records with repeat state. */
+    injectedRuleRecords?: TtsrInjectionRecord[];
+    /** TTSR manager message count when this injection was recorded. */
+    ttsrMessageCount?: number;
+}
+/** Persisted MCP discovery selection state for a session branch. */
+export interface MCPToolSelectionEntry extends SessionEntryBase {
+    type: "mcp_tool_selection";
+    /** MCP tool names selected for visibility in discovery mode. */
+    selectedToolNames: string[];
+    /** Legacy v4 combined built-in authority, retained for read compatibility. */
+    selectedDiscoveredBuiltinToolNames?: string[];
+    /** Correlates the ordered MCP and built-in entries emitted by one combined activation. */
+    mutationCorrelationId?: string;
+}
+/** Persisted discovered-built-in selection state, independent of MCP authority. */
+export interface DiscoveredBuiltinToolSelectionEntry extends SessionEntryBase {
+    type: "discovered_builtin_tool_selection";
+    selectedToolNames: string[];
+    /** Correlates the ordered MCP and built-in entries emitted by one combined activation. */
+    mutationCorrelationId?: string;
+}
+/** Session init entry - captures initial context for subagent sessions (debugging/replay). */
+export interface SessionInitEntry extends SessionEntryBase {
+    type: "session_init";
+    /** Full system prompt sent to the model */
+    systemPrompt: string;
+    /** Initial task/user message */
+    task: string;
+    /** Tools available to the agent */
+    tools: string[];
+    /** Output schema if structured output was requested */
+    outputSchema?: unknown;
+    /** Fork-context seed metadata for subagent debugging/replay. */
+    forkContext?: unknown;
+}
+/** Mode change entry - tracks agent mode transitions (e.g. plan mode). */
+export interface ModeChangeEntry extends SessionEntryBase {
+    type: "mode_change";
+    /** Current mode name, or "none" when exiting a mode */
+    mode: string;
+    /** Optional mode-specific data (e.g. plan file path) */
+    data?: Record<string, unknown>;
+}
+/**
+ * Custom message entry for extensions to inject messages into LLM context.
+ * Use customType to identify your extension's entries.
+ *
+ * Unlike CustomEntry, this DOES participate in LLM context.
+ * The content participates in LLM context through convertToLlm().
+ * Use details for extension-specific metadata (not sent to LLM).
+ *
+ * display controls TUI rendering:
+ * - false: hidden entirely
+ * - true: rendered with distinct styling (different from user messages)
+ */
+export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    details?: T;
+    display: boolean;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Cold-spill marker for custom-message content evicted after compaction. */
+    evictedContent?: EvictedContentMarker;
+}
+/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | DiscoveredBuiltinToolSelectionEntry | SessionInitEntry | ModeChangeEntry | ConfiguredModelChainEntry;
+/** Append-only replacement for mutable fields on the session header. */
+export interface HeaderPatchRecord {
+    type: "header_patch";
+    patch: Partial<Pick<SessionHeader, "title" | "titleSource" | "cwd">>;
+}
+/** Append-only replacement for replay metadata on one existing session entry. */
+export interface EntryPatchRecord {
+    type: "entry_patch";
+    entryId: string;
+    patch: Partial<Pick<SessionMessageEntry, "message">>;
+}
+export type SessionPatchRecord = HeaderPatchRecord | EntryPatchRecord;
+/** Resolved file entries; patch records are applied by parseSessionEntries(). */
+export type FileEntry = SessionHeader | SessionEntry;
+export type DefaultModelSelectionStage = {
+    readonly entryRevision: number;
+    readonly headerExportRevision: number;
+    readonly sessionId: string;
+    readonly sessionFile: string | undefined;
+    readonly entries: readonly FileEntry[];
+    readonly tempPath: string | undefined;
+    readonly persistsToExistingFile: boolean;
+};
+export type DefaultModelSelectionPromotion = {
+    readonly kind: "promoted";
+} | {
+    readonly kind: "not_promoted";
+    readonly error?: Error;
+} | {
+    readonly kind: "unknown";
+    readonly error: Error;
+};
+/** Tree node for getTree() - defensive copy of session structure */
+export interface SessionTreeNode {
+    entry: SessionEntry;
+    children: SessionTreeNode[];
+    /** Resolved label for this entry, if any */
+    label?: string;
+}
+export interface SessionContext {
+    messages: AgentMessage[];
+    thinkingLevel?: string;
+    serviceTier?: ServiceTier;
+    /** Model roles: { default: "provider/modelId", small: "provider/modelId", ... } */
+    models: Record<string, string>;
+    /** Configured fallback chains for model roles on the active branch. */
+    configuredModelChains: Record<string, ConfiguredModelChain>;
+    /** Names of TTSR rules that have been injected this session */
+    injectedTtsrRules: string[];
+    /** Rich TTSR rule injection records for repeat resume. */
+    injectedTtsrRuleRecords?: TtsrInjectionRecord[];
+    /** TTSR manager message count for repeat resume. */
+    ttsrMessageCount?: number;
+    /** MCP tool names selected through discovery for this session branch. */
+    selectedMCPToolNames: string[];
+    /** Built-in discoverable tool names activated through discovery, when explicitly persisted. */
+    selectedDiscoveredBuiltinToolNames?: string[];
+    /** Whether this branch contains an explicit persisted MCP selection entry. */
+    hasPersistedMCPToolSelection: boolean;
+    /** Whether this branch contains an explicit persisted discovered-built-in selection entry. */
+    hasPersistedDiscoveredBuiltinToolSelection?: boolean;
+    /** Active mode (e.g. "plan") or "none" if no special mode is active */
+    mode: string;
+    /** Mode-specific data from the last mode_change entry */
+    modeData?: Record<string, unknown>;
+}
+/** Immutable fingerprint captured during read-only resume inspection. */
+export interface ResumeSessionIdentity {
+    canonicalPath: string;
+    sessionId: string;
+    dev: bigint;
+    ino: bigint;
+    size: number;
+    mtimeMs: number;
+    mtimeNs: bigint;
+    sha256: string;
+}
+export interface ResumeTailResumable {
+    kind: "resumable";
+    identity: ResumeSessionIdentity;
+}
+export interface ResumeTailTerminal {
+    kind: "terminal";
+    identity: ResumeSessionIdentity;
+}
+export interface ResumeTailError {
+    kind: "error";
+    reason: "missing" | "malformed" | "unstable" | "read-failed" | "legacy_migration_disabled";
+}
+export type SessionDirectoryMigrationPolicy = ManagedMigrationPolicy;
+export declare class SessionManagedStorageError extends Error {
+    readonly code = "managed_storage_unsupported";
+    constructor();
+}
+export declare class SessionMigrationPolicyError extends Error {
+    readonly code = "legacy_migration_disabled";
+    constructor();
+}
+export type ResumeTailInspection = ResumeTailResumable | ResumeTailTerminal | ResumeTailError;
+export interface StrictSessionOpenSuccess {
+    kind: "opened";
+    manager: SessionManager;
+}
+export interface StrictSessionOpenFailure {
+    kind: "error";
+    reason: ResumeTailError["reason"] | "identity-mismatch" | "migration-required";
+}
+/** Exact transcript bytes and authority captured from one descriptor-bound read. */
+export interface CapturedSessionTranscriptSnapshot {
+    sourcePath: string;
+    identity: ResumeSessionIdentity;
+    content: Uint8Array;
+    storage: SessionStorage;
+}
+export type StrictSessionCaptureResult = {
+    kind: "captured";
+    snapshot: CapturedSessionTranscriptSnapshot;
+} | ResumeTailError;
+export type StrictSessionForkResult = {
+    kind: "forked";
+    manager: SessionManager;
+} | StrictSessionOpenFailure;
+/** Result of opening an inspected session without create-or-rewrite fallback. */
+export type StrictSessionOpenResult = StrictSessionOpenSuccess | StrictSessionOpenFailure;
+/**
+ * Capability returned only by a strict recovery hydration open. It represents
+ * immutable transcript authority and is consumed by the promotion seam.
+ */
+export interface RecoveryHydrationContext {
+    readonly identity: ResumeSessionIdentity;
+}
+export interface RecoveryHydrationOpenSuccess {
+    readonly kind: "hydrated";
+    readonly manager: SessionManager;
+    readonly context: RecoveryHydrationContext;
+}
+export type RecoveryHydrationOpenResult = RecoveryHydrationOpenSuccess | StrictSessionOpenFailure;
+export interface RecoveryHydrationPromotionFence {
+    /** The caller has durably published ownership and acquired its writer lease. */
+    readonly ownershipReady: true;
+}
+export interface SessionInfo {
+    path: string;
+    id: string;
+    /** Working directory where the session was started. Empty string for old sessions. */
+    cwd: string;
+    title?: string;
+    /** Path to the parent session (if this session was forked). */
+    parentSessionPath?: string;
+    created: Date;
+    modified: Date;
+    messageCount: number;
+    /** True when messageCount was counted from only the bounded list prefix. */
+    messageCountIsEstimate?: boolean;
+    /** File size in bytes on disk; used for compact list rendering. */
+    size: number;
+    firstMessage: string;
+    allMessagesText: string;
+}
+/** Kind of failure surfaced by strict scoped inventory. Any failure grants zero authority. */
+export type StrictInventoryFailureKind = "root" | "scan" | "lstat" | "read" | "parse" | "stat" | "header" | "cwd" | "containment" | "identity";
+/** Sanitized strict-inventory failure. Never carries raw file content. */
+export interface StrictInventoryFailure {
+    kind: StrictInventoryFailureKind;
+    message: string;
+    path?: string;
+}
+/** One exact-identity candidate suitable for ACP authorization binding. */
+export interface StrictInventoryCandidate {
+    /** Canonical absolute transcript path. */
+    path: string;
+    /** Session id parsed from the header. */
+    id: string;
+    /** Canonical cwd parsed from the header. */
+    cwd: string;
+    /** Descriptor-bound transcript identity (dev, ino, ...). */
+    identity: SessionStorageStat;
+}
+/**
+ * Strict inventory result. `complete` carries the full validated candidate set;
+ * `failure` carries every sanitized failure and grants zero page/cursor/authority.
+ * A failure result is never reduced to a partial candidate set.
+ */
+export type StrictInventoryResult = {
+    kind: "complete";
+    candidates: StrictInventoryCandidate[];
+} | {
+    kind: "failure";
+    failures: StrictInventoryFailure[];
+};
+/** Certainty-aware close outcome for strict ACP disposal. */
+export type SessionManagerCloseOutcome = {
+    kind: "closed";
+} | {
+    kind: "close_failed_retryable";
+    error: Error;
+} | {
+    kind: "close_unknown";
+    error: Error;
+};
+/** Read-only session state made available to extensions and custom tools. */
+/** Frozen read-only session facade made available to extensions and custom tools. */
+export interface ReadonlySessionManager {
+    getCwd(): string;
+    getSessionDir(): string;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    getSessionName(): string | undefined;
+    getArtifactsDir(): string | null;
+    getArtifactPath(id: string): Promise<string | null>;
+    getLeafId(): string | null;
+    getLeafEntry(): SessionEntry | undefined;
+    getEntry(id: string): SessionEntry | undefined;
+    getLabel(id: string): string | undefined;
+    getBranch(fromId?: string): SessionEntry[];
+    getHeader(): SessionHeader | null;
+    getEntries(): SessionEntry[];
+    getTree(): SessionTreeNode[];
+    getUsageStatistics(): UsageStatistics;
+}
+/** Creates an immutable facade that never exposes SessionManager mutation authority. */
+export declare function createReadonlySessionManager(manager: SessionManager): ReadonlySessionManager;
+/** Internal artifact-writing capability. Read-only facades expose it only through a private weak-map lookup. */
+export type SessionArtifactCapability = Readonly<Pick<SessionManager, "allocateArtifactPath" | "saveArtifact" | "putBlob">>;
+/**
+ * Returns the artifact capability for a concrete persistence owner or one of its
+ * immutable read-only facades. Structural lookalikes remain unauthorized.
+ */
+export declare function sessionArtifactCapability(value: unknown): SessionArtifactCapability | undefined;
+/** Exported for testing */
+export declare function migrateSessionEntries(entries: FileEntry[]): void;
+/** Exported for compaction.test.ts */
+export declare function parseSessionEntries(content: string): FileEntry[];
+export declare function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null;
+/**
+ * Build the session context from entries using tree traversal.
+ * If leafId is provided, walks from that entry to root.
+ * Handles compaction and branch summaries along the path.
+ */
+export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>, sessionIdentityNamespace?: string): SessionContext;
+/** A session directory's authority is distinct from its string path. */
+export type SessionDestination = {
+    readonly kind: "managed";
+    readonly directory: string;
+    readonly securityContext: ManagedSessionSecurityContext;
+} | {
+    readonly kind: "explicit";
+    readonly directory: string;
+};
+export type SessionDestinationInput = string | SessionDestination | undefined;
+interface ForkArtifactPublication {
+    readonly snapshot: native.NativeDirectoryTreeSnapshot;
+    readonly store: ManagedSessionDescendantStore;
+    readonly cleanupStore: ManagedSessionDescendantStore;
+    readonly cleanupRelativePath: string;
+}
+/** Exported for testing */
+export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
+declare class RecentSessionInfo {
+    #private;
+    readonly path: string;
+    readonly mtime: number;
+    constructor(path: string, mtime: number, header: Record<string, unknown>, firstPrompt?: string);
+    /** Display name. Falls back to a timestamp-based label, never the raw UUID. */
+    get fullName(): string;
+    /**
+     * Display name without an arbitrary length cap. The renderer is responsible for
+     * width-aware truncation so adjacent fields (e.g. the relative time) stay visible.
+     */
+    get name(): string;
+    /** Human-readable relative time (e.g., "2 hours ago") */
+    get timeAgo(): string;
+}
+/**
+ * Promote orphaned `<basename>.jsonl.<snowflake>.bak` backups created by
+ * `#replaceSessionFileAfterEperm` back to their primary path when the primary
+ * is missing. This runs once per session-dir scan, before the main `*.jsonl`
+ * glob, so a crash between the two renames in the EPERM-rewrite path does not
+ * leave the user's last good state stranded outside the loader's view.
+ *
+ * Exported for testing.
+ */
+export declare function recoverOrphanedBackups(sessionDir: string, storage: SessionStorage): Promise<void>;
+/** Exported for testing */
+export declare function findMostRecentSession(sessionDir: string, storage?: SessionStorage): Promise<string | null>;
+interface SessionMoveDirectoryHandle {
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function syncSessionMoveDirectory(directory: string, platform?: NodeJS.Platform, openDirectory?: (directory: string) => Promise<SessionMoveDirectoryHandle>): Promise<void>;
+declare const RESIDENT_BLOB_SENTINEL_KEY = "__skcResidentBlob";
+type ResidentBlobKind = "text" | "imageUrl" | "imageData";
+interface ResidentBlobSentinel {
+    [RESIDENT_BLOB_SENTINEL_KEY]: true;
+    kind: ResidentBlobKind;
+    ref: string;
+}
+export declare function residentBlobSentinelForTests(kind: ResidentBlobKind, ref: string): ResidentBlobSentinel;
+export declare function materializeResidentEntriesForPersistenceForTests<T>(entries: T[], textStore: BlobStore, imageStore?: BlobStore): T[];
+/** Get recent sessions for display in welcome screen */
+export declare function getRecentSessions(sessionDir: string, limit?: number, storage?: SessionStorage): Promise<RecentSessionInfo[]>;
+/**
+ * Manages conversation sessions as append-only trees stored in JSONL files.
+ *
+ * Each session entry has an id and parentId forming a tree structure. The "leaf"
+ * pointer tracks the current position. Appending creates a child of the current leaf.
+ * Branching moves the leaf to an earlier entry, allowing new branches without
+ * modifying history.
+ *
+ * Use buildSessionContext() to get the resolved message list for the LLM, which
+ * handles compaction summaries and follows the path from root to current leaf.
+ */
+export interface UsageStatistics {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    premiumRequests: number;
+    cost: number;
+}
+export interface ResolvedSessionMatch {
+    session: SessionInfo;
+    scope: "local" | "global";
+}
+export declare function resolveResumableSession(sessionArg: string, cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<ResolvedSessionMatch | undefined>;
+interface SessionManagerStateSnapshot {
+    sessionId: string;
+    sessionName: string | undefined;
+    titleSource: "auto" | "user" | undefined;
+    sessionFile: string | undefined;
+    flushed: boolean;
+    ensuredOnDisk: boolean;
+    needsFullRewriteOnNextPersist: boolean;
+    fileEntries: FileEntry[];
+    materializedFileEntries: FileEntry[];
+}
+export declare class SessionManager {
+    #private;
+    private cwd;
+    private sessionDir;
+    private readonly persist;
+    private readonly storage;
+    private destination;
+    private constructor();
+    /**
+     * Snapshot of the five cache-invalidation revision domains (plan: Lane 1
+     * revision contract). Tests assert the invalidation mapping through this;
+     * future export/label-view caches key off their respective domains.
+     */
+    revisionSnapshot(): {
+        entry: number;
+        leaf: number;
+        headerExport: number;
+        label: number;
+        replayMetadata: number;
+    };
+    /** Puts a binary blob into the blob store and returns the blob reference */
+    putBlob(data: Buffer): Promise<BlobPutResult>;
+    captureState(): SessionManagerStateSnapshot;
+    restoreState(snapshot: SessionManagerStateSnapshot): void;
+    /** Switch to a different session file (used for resume and branching) */
+    setSessionFile(sessionFile: string): Promise<void>;
+    /** Start a new session. Closes any existing writer first. */
+    newSession(options?: NewSessionOptions): Promise<string | undefined>;
+    /** Tombstone and exact-delete managed transcripts, detaching the active transcript first. */
+    dropSession(sessionPath: string): Promise<void>;
+    /**
+     * Exact-delete a session transcript and its artifacts by path WITHOUT requiring
+     * managed logical authorization. This is only for discarding an UNCOMMITTED
+     * successor that a transaction (e.g. handoff) created via `newSession()` but
+     * never durably authorized — such a session has no managed candidate listing
+     * yet, so `dropSession` would refuse it and leak its resident-cache/artifact
+     * root. Bounded to this manager's configured session root and refuses to touch
+     * the active session; tolerates missing files.
+     */
+    discardUncommittedSession(sessionPath: string): Promise<void>;
+    /**
+     * Fork the current session, creating a new session file with the same entries.
+     * Returns both the old and new session file paths for artifact copying.
+     * @returns { oldSessionFile, newSessionFile } or undefined if not persisting
+     */
+    fork(): Promise<{
+        oldSessionFile: string;
+        newSessionFile: string;
+    } | undefined>;
+    copyArtifactsForFork(oldSessionFile: string, newSessionFile: string): Promise<ForkArtifactPublication | undefined>;
+    /**
+     * Move the session to a new working directory.
+     * Moves session files and artifacts on disk, updates all internal references,
+     * and rewrites the session header with the new cwd.
+     */
+    moveTo(newCwd: string): Promise<void>;
+    isPersisted(): boolean;
+    stageDefaultModelSelection(model: string, thinkingLevel: string | undefined, options?: {
+        readonly appendThinkingLevel: boolean;
+    }): Promise<DefaultModelSelectionStage>;
+    promoteDefaultModelSelection(stage: DefaultModelSelectionStage): DefaultModelSelectionPromotion;
+    discardDefaultModelSelectionStage(stage: DefaultModelSelectionStage): Promise<void>;
+    /**
+     * Force-persist all current entries to disk, even when no assistant message exists yet.
+     * Used by ACP mode where session/new must create a discoverable session immediately.
+     */
+    ensureOnDisk(): Promise<void>;
+    /** Flush pending writes to disk. Call before switching sessions or on shutdown. */
+    flush(): Promise<void>;
+    /** Close the persistent writer after flushing all pending data. */
+    close(): Promise<void>;
+    /** Flush while open, then strictly close; retryable close skips the invalid second flush. */
+    flushAndCloseStrict(): Promise<SessionManagerCloseOutcome>;
+    /**
+     * Strictly flush and close the persist writer, returning the certainty-aware close
+     * outcome without manufacturing success. The existing {@link close} path is
+     * preserved for best-effort callers; this seam lets strict ACP disposal prove
+     * writer closure before any destructive operation.
+     */
+    closeStrict(): Promise<SessionManagerCloseOutcome>;
+    getCwd(): string;
+    /** Get usage statistics across all assistant messages in the session. */
+    getUsageStatistics(): UsageStatistics;
+    getSessionDir(): string;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    /**
+     * Returns the session artifacts directory path (session file path without .jsonl).
+     * Returns null when the session is not persisted to a file.
+     * When this session has adopted an external ArtifactManager (subagent case),
+     * never exposes that managed directory as a pathname. Reads and writes use the
+     * adopted manager capability directly.
+     */
+    getArtifactsDir(): string | null;
+    isManagedDestination(): boolean;
+    /** Supplies opaque retained authority for mandatory managed legacy local migration. */
+    getManagedLegacyLocalMigrationSource(): ManagedLegacyLocalMigrationSource | null;
+    /**
+     * Adopt an externally-owned ArtifactManager. Used by subagents to share
+     * the parent session's artifact directory and ID counter.
+     */
+    adoptArtifactManager(manager: ArtifactManager): void;
+    /**
+     * Returns the ArtifactManager this session writes through. Lazily creates
+     * one bound to the current session file unless an external manager was
+     * adopted via `adoptArtifactManager`. Returns null only for non-persistent
+     * sessions with no adopted manager.
+     */
+    getArtifactManager(): ArtifactManager | null;
+    /**
+     * Allocate a new artifact path and ID for the current session.
+     * Returns an empty object when the session is not persisted.
+     */
+    allocateArtifactPath(toolType: string): Promise<{
+        id?: string;
+        path?: string;
+    }>;
+    /**
+     * Save artifact content under the current session and return artifact ID.
+     * Returns an artifact ID for all sessions (file-backed for persistent, in-memory fallback otherwise).
+     */
+    saveArtifact(content: string, toolType: string): Promise<string | undefined>;
+    /**
+     * Resolve an artifact ID to an on-disk path for the current session.
+     * Returns null when missing or when the session is not persisted.
+     */
+    getArtifactPath(id: string): Promise<string | null>;
+    /**
+     * Persist (or clear) the current editor draft so the next resume of this
+     * session can restore it. Empty text deletes any stale draft. No-op when the
+     * session is not persisted.
+     */
+    saveDraft(text: string): Promise<void>;
+    /**
+     * Read and remove the saved draft. Returns the previously-saved text, or
+     * null when no draft is pending. Single-shot: a successful read removes the
+     * sidecar so a subsequent resume does not re-restore the same text.
+     */
+    consumeDraft(): Promise<string | null>;
+    /** The source that set the session name: "user" (manual /rename or RPC) or "auto" (generated title). */
+    get titleSource(): "auto" | "user" | undefined;
+    getSessionName(): string | undefined;
+    /**
+     * Set the session display name.
+     * @param source - "user" for explicit renames (/rename command, RPC); "auto" for generated titles.
+     *   Auto-generated titles are silently ignored when the user has already set a name.
+     */
+    setSessionName(name: string, source?: "auto" | "user"): Promise<boolean>;
+    _persist(entry: SessionEntry): void;
+    /** Append a configured fallback chain as child of current leaf, then advance leaf. Returns entry id. */
+    appendConfiguredModelChain(chain: ConfiguredModelChain): string;
+    /** Append a message as child of current leaf, then advance leaf. Returns entry id.
+     * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
+     * Reason: we want these to be top-level entries in the session, not message session entries,
+     * so it is easier to find them.
+     * These need to be appended via appendCompaction() and appendBranchSummary() methods.
+     */
+    appendMessage(message: Message | CustomMessage | HookMessage | BashExecutionMessage | PythonExecutionMessage | FileMentionMessage): string;
+    /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
+    appendThinkingLevelChange(thinkingLevel?: string): string;
+    appendServiceTierChange(serviceTier: ServiceTier | null): string;
+    /** Append a mode change as child of current leaf, then advance leaf. Returns entry id. */
+    appendModeChange(mode: string, data?: Record<string, unknown>): string;
+    /**
+     * Append a model change as child of current leaf, then advance leaf. Returns entry id.
+     * @param model Model in "provider/modelId" format
+     * @param role Optional role (default: "default")
+     */
+    appendModelChange(model: string, role?: string, metadata?: {
+        previousModel?: string;
+        reason?: string;
+        thinkingLevel?: string | null;
+    }): string;
+    /** Append session init metadata (for subagent debugging/replay). Returns entry id. */
+    appendSessionInit(init: {
+        systemPrompt: string;
+        task: string;
+        tools: string[];
+        outputSchema?: unknown;
+        forkContext?: unknown;
+    }): string;
+    /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
+    appendCompaction<T = unknown>(summary: string, shortSummary: string | undefined, firstKeptEntryId: string, tokensBefore: number, details?: T, fromExtension?: boolean, preserveData?: Record<string, unknown>): string;
+    /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
+    appendCustomEntry(customType: string, data?: unknown): string;
+    /**
+     * Append a root marker that starts a fresh active branch without changing the
+     * session id or deleting earlier durable entries. Subsequent messages descend
+     * from this marker, so provider context is clear while history remains
+     * available for diagnostics/export.
+     */
+    appendContextClearEntry(data?: Record<string, unknown>): string;
+    /**
+     * Write mutated message entries back into the canonical entry store by id.
+     *
+     * `getBranch()` materializes resident-blob entries into copies, so in-place
+     * mutation of returned entries (e.g. pruning tool outputs) does not affect
+     * the canonical store. This applies such mutations for real.
+     */
+    applyEntryMessageUpdates(entries: readonly SessionMessageEntry[]): void;
+    /** Write mutated custom-message entries back into the canonical entry store by id. */
+    applyCustomMessageEntryUpdates(entries: readonly CustomMessageEntry[]): void;
+    /**
+     * Rewrite the session file after in-place entry updates.
+     * Use sparingly (e.g., pruning old tool outputs).
+     */
+    rewriteEntries(): Promise<void>;
+    /**
+     * Append a custom message entry (for extensions) that participates in LLM context.
+     * @param customType Hook identifier for filtering on reload
+     * @param content Message content (string or TextContent/ImageContent array)
+     * @param display Whether to show in TUI (true = styled display, false = hidden)
+     * @param details Optional extension-specific metadata (not sent to LLM)
+     * @param attribution Who initiated this message for billing/attribution semantics
+     * @returns Entry id
+     */
+    appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T, attribution?: MessageAttribution, observationId?: string): string;
+    /** Append MCP discovery selection authority without altering discovered built-in authority. */
+    appendMCPToolSelection(selectedToolNames: string[], mutationCorrelationId?: string): string;
+    /** Append discovered built-in selection authority without altering MCP authority. */
+    appendDiscoveredBuiltinToolSelection(selectedToolNames: string[], mutationCorrelationId?: string): string;
+    /**
+     * Append a TTSR injection entry recording which rules were injected.
+     * @param ruleNames Names of rules that were injected
+     * @returns Entry id
+     */
+    appendTtsrInjection(ruleNames: string[], records?: TtsrInjectionRecord[], ttsrMessageCount?: number): string;
+    /**
+     * Get all unique TTSR rule names that have been injected in the current branch.
+     * Scans from root to current leaf for ttsr_injection entries.
+     */
+    getInjectedTtsrRules(): string[];
+    getLeafId(): string | null;
+    getLeafEntry(): SessionEntry | undefined;
+    getResidentImageBytes(): number;
+    /**
+     * Get the most recent model role from the current session path.
+     * Returns undefined if no model change has been recorded.
+     */
+    getLastModelChangeRole(): string | undefined;
+    evictCompactedContent(firstKeptEntryId: string, compactionEntryId: string): EvictCompactedContentResult;
+    getObservabilityStatsForTests(): SessionManagerObservabilityStats;
+    hotRetainedMessageCharsForTests(): number;
+    getCanonicalEntryForTests(id: string): SessionEntry | undefined;
+    getEntryForFidelity(id: string): SessionEntry | undefined;
+    getBranchForFidelity(fromId?: string): SessionEntry[];
+    /**
+     * Walk the active branch without materializing resident blobs or rehydrating
+     * cold-spill payloads. Intended for metadata-only scans such as todo-phase
+     * sync; callers must not mutate returned entries.
+     */
+    getActivePathEntriesCanonical(fromId?: string): SessionEntry[];
+    getEntriesForExport(): SessionEntry[];
+    getEntry(id: string): SessionEntry | undefined;
+    /**
+     * Get all direct children of an entry.
+     */
+    getChildren(parentId: string): SessionEntry[];
+    /**
+     * Get the label for an entry, if any.
+     */
+    getLabel(id: string): string | undefined;
+    /**
+     * Set or clear a label on an entry.
+     * Labels are user-defined markers for bookmarking/navigation.
+     * Pass undefined or empty string to clear the label.
+     */
+    appendLabelChange(targetId: string, label: string | undefined): string;
+    /**
+     * Walk from entry to root, returning all entries in path order.
+     * Includes all entry types (messages, compaction, model changes, etc.).
+     * Use buildSessionContext() to get the resolved messages for the LLM.
+     */
+    getBranch(fromId?: string): SessionEntry[];
+    /**
+     * Build the session context (what gets sent to the LLM).
+     * Uses tree traversal from current leaf.
+     */
+    /**
+     * Return a defensive context snapshot for public consumers.
+     */
+    buildSessionContext(): SessionContext;
+    /** Strip stale OpenAI Responses assistant replay metadata from loaded in-memory entries without persisting it. */
+    sanitizeLoadedOpenAIResponsesReplayMetadata(): boolean;
+    /**
+     * Get session header.
+     */
+    getHeader(): SessionHeader | null;
+    getEntries(): SessionEntry[];
+    /**
+     * Get the session as a tree structure. Returns defensive copies of all entries.
+     * A well-formed session has exactly one root (first entry with parentId === null).
+     * Orphaned entries (broken parent chain) are also returned as roots.
+     */
+    getTree(): SessionTreeNode[];
+    [sessionManagerReadCapability](): SessionManagerReadAccess;
+    /**
+     * Start a new branch from an earlier entry.
+     * Moves the leaf pointer to the specified entry. The next appendXXX() call
+     * will create a child of that entry, forming a new branch. Existing entries
+     * are not modified or deleted.
+     */
+    branch(branchFromId: string): void;
+    /**
+     * Reset the leaf pointer to null (before any entries).
+     * The next appendXXX() call will create a new root entry (parentId = null).
+     * Use this when navigating to re-edit the first user message.
+     */
+    resetLeaf(): void;
+    /**
+     * Start a new branch with a summary of the abandoned path.
+     * Same as branch(), but also appends a branch_summary entry that captures
+     * context from the abandoned conversation path.
+     */
+    branchWithSummary(branchFromId: string | null, summary: string, details?: unknown, fromExtension?: boolean): string;
+    /**
+     * Create a new session file containing only the path from root to the specified leaf.
+     * Useful for extracting a single conversation path from a branched session.
+     * Returns the new session file path, or undefined if not persisting.
+     */
+    createBranchedSession(leafId: string): string | undefined;
+    /**
+     * Resolve the canonical default session directory for a cwd.
+     */
+    static getDefaultSessionDir(cwd: string, agentDir?: string, storage?: SessionStorage): string;
+    /** Resolve the default session directory without creating or migrating storage. */
+    static getDefaultSessionDirReadOnly(cwd: string, agentDir?: string): string;
+    /**
+     * Create a new session.
+     * @param cwd Working directory (stored in session header)
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.skc/agent/sessions/<encoded-cwd>/).
+     */
+    static nestedManagedDestination(authority: ManagedDirectoryRoot | ManagedSessionDescendantStore, directory: string): SessionDestination;
+    static managedDestination(cwd: string, agentDir?: string, storage?: SessionStorage): SessionDestination;
+    static explicitDestination(directory: string): SessionDestination;
+    static create(cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage): SessionManager;
+    /** Resolve a default-managed candidate through binding validation and copy-retain migration before mutation. */
+    static prepareManagedCandidateForWrite(filePath: string, migrationPolicy: SessionDirectoryMigrationPolicy): Promise<string>;
+    /**
+     * Fork a session into the current project directory.
+     * Copies history from another session file while creating a new session file in the current sessionDir.
+     */
+    static forkFrom(sourcePath: string, cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    /**
+     * Open a specific session file.
+     * @param path Path to session file
+     * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
+     */
+    static open(filePath: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    static openNestedManaged(filePath: string, destination: SessionDestination, store: ManagedSessionDescendantStore, storage?: SessionStorage): Promise<SessionManager>;
+    /**
+     * List sessions for the resume picker without recovery or other maintenance writes.
+     */
+    static listForResumePickerReadOnly(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
+    /** Tombstone and exact-delete a default-managed candidate. */
+    static deleteManagedCandidate(sessionPath: string): Promise<void>;
+    /** Capture exact source content for a strict fork without granting write ownership. */
+    static captureTranscriptStrict(filePath: string, storage?: SessionStorage): StrictSessionCaptureResult;
+    /**
+     * Fork strictly from captured source bytes. The source pathname is used only to
+     * revalidate captured authority before destination initialization and transcript
+     * persistence; destination history always comes from the captured bytes.
+     */
+    static forkFromCaptured(snapshot: CapturedSessionTranscriptSnapshot, cwd: string, destinationInput?: SessionDestinationInput, _migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionForkResult>;
+    /** Inspect a selected session without acquiring write-capable ownership. */
+    static inspectSessionTailReadOnly(filePath: string, storage?: SessionStorage): Promise<ResumeTailInspection>;
+    /**
+     * Hydrate an existing predecessor transcript for recovery without taking any
+     * write-capable action. The caller must retain the returned context and use
+     * the explicit promotion seam only after its ownership-ready fence and writer
+     * lease are durable.
+     */
+    static openExistingForRecoveryHydrationStrict(identity: ResumeSessionIdentity, destinationInput?: SessionDestinationInput, storage?: SessionStorage): Promise<RecoveryHydrationOpenResult>;
+    /**
+     * Allows the normal post-open metadata sanitation only after the caller has
+     * fsynced its external ownership-ready fence and acquired the writer lease.
+     */
+    promoteRecoveryHydrationAfterOwnershipReadyFence(context: RecoveryHydrationContext, fence: RecoveryHydrationPromotionFence): Promise<void>;
+    /**
+     * Main startup code MUST retain the consented inspection identity and branch on
+     * the returned discriminant; an error result never creates, rewrites, or adopts
+     * the selected path. Breadcrumb ownership begins only after `kind: "opened"`.
+     */
+    static openExistingStrict(identity: ResumeSessionIdentity, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<StrictSessionOpenResult>;
+    /**
+     * Continue the most recent session, or create new if none.
+     * @param cwd Working directory
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.skc/agent/sessions/<encoded-cwd>/).
+     */
+    static continueRecent(cwd: string, destinationInput?: SessionDestinationInput, storage?: SessionStorage, migrationPolicy?: SessionDirectoryMigrationPolicy): Promise<SessionManager>;
+    /** Create an in-memory session (no file persistence) */
+    static inMemory(cwd?: string, storage?: SessionStorage): SessionManager;
+    /**
+     * List all sessions.
+     * @param cwd Working directory (used to compute default session directory)
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.skc/agent/sessions/<encoded-cwd>/).
+     */
+    static list(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
+    /**
+     * List all sessions across all project directories.
+     */
+    static listAll(storage?: SessionStorage): Promise<SessionInfo[]>;
+    /**
+     * Strict raw scoped inventory for ACP authorization. Enumerates the scoped
+     * session directory without suppressing any root/scan/lstat/read/parse/stat/
+     * header/cwd/containment/identity failure. A failure result carries every
+     * sanitized failure and grants zero authority — it is never reduced to a
+     * partial candidate set. Display/global {@link list} behavior is unaffected.
+     */
+    static inventorySessionsStrict(cwd: string, options?: {
+        sessionDir?: string;
+        storage?: SessionStorage;
+    }): StrictInventoryResult;
+    /**
+     * Propagate the storage-layer verified hard delete bound to exact identity evidence.
+     * Never performs ID lookup or first-match selection; the caller supplies the exact
+     * authorization target captured from a complete strict inventory.
+     */
+    deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
+}
+export {};