agentcache 0.4.2 → 0.5.0-beta.2

package/dist/mcp.d.ts

@@ -1,3 +1,735 @@
-declare function startMcpServer(): Promise<void>;
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 
-export { startMcpServer };
+declare const SESSION_SCHEMA_VERSION: 1;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * Known adapters remain autocomplete-friendly while third-party adapters can
+ * participate without requiring a domain-model release.
+ */
+type AdapterId = "claude-code" | "cursor" | "roo-code" | "windsurf" | "continue" | "codex" | "goose" | (string & {});
+type SessionState = "active" | "checkpointed" | "closed" | "archived";
+type ClientLegState = "attached" | "completed" | "orphaned";
+type SessionEventKind = "message.user" | "message.assistant" | "tool.call" | "tool.result" | "checkpoint" | "correction" | "tombstone";
+type SessionEventRole = "user" | "assistant" | "tool";
+type RedactionState = "none" | "redacted" | "omitted";
+type HandoffMode = "continue" | "fork";
+type SourceCursorStatus = "active" | "out-of-sync" | "malformed" | "unsupported";
+/** Source facts emitted by adapters before persistence concerns are applied. */
+interface NormalizedEventInput {
+    sourceEventId: string;
+    sourceSequence?: number;
+    kind: SessionEventKind;
+    role?: SessionEventRole;
+    occurredAt: number;
+    textContent?: string;
+    payload?: Record<string, unknown>;
+}
+interface PortableSession {
+    sessionId: string;
+    workspaceId: string | null;
+    title: string;
+    status: SessionState;
+    createdAt: number;
+    updatedAt: number;
+    headEventId: string | null;
+    headSequence: number;
+    headCheckpointId: string | null;
+    metadata: JsonObject;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface ClientLeg {
+    legId: string;
+    sessionId: string;
+    deviceId: string;
+    adapterId: AdapterId;
+    nativeSessionId: string | null;
+    clientVersion: string | null;
+    model: string | null;
+    workspaceLocationId: string | null;
+    resumedFromCheckpointId: string | null;
+    state: ClientLegState;
+    startedAt: number;
+    endedAt: number | null;
+    metadata: JsonObject;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface SessionEvent {
+    eventId: string;
+    sessionId: string;
+    legId: string;
+    timelineSequence: number;
+    sourceEventId: string;
+    sourceSequence: number | null;
+    parentEventId: string | null;
+    kind: SessionEventKind;
+    role: SessionEventRole | null;
+    occurredAt: number;
+    ingestedAt: number;
+    textContent: string | null;
+    payload: JsonObject;
+    contentHash: string;
+    redactionState: RedactionState;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface CheckpointState {
+    objective: string;
+    completedWork: string[];
+    openWork: string[];
+    blockers: string[];
+    explicitConstraints: string[];
+    decisions: string[];
+    rejectedApproaches: string[];
+    nextStep: string | null;
+}
+interface CheckpointWorkspaceState {
+    gitBranch: string | null;
+    gitCommit: string | null;
+    repositoryRelativePaths: string[];
+}
+interface SessionCheckpoint {
+    checkpointId: string;
+    sessionId: string;
+    createdByLegId: string;
+    throughEventId: string;
+    throughSequence: number;
+    summaryText: string;
+    state: CheckpointState;
+    workspaceState: CheckpointWorkspaceState;
+    generator: string;
+    createdAt: number;
+    contentHash: string;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface SessionFork {
+    forkSessionId: string;
+    parentSessionId: string;
+    forkedFromEventId: string;
+    createdByLegId: string | null;
+    reason: string | null;
+    createdAt: number;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface SourceCursor {
+    sourceId: string;
+    legId: string;
+    deviceId: string;
+    adapterId: AdapterId;
+    locator: string;
+    sourceFingerprint: string;
+    cursorKind: string;
+    cursorValue: string;
+    lastSourceEventId: string | null;
+    parserVersion: string;
+    lastSeenAt: number;
+    status: SourceCursorStatus;
+    lastError: string | null;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface Handoff {
+    handoffId: string;
+    sessionId: string;
+    checkpointId: string;
+    workspaceId: string;
+    targetAdapterId: AdapterId;
+    mode: HandoffMode;
+    tokenHash: string;
+    createdAt: number;
+    expiresAt: number;
+    consumedAt: number | null;
+    createdHeadSequence: number;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+    allowsLeaseTakeover: boolean;
+    expectedSourceLeaseGeneration: number | null;
+    expectedSourceLeaseTokenHash: string | null;
+    forkTitle: string | null;
+    forkReason: string | null;
+    /** Exact immutable capsule previewed before this handoff token is disclosed. */
+    capsule: ResumeCapsule | null;
+    /** SHA-256 of the exact persisted capsule JSON; null only for migrated beta rows. */
+    capsuleHash: string | null;
+}
+interface SessionLease {
+    sessionId: string;
+    legId: string;
+    tokenHash: string;
+    generation: number;
+    acquiredAt: number;
+    expiresAt: number;
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+}
+interface CapsuleEvent {
+    eventId: string;
+    sequence: number;
+    adapterId: AdapterId;
+    kind: SessionEventKind;
+    role: SessionEventRole | null;
+    occurredAt: number;
+    text: string | null;
+    toolOutcome?: string;
+}
+interface ResumeCapsule {
+    schemaVersion: typeof SESSION_SCHEMA_VERSION;
+    trust: "untrusted_prior_session_context";
+    checkpointId: string;
+    sessionId: string;
+    workspaceId: string;
+    sourceAdapterId: AdapterId;
+    sourceLegId: string;
+    destinationAdapterId: AdapterId;
+    goal: string;
+    explicitConstraints: string[];
+    completedWork: string[];
+    openWork: string[];
+    blockers: string[];
+    decisions: string[];
+    rejectedApproaches: string[];
+    nextStep: string | null;
+    workspaceState: CheckpointWorkspaceState;
+    recentEvents: CapsuleEvent[];
+    partial: boolean;
+    olderEventsCursor: string | null;
+    createdAt: number;
+}
+
+declare const ADAPTER_CONTRACT_VERSION: 1;
+type AdapterCapabilityMode = "mcp-cooperative" | "hook-assisted" | "local-snapshot" | "native-api" | "cli-launch" | "none";
+/** Evidence for one independently testable adapter behavior. */
+interface AdapterCapabilityEvidence {
+    mode: AdapterCapabilityMode;
+    /** ISO-8601 timestamp of the integration check supporting this claim. */
+    verifiedAt?: string;
+    evidence?: string;
+}
+type AdapterCapability = (AdapterCapabilityEvidence & {
+    level: "stable";
+    reason?: string;
+    evidence: string;
+    verifiedAt: string;
+}) | (AdapterCapabilityEvidence & {
+    level: "experimental" | "unsupported";
+    /** Why this behavior cannot be advertised as stable. */
+    reason: string;
+});
+interface AdapterCapabilities {
+    registration: AdapterCapability;
+    history: AdapterCapability;
+    nativeResume: AdapterCapability;
+    append: AdapterCapability;
+    checkpoint: AdapterCapability;
+    fork: AdapterCapability;
+    launch: AdapterCapability;
+}
+interface ReadBudget {
+    maxBytes: number;
+    maxEvents: number;
+    maxDurationMs: number;
+}
+interface TranscriptRoot {
+    path: string;
+    readOnly: true;
+}
+interface AdapterDescriptor {
+    contractVersion: typeof ADAPTER_CONTRACT_VERSION;
+    id: AdapterId;
+    displayName: string;
+    capabilities: AdapterCapabilities;
+    transcriptRoots: readonly TranscriptRoot[];
+    defaultReadBudget: ReadBudget;
+}
+interface AdapterProbeResult {
+    adapterId: AdapterId;
+    available: boolean;
+    checkedAt: string;
+    clientVersion?: string;
+    sourceFormatVersion?: string;
+    diagnostics: readonly string[];
+    capabilities: AdapterCapabilities;
+}
+interface NativeSessionReference {
+    adapterId: AdapterId;
+    nativeSessionId: string;
+    locator: string;
+    /** Present only when the native source itself proves the workspace root. */
+    workspaceRoot?: string;
+}
+type VerifiedWorkspaceEvidenceSource = "claude.cwd" | "codex.session_meta.cwd" | "continue.workspaceDirectory";
+type WorkspaceHintSource = "claude.path-key" | "cursor.path-key";
+/**
+ * Native-source evidence for workspace ownership.
+ *
+ * Encoded directory names are intentionally hints: they are lossy and must
+ * never be promoted to a workspace binding. Only an explicit native metadata
+ * field can produce `verified` evidence and a `reference.workspaceRoot`.
+ */
+type WorkspaceEvidence = {
+    status: "verified";
+    root: string;
+    source: VerifiedWorkspaceEvidenceSource;
+} | {
+    status: "hint";
+    source: WorkspaceHintSource;
+} | {
+    status: "unknown";
+    source: "none";
+};
+interface DiscoveredNativeSession {
+    reference: NativeSessionReference;
+    workspaceEvidence: WorkspaceEvidence;
+    title?: string;
+    startedAt?: number;
+    updatedAt: number;
+    clientVersion?: string;
+    model?: string;
+    gitBranch?: string;
+    gitCommit?: string;
+    metadata?: Record<string, unknown>;
+}
+interface TranscriptCursor {
+    kind: "byte" | "line" | "sequence" | "snapshot" | (string & {});
+    value: string;
+    lastSourceEventId?: string;
+}
+interface TranscriptDiagnostic {
+    level: "warning" | "error";
+    code: string;
+    message: string;
+    sourceSequence?: number;
+}
+interface TranscriptSnapshot {
+    reference: NativeSessionReference;
+    /** Workspace evidence derived from the same immutable source read as events. */
+    workspaceEvidence: WorkspaceEvidence;
+    events: readonly NormalizedEventInput[];
+    sourceFingerprint: string;
+    parserVersion: string;
+    nextCursor: TranscriptCursor;
+    truncated: boolean;
+    diagnostics: readonly TranscriptDiagnostic[];
+}
+interface AdapterDiscoveryRequest {
+    workspaceRoot?: string;
+    budget: ReadBudget;
+}
+interface TranscriptSnapshotRequest {
+    reference: NativeSessionReference;
+    budget: ReadBudget;
+    cursor?: TranscriptCursor;
+}
+interface NativeReferenceRequest {
+    nativeSessionId?: string;
+    locator?: string;
+    workspaceRoot?: string;
+}
+interface NativeLaunchRequest {
+    workspaceRoot: string;
+    handoffToken: string;
+}
+interface NativeLaunchResult {
+    launched: boolean;
+    nativeSessionId?: string;
+    message?: string;
+}
+interface AdapterRegistrationResult {
+    changed: boolean;
+    registered: boolean;
+    reason?: string;
+}
+/**
+ * Boundary implemented by each client integration.
+ *
+ * There are deliberately no transcript-write methods. Native transcript stores
+ * are inputs owned by their clients and remain read-only to AgentCache.
+ */
+interface AgentClientAdapter {
+    readonly id: AdapterId;
+    descriptor(): AdapterDescriptor;
+    probe(): Promise<AdapterProbeResult>;
+    register(): Promise<AdapterRegistrationResult>;
+    unregister(): Promise<AdapterRegistrationResult>;
+    discover?(request: AdapterDiscoveryRequest): Promise<readonly DiscoveredNativeSession[]>;
+    readSnapshot?(request: TranscriptSnapshotRequest): Promise<TranscriptSnapshot>;
+    resolveNativeReference?(request: NativeReferenceRequest): Promise<NativeSessionReference | undefined>;
+    launchNative?(request: NativeLaunchRequest): Promise<NativeLaunchResult>;
+}
+
+interface Device {
+    deviceId: string;
+    displayName: string | null;
+    createdAt: number;
+    lastSeenAt: number;
+}
+type WorkspaceKind = "git" | "directory" | "none";
+interface Workspace {
+    workspaceId: string;
+    displayName: string;
+    kind: WorkspaceKind;
+    createdAt: number;
+    updatedAt: number;
+    archivedAt: number | null;
+    metadata: JsonObject;
+}
+interface WorkspaceLocation {
+    locationId: string;
+    workspaceId: string;
+    deviceId: string;
+    rootPath: string;
+    canonicalGitRemote: string | null;
+    gitCommonDir: string | null;
+    firstSeenAt: number;
+    lastSeenAt: number;
+}
+type WorkspaceResolutionSource = "existing-location" | "created";
+interface ResolveWorkspaceLocationInput {
+    deviceId: string;
+    rootPath: string;
+    canonicalGitRemote: string | null;
+    gitCommonDir: string | null;
+    proposedWorkspace: Workspace;
+    proposedLocationId: string;
+    seenAt: number;
+}
+type ResolveWorkspaceLocationResult = {
+    status: "bound";
+    source: WorkspaceResolutionSource;
+    location: WorkspaceLocation;
+    /** True when a previously known Git identity no longer matches this exact path. */
+    gitIdentityMismatch: boolean;
+} | {
+    status: "unassigned";
+    reason: "ambiguous-git-remote";
+    candidateWorkspaceIds: string[];
+};
+interface SessionListFilter {
+    workspaceId?: string | null;
+    status?: SessionState;
+    adapterId?: AdapterId;
+    limit?: number;
+}
+interface AppendEventInput extends NormalizedEventInput {
+    eventId?: string;
+    parentEventId?: string | null;
+    contentHash?: string;
+    redactionState?: SessionEvent["redactionState"];
+}
+interface AppendEventsInput {
+    sessionId: string;
+    legId: string;
+    events: readonly AppendEventInput[];
+    expectedHeadSequence?: number;
+    ingestedAt?: number;
+    cursor?: SourceCursor;
+}
+interface AppendEventsResult {
+    inserted: number;
+    events: SessionEvent[];
+    headEventId: string | null;
+    headSequence: number;
+}
+interface AppendEventsWithLeaseInput extends AppendEventsInput {
+    leaseToken: string;
+    expectedAdapterId: AdapterId;
+    expectedDeviceId: string;
+    now?: number;
+    renewLeaseExpiresAt: number;
+    /**
+     * Portable API timestamps are assigned by the receiving service. On an
+     * idempotent retry, reuse the durable timestamp before comparing content so
+     * two processes racing the same key return the original event.
+     */
+    reusePersistedOccurredAtOnRetry?: boolean;
+}
+interface AppendEventsWithLeaseResult extends AppendEventsResult {
+    lease: SessionLease;
+}
+interface AppendEventsAsTransientWriterInput {
+    leg: ClientLeg;
+    leaseToken: string;
+    now: number;
+    leaseExpiresAt: number;
+    append: AppendEventsInput;
+    reusePersistedOccurredAtOnRetry?: boolean;
+}
+interface AppendEventsAsTransientWriterResult extends AppendEventsResult {
+    leg: ClientLeg;
+}
+interface CreateCheckpointWithLeaseInput {
+    checkpoint: SessionCheckpoint;
+    expectedHeadSequence: number;
+    legId: string;
+    leaseToken: string;
+    expectedAdapterId: AdapterId;
+    expectedDeviceId: string;
+    now?: number;
+    renewLeaseExpiresAt: number;
+}
+interface CreateCheckpointWithLeaseResult {
+    checkpoint: SessionCheckpoint;
+    lease: SessionLease;
+}
+interface CreateCheckpointAsTransientWriterInput {
+    leg: ClientLeg;
+    leaseToken: string;
+    now: number;
+    leaseExpiresAt: number;
+    checkpoint: SessionCheckpoint;
+    expectedHeadSequence: number;
+}
+interface CreateCheckpointAsTransientWriterResult {
+    checkpoint: SessionCheckpoint;
+    leg: ClientLeg;
+}
+type IngestionTitleSource = "native" | "user" | "fallback";
+/**
+ * One adapter page plus the identity and metadata required to commit it.
+ * `proposedSession` is used only when import mode wins the native-leg claim.
+ */
+interface IngestTranscriptPageInput {
+    mode: "import" | "attach";
+    proposedSession: PortableSession | null;
+    proposedLeg: ClientLeg;
+    targetSessionId: string | null;
+    rootScopeId: string;
+    events: readonly AppendEventInput[];
+    expectedHeadSequence?: number;
+    expectedCursor: SourceCursor | null;
+    nextCursor: SourceCursor;
+    titleCandidate: {
+        title: string;
+        source: IngestionTitleSource;
+    };
+    sessionMetadata: JsonObject;
+    legMetadata: JsonObject;
+    updatedAt: number;
+}
+interface IngestTranscriptPageResult extends AppendEventsResult {
+    session: PortableSession;
+    leg: ClientLeg;
+    cursor: SourceCursor;
+    createdSession: boolean;
+    createdLeg: boolean;
+}
+interface MarkIngestionSourceStatusInput {
+    expectedCursor: SourceCursor;
+    rootScopeId: string;
+    status: SourceCursor["status"];
+    lastError: string;
+    lastSeenAt: number;
+}
+interface CreateForkInput {
+    session: PortableSession;
+    parentSessionId: string;
+    expectedParentHeadSequence: number;
+    forkedFromCheckpointId: string;
+    forkedFromEventId: string;
+    createdByLegId: string | null;
+    reason: string | null;
+    createdAt: number;
+}
+interface CreateForkAndAcquireLeaseInput {
+    fork: CreateForkInput;
+    destinationLeg: ClientLeg;
+    leaseToken: string;
+    now?: number;
+    leaseExpiresAt: number;
+}
+interface CreateForkAndAcquireLeaseResult {
+    session: PortableSession;
+    fork: CheckpointAnchoredFork;
+    leg: ClientLeg;
+    lease: SessionLease;
+}
+interface CheckpointAnchoredFork extends SessionFork {
+    forkedFromCheckpointId: string;
+}
+interface CreateHandoffInput {
+    handoffId: string;
+    sessionId: string;
+    checkpointId: string;
+    workspaceId: string;
+    targetAdapterId: AdapterId;
+    mode: HandoffMode;
+    token: string;
+    createdAt: number;
+    expiresAt: number;
+    createdHeadSequence: number;
+    allowsLeaseTakeover?: boolean;
+    expectedSourceLeaseGeneration?: number | null;
+    /** Hash of the exact source lease being authorized for replacement. */
+    expectedSourceLeaseTokenHash?: string | null;
+    forkTitle?: string | null;
+    forkReason?: string | null;
+    capsule: ResumeCapsule;
+}
+interface ConsumeHandoffInput {
+    handoffId: string;
+    token: string;
+    targetAdapterId: AdapterId;
+    workspaceId: string;
+    now?: number;
+}
+interface ConsumeHandoffAndAcquireLeaseInput extends ConsumeHandoffInput {
+    destinationLeg: ClientLeg;
+    leaseToken: string;
+    leaseExpiresAt: number;
+    fork?: CreateForkInput;
+}
+interface ConsumeHandoffAndAcquireLeaseResult {
+    handoff: Handoff;
+    session: PortableSession;
+    leg: ClientLeg;
+    lease: SessionLease;
+    fork: CheckpointAnchoredFork | null;
+}
+interface AcquireLeaseInput {
+    sessionId: string;
+    legId: string;
+    token: string;
+    now?: number;
+    expiresAt: number;
+}
+interface OpenSessionAndAcquireLeaseInput {
+    session: PortableSession;
+    leg: ClientLeg;
+    leaseToken: string;
+    now?: number;
+    leaseExpiresAt: number;
+}
+interface OpenSessionAndAcquireLeaseResult {
+    session: PortableSession;
+    leg: ClientLeg;
+    lease: SessionLease;
+}
+/**
+ * Persistence boundary for the portable v2 session model.
+ *
+ * Bearer tokens cross this interface only in plaintext and are hashed by the
+ * implementation before they reach durable storage.
+ */
+interface SessionRepository {
+    close(): void;
+    upsertDevice(device: Device): Device;
+    getDevice(deviceId: string): Device | null;
+    createWorkspace(workspace: Workspace): Workspace;
+    updateWorkspace(workspace: Workspace): Workspace;
+    getWorkspace(workspaceId: string): Workspace | null;
+    listWorkspaces(): Workspace[];
+    saveWorkspaceLocation(location: WorkspaceLocation): WorkspaceLocation;
+    getWorkspaceLocation(locationId: string): WorkspaceLocation | null;
+    getWorkspaceLocationForPath(deviceId: string, rootPath: string): WorkspaceLocation | null;
+    listWorkspaceLocations(workspaceId: string): WorkspaceLocation[];
+    findWorkspaceLocationsByGitRemote(canonicalGitRemote: string): WorkspaceLocation[];
+    resolveWorkspaceLocation(input: ResolveWorkspaceLocationInput): ResolveWorkspaceLocationResult;
+    createSession(session: PortableSession): PortableSession;
+    openSessionAndAcquireLease(input: OpenSessionAndAcquireLeaseInput): OpenSessionAndAcquireLeaseResult;
+    updateSession(session: PortableSession): PortableSession;
+    getSession(sessionId: string): PortableSession | null;
+    listSessions(filter?: SessionListFilter): PortableSession[];
+    createLeg(leg: ClientLeg): ClientLeg;
+    updateLeg(leg: ClientLeg): ClientLeg;
+    getLeg(legId: string): ClientLeg | null;
+    findLeg(deviceId: string, adapterId: AdapterId, nativeSessionId: string): ClientLeg | null;
+    listLegs(sessionId: string, limit?: number): ClientLeg[];
+    appendEvents(input: AppendEventsInput): AppendEventsResult;
+    appendEventsWithLease(input: AppendEventsWithLeaseInput): AppendEventsWithLeaseResult;
+    appendEventsAsTransientWriter(input: AppendEventsAsTransientWriterInput): AppendEventsAsTransientWriterResult;
+    ingestTranscriptPage(input: IngestTranscriptPageInput): IngestTranscriptPageResult;
+    markIngestionSourceStatus(input: MarkIngestionSourceStatusInput): SourceCursor;
+    getEvent(eventId: string): SessionEvent | null;
+    listEvents(sessionId: string, options?: {
+        beforeSequence?: number;
+        limit?: number;
+    }): SessionEvent[];
+    saveSourceCursor(cursor: SourceCursor): SourceCursor;
+    getSourceCursor(sourceId: string): SourceCursor | null;
+    findSourceCursor(deviceId: string, adapterId: AdapterId, locator: string): SourceCursor | null;
+    createCheckpoint(checkpoint: SessionCheckpoint, expectedHeadSequence?: number): SessionCheckpoint;
+    createCheckpointWithLease(input: CreateCheckpointWithLeaseInput): CreateCheckpointWithLeaseResult;
+    createCheckpointAsTransientWriter(input: CreateCheckpointAsTransientWriterInput): CreateCheckpointAsTransientWriterResult;
+    getCheckpoint(checkpointId: string): SessionCheckpoint | null;
+    listCheckpoints(sessionId: string, limit?: number): SessionCheckpoint[];
+    createFork(input: CreateForkInput): CheckpointAnchoredFork;
+    createForkAndAcquireLease(input: CreateForkAndAcquireLeaseInput): CreateForkAndAcquireLeaseResult;
+    getFork(forkSessionId: string): CheckpointAnchoredFork | null;
+    listForks(parentSessionId: string, limit?: number): CheckpointAnchoredFork[];
+    createHandoff(input: CreateHandoffInput): Handoff;
+    getHandoff(handoffId: string): Handoff | null;
+    listHandoffs(sessionId?: string, includeConsumed?: boolean, limit?: number): Handoff[];
+    listPendingHandoffs(workspaceId: string, now: number, limit?: number): Handoff[];
+    consumeHandoff(input: ConsumeHandoffInput): Handoff;
+    consumeHandoffAndAcquireLease(input: ConsumeHandoffAndAcquireLeaseInput): ConsumeHandoffAndAcquireLeaseResult;
+    cancelHandoff(handoffId: string): boolean;
+    acquireLease(input: AcquireLeaseInput): SessionLease;
+    getLease(sessionId: string): SessionLease | null;
+    validateLease(sessionId: string, legId: string, token: string, now?: number): SessionLease;
+    releaseLease(sessionId: string, legId: string, token: string): boolean;
+}
+
+type RootBindingSource = WorkspaceResolutionSource | "unassigned";
+interface RootBindingBase {
+    /** Ephemeral, server-issued authority handle; never derived from a path. */
+    rootId: string;
+    /** Optional bounded client-facing label; never used as workspace authority. */
+    displayName?: string;
+    /** Warning only; the exact canonical device path remains the authority boundary. */
+    gitIdentityMismatch?: true;
+    rootPath: string;
+    canonicalGitRemote: string | null;
+    gitCommonDir: string | null;
+}
+interface AssignedRootBinding extends RootBindingBase {
+    status: "bound";
+    workspaceId: string;
+    locationId: string;
+    source: Exclude<RootBindingSource, "unassigned">;
+}
+interface UnassignedRootBinding extends RootBindingBase {
+    status: "unassigned";
+    workspaceId: null;
+    locationId: null;
+    source: "unassigned";
+    reason: "ambiguous-git-remote";
+    candidateWorkspaceIds: string[];
+}
+type RootBinding = AssignedRootBinding | UnassignedRootBinding;
+
+interface McpClientRoot {
+    uri: string;
+    name?: string;
+}
+interface CanonicalizedClientRoot {
+    rootPath: string;
+    displayName: string;
+}
+interface StartMcpServerOptions {
+    /** Trusted process identity supplied by the integration, never by a tool call. */
+    adapterId: AdapterId;
+    /** Stable machine identity supplied by shared runtime configuration. */
+    deviceId: string;
+    /** Test/integration seams; normal callers use the v2 local repository and registry. */
+    repository?: SessionRepository;
+    adapters?: readonly AgentClientAdapter[];
+    resolveRoot?: (canonicalRoot: string, deviceId: string, repository: SessionRepository) => RootBinding;
+    server?: Server;
+    transport?: Transport;
+}
+/**
+ * Decodes and canonicalizes roots with URL semantics. There is deliberately no
+ * process.cwd() fallback: absent roots mean absent workspace authority.
+ */
+declare function canonicalizeClientRootUris(roots: readonly McpClientRoot[]): string[];
+/** Preserve only a safe human label alongside each canonical authority root. */
+declare function canonicalizeClientRoots(roots: readonly McpClientRoot[]): CanonicalizedClientRoot[];
+/**
+ * Starts the beta session-continuity server. Legacy knowledge, compilation,
+ * policy, migration, update, and background jobs are intentionally absent.
+ */
+declare function startMcpServer(options?: StartMcpServerOptions): Promise<void>;
+
+export { type CanonicalizedClientRoot, type McpClientRoot, type StartMcpServerOptions, canonicalizeClientRootUris, canonicalizeClientRoots, startMcpServer };