@vibesdotdev/session 0.0.0-stage → 1.0.0-rc.2

package/dist/manager.d.ts

@@ -0,0 +1,715 @@
+/**
+ * Session Manager
+ * Core business logic for session management
+ *
+ * Responsibilities:
+ * - Session lifecycle management (create, resume, pause, archive)
+ * - TODO tracking with dependencies and hierarchies
+ * - Scratchpad operations with expiration
+ * - Job reference tracking
+ * - Participant messaging
+ * - Knowledge context integration
+ * - Participant identification and connection tracking
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { RuntimeInvokeCaller } from '@vibesdotdev/kernel/schemas/invoke-caller';
+import type { VibesLink } from '@vibesdotdev/shared/schemas';
+import { type HarnessSeat, type HarnessSeatRegistration } from './schemas/harness-seat.ts';
+import type { SessionMembershipLease } from './storage/session-membership-leases.record.descriptor.ts';
+import type { Session, SessionCreate, SessionUpdate, SessionFilters, SessionSummary, Todo, TodoCreate, TodoUpdate, TodoFilters, TodoWithComputed, ScratchpadEntry, ScratchpadEntryCreate, ScratchpadEntryUpdate, ScratchpadFilters, ScratchpadSummary, JobRef, JobRefCreate, JobRefUpdate, JobFilters, JobSummary, ParticipantMessage, ParticipantMessageCreate, MessageFilters, ParticipantProfile, ParticipantProfileCreate, ParticipantProfileUpdate, ParticipantFilters, ParticipantConnection, RegisterInstanceInput, KnowledgeRef, KnowledgeRefCreate, KnowledgeRefFilters, SessionPresence, SessionPresenceSummary } from './schemas/index.ts';
+/**
+ * Key-order-independent JSON so metadata comparison can't flake on insertion
+ * order: every object's keys are emitted sorted, arrays keep their order, and
+ * `undefined` encodes as `null`.
+ */
+export declare function canonicalJson<Value>(value: Value): string;
+/**
+ * Keep the indexed Work item id and its typed execution edge inseparable.
+ * A Work-linked todo always carries exactly one canonical work-item edge.
+ */
+export declare function normalizeTodoWorkLink<T extends {
+    workItemId?: string;
+    links?: VibesLink[];
+}>(todo: T, options?: {
+    rewriteExisting?: boolean;
+}): T;
+/** Attach one authoritative checkout project edge to every Work-linked todo. */
+export declare function scopeTodoWorkLinks<T extends {
+    workItemId?: string;
+    links?: VibesLink[];
+}>(todo: T, projectId?: string): T;
+export interface PruneStaleMappingsResult {
+    prunedEntries: number;
+    remainingEntries: number;
+    prunedKeys: string[];
+}
+export interface PruneOrphanedProfilesResult {
+    prunedProfiles: number;
+    remainingProfiles: number;
+    protectedCount: number;
+    prunedIds: string[];
+}
+/** Cross-feature contract exposed by the registered `session/manager` context. */
+export interface SessionContextResolutionOptions {
+    intent?: 'bind' | 'read';
+    caller?: RuntimeInvokeCaller;
+}
+/** Session-owned resolution result returned through `session/manager`. */
+export interface ResolvedSessionContext {
+    session: SessionManager;
+    sessionId: string;
+    participantId?: string;
+    sessionData: Session | null;
+}
+/**
+ * SessionManager
+ * High-level API for session operations with business logic
+ *
+ * Uses storage descriptors for adapter-agnostic storage operations.
+ * Supports any compliant storage adapter (localdb, drizzle, etc.)
+ */
+export declare class SessionManager {
+    private hostRuntime;
+    private logger;
+    /** A stable manager keeps state while dependencies follow its caller's view. */
+    private get runtime();
+    /** The runtime this manager serves (its caller's view): per-root transport state keys on its root. */
+    get servingRuntime(): VibesRuntime;
+    bindRuntime(runtime: VibesRuntime): void;
+    private initialized;
+    private sessionsStorage?;
+    private todosStorage?;
+    private scratchpadStorage?;
+    private jobsStorage?;
+    private messagesStorage?;
+    private participantsStorage?;
+    private presenceStorage?;
+    private knowledgeRefsStorage?;
+    private connectionsStorage?;
+    private membershipLeasesStorage?;
+    private participantSessions;
+    private mcpSessions;
+    private defaultSessionId;
+    private defaultParticipantId;
+    private persistMappingsTail;
+    constructor(runtime: VibesRuntime);
+    /**
+     * Resolve Session's participant/session policy through the registered
+     * manager context. Consumers do not import MCP participant internals.
+     */
+    resolveContext(sessionId?: string, participantId?: string, mcpSessionId?: string | null, options?: SessionContextResolutionOptions): Promise<ResolvedSessionContext>;
+    /** Identify this caller by UUID or slug, reusing Session's self-registration policy. */
+    identifyParticipant(reference: string): Promise<string>;
+    /** Resolve or create the caller's MCP participant under Session policy. */
+    resolveMcpParticipant(options?: {
+        preferredParticipantId?: string;
+        preferredSlug?: string;
+    }, mcpSessionId?: string | null, caller?: RuntimeInvokeCaller): Promise<string>;
+    /** Commit and publish Session's canonical bound-session lifecycle event. */
+    announceBound(sessionId: string, participantId: string | undefined, surface: string): Promise<void>;
+    /**
+     * Ambient consumers need one stable session identity, not a private map
+     * guess. The durable default is the process' current binding and is cleared
+     * when that session is paused, archived, or deleted.
+     */
+    get activeSessionId(): string | undefined;
+    /**
+     * Resolve one `session.*` storage record through the runtime. A declared
+     * record whose implementation is not registered (the descriptor-only
+     * registration path) is bound directly to its descriptor; a record that is
+     * not declared at all is a typed NOT_FOUND. Every other resolution failure
+     * propagates unchanged.
+     */
+    private resolveStorageRecord;
+    private ensureStorage;
+    /**
+     * The notifications delivery client, or `undefined` when the composition
+     * does not provide one. Notifications are runtime-soft (SPEC): absence is
+     * confirmed by asking the runtime whether the client is declared, never by
+     * catching a failure. A declared client that fails to load propagates.
+     */
+    private resolveNotifications;
+    /** A true COUNT over `where` — never a loaded page's length (ledger L-11). */
+    private countRecords;
+    private buildSessionSummary;
+    private nonEmptyMetadata;
+    private projectParticipant;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Resolves `true` when session storage answers a query. Storage that cannot
+     * answer is a typed `UNAVAILABLE session-storage-unavailable` refusal
+     * carrying the storage failure, never a silent `false`.
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Create a session. An active creation becomes the workspace's durable
+     * default unless `adoptAsDefault: false` — a per-native-session continuity
+     * row minted by an external-tool hook is not "the process' current binding"
+     * and must not retarget every later anonymous bind onto itself.
+     */
+    createSession(session: SessionCreate, options?: {
+        adoptAsDefault?: boolean;
+        id?: string;
+    }): Promise<Session>;
+    getSession(id: string): Promise<Session | null>;
+    updateSession(id: string, updates: SessionUpdate): Promise<void>;
+    /**
+     * Place a session under a parent session (a subsession), or make it top
+     * level with `null`. The parent must exist, and may not be the session itself
+     * or any of its descendants: a cycle is refused `INVALID_INPUT
+     * session-parent-cycle`.
+     */
+    setSessionParent(sessionId: string, parentSessionId: string | null): Promise<void>;
+    /**
+     * Bump a session's activity clock to reflect real traffic (messages), so
+     * `lastActivityAt` tracks when the session was last USED — not merely when its
+     * record was created. Before this, `lastActivityAt` was stamped only at
+     * createSession, so a live session reads hours-stale while agents are actively
+     * messaging on it — a false "dark/idle" signal that mislead liveness reads.
+     * Best-effort: an activity touch must NEVER fail the underlying operation.
+     */
+    private touchSessionActivity;
+    listSessions(filters?: SessionFilters): Promise<SessionSummary[]>;
+    /**
+     * Count sessions matching the filter without pagination.
+     *
+     * Routines need a way to distinguish "this page is empty" from
+     * "the underlying set is empty," so this exposes the unfiltered
+     * count even when callers paginate via `listSessions`.
+     */
+    countSessions(filters?: Pick<SessionFilters, 'status' | 'ownerParticipant'>): Promise<number>;
+    getActiveSession(): Promise<Session | null>;
+    /**
+     * Pause a specific session by id. Prefer this over pauseActiveSession when
+     * the caller has a concrete target (e.g. a UI selection): with more than one
+     * active session, "the active session" is ambiguous and pausing the wrong
+     * one is a real hazard.
+     */
+    pauseSession(id: string): Promise<void>;
+    /**
+     * Pause the active session and optionally create a new one
+     */
+    pauseActiveSession(): Promise<void>;
+    /**
+     * Resume a paused session (sets it to active)
+     */
+    resumeSession(id: string): Promise<Session>;
+    /**
+     * Open a session for bound work. Paused sessions resume in place.
+     * Archived sessions stay closed until the explicit resume action.
+     */
+    openSessionForWork(sessionId: string): Promise<Session>;
+    /** Participant ids currently mapped to this session. */
+    listBoundParticipantIds(sessionId: string): Promise<string[]>;
+    private releaseAllMembershipLeases;
+    archiveSession(id: string): Promise<void>;
+    deleteSession(id: string): Promise<void>;
+    searchSessions(query: string, filters?: SessionFilters): Promise<SessionSummary[]>;
+    /**
+     * Session search with true match total (L-11 class).
+     * Storage search already returns COUNT over MATCH+where before limit;
+     * discard-only wrappers were re-introducing page-as-total at CLI/MCP.
+     */
+    searchSessionsPaged(query: string, filters?: SessionFilters): Promise<{
+        results: SessionSummary[];
+        total: number;
+    }>;
+    /**
+     * Get child sessions for a parent session
+     */
+    getChildSessions(parentSessionId: string): Promise<Session[]>;
+    /**
+     * Get parent session if one exists
+     */
+    getParentSession(childSessionId: string): Promise<Session | null>;
+    /**
+     * Create a child session linked to a parent
+     */
+    createChildSession(parentSessionId: string, session: Omit<SessionCreate, 'parentSessionId'>): Promise<Session>;
+    createTodo(sessionId: string, todo: TodoCreate): Promise<Todo>;
+    /** Create once for one native todo identity; never overwrite another record. */
+    ensureNativeTodo(sessionId: string, native: {
+        tool: string;
+        session: string;
+        id: string;
+    }, todo: TodoCreate): Promise<Todo>;
+    /**
+     * Legacy alias retained for CLI compatibility.
+     */
+    addTodo(sessionId: string, todo: TodoCreate): Promise<Todo>;
+    getTodo(id: string): Promise<Todo | null>;
+    updateTodo(id: string, updates: TodoUpdate): Promise<void>;
+    /**
+     * Legacy alias retained for CLI compatibility.
+     */
+    completeTodo(id: string, updates?: Pick<TodoUpdate, 'actualMinutes' | 'metadata' | 'tags'>): Promise<Todo>;
+    /**
+     * The storage filter for a session's todos. `tags` is exact all-of
+     * membership; `workItemId` is indexed. `hasDependencies`/`isBlocked` are
+     * not storage predicates: {@link scanTodosByDependency} applies them.
+     */
+    private buildTodoWhere;
+    countTodos(sessionId: string, filters?: TodoFilters): Promise<number>;
+    listTodos(sessionId: string, filters?: TodoFilters): Promise<Todo[]>;
+    /** One page of todos in the default order; the id tiebreak keeps successive pages stable. */
+    private listTodoPage;
+    /** Every todo matching `where`, paged exhaustively (no row ceiling). */
+    private scanTodos;
+    /**
+     * The session's todos matching the storage filters and the dependency
+     * predicates, in the default order. Exhaustive, so callers page and count
+     * the full match set: `isBlocked` follows {@link computeTodo}.
+     */
+    private scanTodosByDependency;
+    /**
+     * The dependencies of `todo` not yet completed. A missing dependency row
+     * does not block; one absent from `known` (another session's todo)
+     * resolves through storage. The one blocked-dependency predicate.
+     */
+    private incompleteDependencies;
+    /**
+     * Every todo linked to a work item, across all sessions, most recently
+     * updated first. Exhaustive: the work-item trace reads it whole.
+     */
+    listTodosForWorkItem(workItemId: string): Promise<Todo[]>;
+    getTodoWithComputed(id: string): Promise<TodoWithComputed | null>;
+    listTodosWithComputed(sessionId: string, filters?: TodoFilters): Promise<TodoWithComputed[]>;
+    /**
+     * A todo with its display fields computed from storage: the dependencies
+     * not yet completed (`blockedBy`; a missing dependency row does not block),
+     * its direct subtask counts, and progress (completed share of subtasks, or
+     * 0/100 by its own status when it has none).
+     */
+    private computeTodo;
+    deleteTodo(id: string): Promise<void>;
+    getTodoHierarchy(parentId: string): Promise<Todo[]>;
+    /**
+     * Blocked means the todo's own explicit status — `status === 'blocked'`.
+     * A todo waiting on incomplete dependencies is a different, truthful state;
+     * ask {@link hasIncompleteDependencies} for that.
+     */
+    isTodoBlocked(id: string): Promise<boolean>;
+    /**
+     * True when the todo declares at least one dependency that is not yet
+     * completed. Reports dependency state only — it says nothing about the
+     * todo's own status (a completed todo with a stale incomplete dependency
+     * still answers true here).
+     */
+    hasIncompleteDependencies(id: string): Promise<boolean>;
+    /**
+     * Get all root-level TODOs (no parent)
+     */
+    getRootTodos(sessionId: string, filters?: TodoFilters): Promise<Todo[]>;
+    /**
+     * Get subtasks for a parent TODO
+     */
+    getSubtasks(parentId: string): Promise<Todo[]>;
+    writeScratchpad(sessionId: string, entry: ScratchpadEntryCreate): Promise<ScratchpadEntry>;
+    /**
+     * Replace an existing scratchpad entry with a fresh write.
+     *
+     * A write is a full replace, not a merge: every ScratchpadEntryCreate field
+     * is passed explicitly with the create-branch defaults, so omitted optional
+     * fields (tags/metadata/expiresAt/language) reset instead of silently
+     * inheriting the previous entry's values. Only id and createdAt survive.
+     */
+    private replaceScratchpadEntry;
+    readScratchpad(sessionId: string, key: string): Promise<ScratchpadEntry | null>;
+    getScratchpadEntry(id: string): Promise<ScratchpadEntry | null>;
+    updateScratchpadEntry(id: string, updates: ScratchpadEntryUpdate): Promise<void>;
+    private buildScratchpadWhere;
+    countScratchpad(sessionId: string, filters?: ScratchpadFilters): Promise<number>;
+    listScratchpad(sessionId: string, filters?: ScratchpadFilters): Promise<ScratchpadSummary[]>;
+    deleteScratchpadEntry(id: string): Promise<void>;
+    cleanupExpiredScratchpad(): Promise<number>;
+    searchScratchpad(sessionId: string, query: string, filters?: ScratchpadFilters): Promise<{
+        items: ScratchpadSummary[];
+        total: number;
+    }>;
+    addJobRef(sessionId: string, job: JobRefCreate): Promise<JobRef>;
+    getJobRef(id: string): Promise<JobRef | null>;
+    getJobRefByJobId(jobId: string): Promise<JobRef | null>;
+    updateJobRef(id: string, updates: JobRefUpdate): Promise<void>;
+    private buildJobWhere;
+    countJobRefs(sessionId: string, filters?: JobFilters): Promise<number>;
+    getJobRefs(sessionId: string, filters?: JobFilters): Promise<JobSummary[]>;
+    deleteJobRef(id: string): Promise<void>;
+    sendMessage(sessionId: string, message: ParticipantMessageCreate): Promise<ParticipantMessage>;
+    /**
+     * Advisory: bump the sender's lastSeen on a send. A failure never fails
+     * the send; it is reported with value-free facts.
+     */
+    private touchParticipantLastSeen;
+    /**
+     * Runtime-soft (SPEC): fan an unread-count notice out through the
+     * notifications client at the 1st, 5th and 10th unread message. A
+     * composition without notifications is confirmed absent and skipped; any
+     * other failure never fails the send and is reported with value-free facts.
+     */
+    private notifyUnread;
+    /**
+     * Exactly-once send keyed on a caller-supplied deterministic id.
+     *
+     * A batch retry after a mid-batch failure re-sends entries whose first
+     * attempt may or may not have persisted. With a stable per-entry id the
+     * replayed create collides on the primary key instead of duplicating;
+     * the existing row is returned with `replay: true` and the side effects
+     * (activity bump, notification) are not re-fired.
+     *
+     * On ANY failure — not only a unique-constraint collision — durable state
+     * is consulted by the deterministic id: a row can persist and a LATER
+     * effect inside sendMessage throw, and classifying that schedule as
+     * "failed" would make the receipt deny a delivery that exists. And a
+     * found row only counts as a replay when its payload MATCHES the intended
+     * send: the same id with different content/recipient is a caller bug that
+     * must surface as a CONFLICT, never as a silent old-row "delivery".
+     */
+    sendMessageIdempotent(sessionId: string, message: ParticipantMessageCreate & {
+        id: string;
+    }): Promise<{
+        message: ParticipantMessage;
+        replay: boolean;
+    }>;
+    getMessage(id: string): Promise<ParticipantMessage | null>;
+    private buildMessageWhere;
+    countMessages(sessionId: string, filters?: MessageFilters): Promise<number>;
+    getMessages(sessionId: string, filters?: MessageFilters): Promise<ParticipantMessage[]>;
+    markMessageRead(id: string): Promise<void>;
+    markAllMessagesRead(sessionId: string, toParticipant: string): Promise<number>;
+    deleteMessage(id: string): Promise<void>;
+    getUnreadCount(sessionId: string, toParticipant: string): Promise<number>;
+    registerParticipant(profile: ParticipantProfileCreate): Promise<ParticipantProfile>;
+    getParticipant(participantId: string): Promise<ParticipantProfile | null>;
+    getParticipantByConnection(connectionId: string): Promise<ParticipantProfile | null>;
+    updateParticipant(participantId: string, updates: ParticipantProfileUpdate): Promise<void>;
+    /**
+     * The seat for one harness conversation, read-only. See
+     * `schemas/harness-seat.ts`: the id is derived, so this is a point read.
+     */
+    findHarnessSeat(seat: HarnessSeat): Promise<ParticipantProfile | null>;
+    /**
+     * The seat for one harness conversation, registered on first sight. The
+     * harness hook and the MCP connection both call this, so they converge on
+     * one participant whichever arrives first. The seat's identity (agent,
+     * harness session, slug) is written onto rows registered before it was.
+     */
+    ensureHarnessSeat(input: HarnessSeatRegistration): Promise<ParticipantProfile>;
+    updateParticipantLastSeen(participantId: string): Promise<void>;
+    listParticipants(filters?: ParticipantFilters): Promise<ParticipantProfile[]>;
+    deleteParticipant(participantId: string): Promise<void>;
+    pruneStaleSessionMappings(): Promise<PruneStaleMappingsResult>;
+    pruneOrphanedParticipantProfiles(): Promise<PruneOrphanedProfilesResult>;
+    recordConnection(connection: Omit<ParticipantConnection, 'connectedAt' | 'disconnectedAt'>): Promise<ParticipantConnection>;
+    closeConnection(connectionId: string): Promise<void>;
+    private static readonly INSTANCE_TTL_MS;
+    private static readonly INSTANCE_HEARTBEAT_MS;
+    /** Touches inside this window are not rewritten: one write per instance per window. */
+    private static readonly INSTANCE_TOUCH_MIN_MS;
+    private static readonly INSTANCE_HANDLE_ATTEMPTS;
+    /** This host's own key: distinguishes its in-process seats from another host's. */
+    readonly hostKey: string;
+    private readonly hostedInstances;
+    private readonly instanceTouchedAt;
+    /** Handles of instances this host registered, so a touch need not reread them. */
+    private readonly instanceHandles;
+    /** (instance, session, participant) triples this host has already leased. */
+    private readonly instanceMemberships;
+    private instanceHeartbeat?;
+    private static isLiveInstance;
+    private static randomHandle;
+    /**
+     * Register (or re-register) a running instance and give it a handle. A
+     * chosen handle held by another LIVE instance is refused `CONFLICT
+     * instance-handle-taken` naming the holder; one held by an expired or closed
+     * instance is reclaimed. With no choice the instance keeps its live handle,
+     * else gets a random `<agent>-<4>` handle. Uniqueness is the storage index
+     * on `activeHandle`, not this check: a lost race is retried (random) or
+     * refused (chosen).
+     */
+    registerInstance(input: RegisterInstanceInput): Promise<ParticipantConnection>;
+    /** Free `handle` when its holder is no longer live, so a new instance can take it. */
+    private releaseExpiredHandle;
+    /** The live instance holding `handle`, if any. */
+    liveInstanceByHandle(handle: string): Promise<ParticipantConnection | null>;
+    /**
+     * Mark an instance alive now and renew the membership leases it holds.
+     * Writes at most once per touch window per instance.
+     */
+    touchInstance(instanceId: string, options?: {
+        force?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Keep an admitted caller's instance live: register it the first time this
+     * host sees it (or after it was closed), otherwise touch it.
+     */
+    ensureInstance(input: RegisterInstanceInput): Promise<{
+        handle?: string;
+    }>;
+    /**
+     * Make an instance a member of the session it calls with: one lease keyed
+     * on the instance, taken the first time this host sees the pair and renewed
+     * by every touch after. An archived or missing session takes no member.
+     */
+    ensureInstanceMembership(input: {
+        instanceId: string;
+        sessionId: string;
+        participantId: string;
+    }): Promise<void>;
+    /**
+     * Give a live instance the handle it chose. The registry's uniqueness rule
+     * applies: a handle another live instance holds is refused naming its holder.
+     */
+    chooseInstanceHandle(instanceId: string, handle: string): Promise<ParticipantConnection>;
+    /** One instance's registry row. */
+    getInstance(instanceId: string): Promise<ParticipantConnection | null>;
+    /** Record the session an instance is working in (its bind, or its first write). */
+    setInstanceSession(instanceId: string, sessionId: string): Promise<void>;
+    /** The session an instance is working in, while that session is still open. */
+    instanceSession(instanceId: string): Promise<string | undefined>;
+    /** Close an instance: it stops being live, frees its handle and releases its leases. */
+    closeInstance(instanceId: string): Promise<void>;
+    /** Every live instance in this store: who is here, however they arrived. */
+    listLiveInstances(): Promise<ParticipantConnection[]>;
+    private forgetInstance;
+    private unreleasedLeasesOf;
+    /**
+     * Heartbeat hosted instances on this runtime's lifecycle interval, so the
+     * kernel stops it at disposal. A finite host (a one-shot command) runs no
+     * interval: its instance lives by activity and closes with the manager.
+     */
+    private hostInstance;
+    private stopInstanceHeartbeat;
+    getConnectionHistory(participantId?: string, limit?: number): Promise<ParticipantConnection[]>;
+    addKnowledgeRef(sessionId: string, ref: KnowledgeRefCreate): Promise<KnowledgeRef>;
+    getKnowledgeRef(id: string): Promise<KnowledgeRef | null>;
+    getKnowledgeRefs(sessionId: string, filters?: KnowledgeRefFilters): Promise<KnowledgeRef[]>;
+    deleteKnowledgeRef(id: string): Promise<void>;
+    deleteSessionKnowledgeRefs(sessionId: string): Promise<number>;
+    setParticipantActiveSession(participantId: string, sessionId: string): Promise<void>;
+    getParticipantActiveSession(participantId: string): Promise<string | null>;
+    /**
+     * Read one participant binding from durable authority for a custody decision.
+     *
+     * The ordinary getter intentionally serves the manager's hydrated read model.
+     * MCP authorization cannot use that cache: another process may have rebound
+     * the participant since this manager started.  Read the body-scoped row on
+     * every call, reconcile only this cache entry, and let storage/parse failures
+     * propagate so the caller fails closed.
+     */
+    getAuthoritativeParticipantActiveSession(participantId: string): Promise<string | null>;
+    /**
+     * Read one participant's body-scoped routing row from durable storage and
+     * reconcile this manager's cache entry with it. A storage failure
+     * propagates; a row that cannot be decoded is reported as `malformed`
+     * (never as unbound) so each caller decides whether to fail closed.
+     */
+    private readParticipantRouting;
+    clearParticipantActiveSession(participantId: string): Promise<void>;
+    ensureParticipantSession(participantId: string): Promise<Session | null>;
+    setDefaultActiveSession(sessionId: string | null): Promise<void>;
+    getDefaultActiveSession(): Promise<string | null>;
+    /** Persist the default session together with the CLI participant that selected it. */
+    setDefaultActiveBinding(sessionId: string, participantId: string): Promise<void>;
+    /** Resolve the durable CLI caller without falling back to a participant-null session. */
+    getDefaultActiveBinding(): Promise<{
+        sessionId: string;
+        participantId: string;
+    } | null>;
+    /**
+     * Get or create active session for a participant
+     */
+    getOrCreateActiveSession(participantId: string, title?: string): Promise<Session>;
+    /**
+     * Get session statistics.
+     *
+     * Every figure is a TRUE count — countRecords over the exact where-filters
+     * the corresponding lists use. These totals previously came from capped
+     * list pages (todos/scratchpad/messages at 10000 rows, jobs at the 100-row
+     * default page) and silently froze at the ceiling on busy sessions.
+     */
+    getSessionStats(sessionId: string, participantId?: string): Promise<{
+        session: {
+            id: string;
+            title: string;
+            status: "active" | "paused" | "archived";
+            scope: "local" | "global" | "project";
+            tags: string[];
+            ownerParticipant: string;
+            metadata: {
+                [x: string]: unknown;
+                source?: string | undefined;
+                version?: string | undefined;
+                gitBranch?: string | undefined;
+                gitCommit?: string | undefined;
+                linearIssueId?: string | undefined;
+                githubPrNumber?: number | undefined;
+                sessionType?: string | undefined;
+                custom?: Record<string, unknown> | undefined;
+            };
+            createdAt: Date;
+            updatedAt: Date;
+            lastActivityAt: Date;
+            description?: string | undefined;
+            projectId?: string | undefined;
+            filesPattern?: string[] | undefined;
+            workItemId?: string | undefined;
+            links?: {
+                kind: string;
+                id: string;
+                source: string;
+                role: string;
+            }[] | undefined;
+            parentSessionId?: string | null | undefined;
+            assignedParticipant?: string | undefined;
+            pausedAt?: Date | undefined;
+            archivedAt?: Date | undefined;
+        };
+        todos: {
+            total: number;
+            completed: number;
+            active: number;
+            blocked: number;
+            awaitingDependencies: number;
+            pending: number;
+        };
+        scratchpad: {
+            total: number;
+            byType: Record<string, number>;
+        };
+        jobs: {
+            total: number;
+            completed: number;
+            pending: number;
+            processing: number;
+            failed: number;
+        };
+        messages: {
+            total: number;
+            unread: number;
+            scope: "session" | "participant";
+            participantId: string | undefined;
+        };
+    } | null>;
+    /**
+     * True counts per scratchpad content type. Enumerates the closed content
+     * type set and counts each — never derived from a capped list page. Types
+     * with zero entries are omitted, matching the historical byType shape.
+     */
+    private countScratchpadByType;
+    /**
+     * Count non-terminal todos waiting on at least one incomplete dependency.
+     * Exhaustive paged scan — no row ceiling. Distinct from the `blocked`
+     * bucket, which is the todo's own explicit status; a completed or
+     * cancelled todo is not awaiting anything, so terminal rows never count.
+     */
+    private countTodosAwaitingDependencies;
+    private ensureInitialized;
+    private loadSessionMappings;
+    /**
+     * Serialize one routing write behind every earlier one. Its failure is
+     * returned to the caller that queued it (the returned promise rejects);
+     * the tail only orders writes, so one failed write never blocks the next.
+     */
+    private queueRoutingMutation;
+    private persistRoutingRow;
+    private deleteRoutingRow;
+    private clearMappingsForSession;
+    private applySessionState;
+    private recoverActiveSession;
+    ensureSessionActive(sessionId: string): Promise<Session>;
+    /**
+     * Link MCP HTTP session to Vibes session
+     *
+     * MCP HTTP transport maintains connection-based sessions.
+     * This maps those to active Vibes sessions for tool execution context.
+     *
+     * @param mcpSessionId - MCP HTTP session identifier
+     * @param vibesSessionId - Vibes session UUID
+     */
+    linkMcpSession(mcpSessionId: string, vibesSessionId: string): Promise<void>;
+    /**
+     * Get Vibes session for MCP connection
+     *
+     * @param mcpSessionId - MCP HTTP session identifier
+     * @returns Session if mapped and exists, null otherwise
+     */
+    getSessionForMcpConnection(mcpSessionId: string): Promise<Session | null>;
+    /**
+     * Unlink MCP HTTP session from Vibes session
+     *
+     * Called when MCP session closes or Vibes session is archived.
+     *
+     * @param mcpSessionId - MCP HTTP session identifier
+     */
+    unlinkMcpSession(mcpSessionId: string): Promise<void>;
+    /**
+     * Clear all MCP session mappings for a given Vibes session
+     *
+     * Called when a session is archived or deleted.
+     *
+     * @param vibesSessionId - Vibes session UUID
+     */
+    clearMcpSessionsForVibesSession(vibesSessionId: string): Promise<void>;
+    /**
+     * Record presence for a connection to a session
+     */
+    recordPresence(input: {
+        sessionId: string;
+        participantId?: string;
+        connectionId?: string;
+        metadata?: SessionPresence['metadata'];
+    }): Promise<SessionPresence>;
+    /**
+     * Update heartbeat for a connection
+     */
+    updateHeartbeat(connectionId: string): Promise<void>;
+    /**
+     * Get active presence records for a session
+     */
+    getActivePresence(sessionId: string): Promise<SessionPresence[]>;
+    /**
+     * Get presence summary for a session
+     */
+    getPresenceSummary(sessionId: string): Promise<SessionPresenceSummary>;
+    /**
+     * Check if session is occupied (has active/idle connections)
+     */
+    isSessionOccupied(sessionId: string): Promise<boolean>;
+    private static readonly MEMBERSHIP_LEASE_TTL_MS;
+    private normalizeConnectionKey;
+    /**
+     * Acquire or renew a membership lease. Idempotent on
+     * (sessionId, participantId, connectionKey).
+     */
+    acquireMembershipLease(input: {
+        sessionId: string;
+        participantId: string;
+        connectionKey?: string | null;
+        role?: 'owner' | 'member';
+        claimedTodoIds?: string[];
+        metadata?: SessionMembershipLease['metadata'];
+        ttlMs?: number;
+    }): Promise<SessionMembershipLease>;
+    releaseMembershipLease(input: {
+        sessionId: string;
+        participantId: string;
+        connectionKey?: string | null;
+    }): Promise<boolean>;
+    /** Live roster: unreleased leases whose expiry is still in the future. */
+    listActiveMembershipLeases(sessionId: string): Promise<SessionMembershipLease[]>;
+    /**
+     * Remove presence record (on disconnect) and release its membership lease.
+     */
+    removePresence(connectionId: string): Promise<void>;
+    /**
+     * Cleanup stale presence records and release any associated leases.
+     */
+    cleanupStalePresence(thresholdMs?: number): Promise<number>;
+    /**
+     * Resolve session with occupation awareness
+     * Returns the first unoccupied session from candidates, or null if all occupied
+     */
+    resolveUnoccupiedSession(candidateIds: string[]): Promise<Session | null>;
+}
+//# sourceMappingURL=manager.d.ts.map