@gajae-code/coding-agent 0.10.1 → 0.11.0

package/dist/types/sdk/bus/telegram-setup.d.ts

@@ -0,0 +1,128 @@
+export declare const DEFAULT_TELEGRAM_SETUP_API_BASE = "https://api.telegram.org";
+export declare const DEFAULT_TELEGRAM_SETUP_POLL_TIMEOUT_MS = 60000;
+export declare const DEFAULT_TELEGRAM_SETUP_POLL_INTERVAL_MS = 1000;
+export type TelegramThreadedModeState = "enabled" | "disabled" | "unknown";
+export type TelegramThreadedModeLabel = "verified" | "unverified" | "unknown";
+export type TelegramSetupPairingSource = "discovered" | "provided" | "reused";
+export type TelegramSetupFailureStatus = "error" | "cancelled" | "requires_explicit_chat" | "ownership_lost" | "aborted";
+export interface TelegramSetupTimers {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+export interface TelegramSetupDeps {
+    fetchImpl: typeof fetch;
+    apiBase?: string;
+    timers?: TelegramSetupTimers;
+}
+/** Current daemon ownership facts collected by the caller before setup starts. */
+export interface TelegramSetupPreflight {
+    storedChatId?: string;
+    daemon?: {
+        live: boolean;
+        tokenFingerprint?: string;
+        /** Required with a live daemon so reuse verifies the complete token/chat identity. */
+        chatId?: string;
+    };
+}
+export type TelegramSetupPollingPolicy = {
+    kind: "discover";
+} | {
+    kind: "reuse_stored_chat";
+    chatId: string;
+} | {
+    kind: "validate_explicit_chat";
+    chatId: string;
+} | {
+    kind: "requires_explicit_chat";
+} | {
+    kind: "cancel_foreign_or_unknown_owner";
+    identity: "foreign" | "unknown";
+};
+export type TelegramSetupEvent = {
+    kind: "token_validated";
+    message: string;
+} | {
+    kind: "threaded_mode_guidance";
+    message: string;
+} | {
+    kind: "rejected_chat";
+    message: string;
+};
+export interface TelegramSetupSuccess {
+    ok: true;
+    chatId: string;
+    tokenFingerprint: string;
+    threadedMode: TelegramThreadedModeState;
+    threadedLabel: TelegramThreadedModeLabel;
+    pairingSource: TelegramSetupPairingSource;
+}
+export interface TelegramSetupFailure {
+    ok: false;
+    status: TelegramSetupFailureStatus;
+    detail: string;
+}
+export type TelegramSetupResult = TelegramSetupSuccess | TelegramSetupFailure;
+export interface TelegramBot {
+    id: number;
+    isBot?: boolean;
+    firstName?: string;
+    username?: string;
+    hasTopicsEnabled?: boolean;
+    allowsUsersToCreateTopics?: boolean;
+}
+export type TelegramTokenValidationResult = {
+    ok: true;
+    bot: TelegramBot;
+    threadedMode: TelegramThreadedModeState;
+} | TelegramSetupFailure;
+export type TelegramPrivateChatValidationResult = {
+    ok: true;
+    chatId: string;
+} | TelegramSetupFailure;
+export interface RunTelegramSetupInput {
+    token: string;
+    preflight: TelegramSetupPreflight;
+    /**
+     * Re-reads daemon ownership immediately before any `getUpdates` call. It is
+     * mandatory for discovery because an earlier preflight cannot own Telegram's
+     * single-poller slot.
+     */
+    revalidatePreflight?: (signal?: AbortSignal) => Promise<TelegramSetupPreflight>;
+    chatId?: string;
+    interactive: boolean;
+    threadedModePrompt?: (message: string) => Promise<string>;
+    pollTimeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onEvent?: (event: TelegramSetupEvent) => void;
+    deps: TelegramSetupDeps;
+}
+export declare function withTelegramSetupLease<T>(token: string, operation: () => Promise<T>): Promise<T>;
+/** Validate a token with getMe without exposing it in diagnostics or results. */
+export declare function validateTelegramBotToken(input: {
+    token: string;
+    deps: TelegramSetupDeps;
+    signal?: AbortSignal;
+}): Promise<TelegramTokenValidationResult>;
+/** Validate that a supplied or stored chat is an actual Telegram private chat. */
+export declare function validateTelegramPrivateChat(input: {
+    token: string;
+    chatId: string;
+    deps: TelegramSetupDeps;
+    signal?: AbortSignal;
+}): Promise<TelegramPrivateChatValidationResult>;
+/**
+ * Decide whether setup may call getUpdates. Any live daemon is a hard polling
+ * boundary: only a verified complete token/chat identity may reuse the stored
+ * chat; setup never polls while any live owner exists.
+ */
+export declare function resolveTelegramSetupPollingPolicy(input: {
+    token: string;
+    preflight: TelegramSetupPreflight;
+    chatId?: string;
+}): TelegramSetupPollingPolicy;
+/**
+ * Validate a token, assess Threaded Mode, and obtain a private chat according
+ * to the daemon poller-contention policy. No settings are written here.
+ */
+export declare function runTelegramSetup(input: RunTelegramSetupInput): Promise<TelegramSetupResult>;

package/dist/types/{notifications → sdk/bus}/topic-registry.d.ts

@@ -30,6 +30,10 @@ export interface TopicRecord {
     userNameUpdateId?: number;
     /** Stable repo/branch identity used when topic names are user-owned or customized. */
     identityKey?: string;
+    /** Last SDK event generation durably consumed by the notification daemon. */
+    replayGeneration?: number;
+    /** Last SDK event sequence durably consumed within replayGeneration. */
+    replaySeq?: number;
 }
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
@@ -68,6 +72,13 @@ export declare class TopicRegistry {
     needsIdentity(sessionId: string): boolean;
     /** Remember stable repo/branch identity independently of the displayed name. */
     markIdentityKey(sessionId: string, identityKey: string): boolean;
+    /** Last durably consumed SDK event cursor for reconnect replay. */
+    replayCursor(sessionId: string): {
+        generation: number;
+        seq: number;
+    } | undefined;
+    /** Advance the durable reconnect cursor without allowing stale responses to move it backwards. */
+    markReplayCursor(sessionId: string, generation: number, seq: number): boolean;
     /** Whether daemon identity reconciliation should apply `name`. */
     needsRename(sessionId: string, name: string): boolean;
     /** The user-owned name that must be preserved, when one exists. */

package/dist/types/sdk/cli/index.d.ts

@@ -0,0 +1 @@
+export * from "./session-cli";

package/dist/types/sdk/cli/session-cli.d.ts

@@ -0,0 +1,19 @@
+export type SdkSessionCliAction = "list" | "control" | "query" | "global";
+export interface SdkSessionCliArgs {
+    action?: string;
+    sessionId?: string;
+    operation?: string;
+    query?: string;
+    jsonInput?: string;
+    jsonInputFile?: string;
+    idempotencyKey?: string;
+    jsonInputStdin?: boolean;
+    confirm?: boolean;
+    cursor?: string;
+    showEndpointCredential?: boolean;
+    yes?: boolean;
+    repo?: string;
+    agentDir?: string;
+}
+/** Runs the pure-SDK `gjc daemon session` command family. */
+export declare function runSdkSessionCli(args: SdkSessionCliArgs, writeOutput?: (value: unknown) => void, setExitCode?: (exitCode: 1 | 2) => void): Promise<void>;

package/dist/types/sdk/client/client.d.ts

@@ -0,0 +1 @@
+export * from "@gajae-code/bridge-client";

package/dist/types/sdk/client/discovery.d.ts

@@ -0,0 +1,27 @@
+import { type BrokerDiscovery } from "../broker/discovery";
+export interface SdkSessionEndpoint {
+    sessionId: string;
+    url: string;
+    token: string;
+    path: string;
+}
+export interface SdkDiscoveryWarning {
+    code: "discovery_error";
+    path: string;
+    message: string;
+}
+export interface SdkSessionEndpointList {
+    endpoints: SdkSessionEndpoint[];
+    warnings: SdkDiscoveryWarning[];
+}
+export declare class SdkDiscoveryError extends Error {
+    readonly path: string;
+    readonly code = "discovery_error";
+    constructor(path: string, message: string);
+}
+/** Lists endpoint files and returns individual malformed or unreadable records as warnings. */
+export declare function listSdkSessionEndpoints(repo: string): Promise<SdkSessionEndpointList>;
+/** Resolves one per-session SDK endpoint discovery file. */
+export declare function readSdkSessionEndpoint(repo: string, sessionId: string): Promise<SdkSessionEndpoint | null>;
+/** Reads the agent-global broker discovery record. */
+export declare function readSdkBrokerDiscovery(agentDir: string): Promise<BrokerDiscovery | null>;

package/dist/types/sdk/client/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./discovery";

package/dist/types/sdk/host/control/dispatch.d.ts

@@ -0,0 +1,34 @@
+import { type Operation } from "../../protocol/operation-registry";
+import type { ControlSurface, ControlValue } from "./operations";
+export interface ControlRequest {
+    id: string;
+    operation: string;
+    input: unknown;
+    expectedRevision?: string;
+    idempotencyKey?: string;
+    confirm?: boolean;
+}
+export type ControlErrorCode = string;
+export interface ControlError {
+    code: ControlErrorCode;
+    message: string;
+    currentRevision?: string;
+    details?: ControlValue;
+}
+export interface ControlResponse {
+    id: string;
+    ok: boolean;
+    result?: ControlValue;
+    error?: ControlError;
+}
+/** An error whose code is intentionally safe to expose on the control protocol. */
+export declare class TypedControlError extends Error {
+    readonly code: ControlErrorCode;
+    constructor(code: ControlErrorCode, message: string);
+}
+/** Busy is reserved for explicitly typed transient unavailability. */
+export declare class BusyError extends TypedControlError {
+    constructor(message?: string);
+}
+/** Dispatches a registry-defined per-session control operation. */
+export declare function dispatchControl(surface: ControlSurface, registryRow: Operation | undefined, request: ControlRequest): Promise<ControlResponse>;

package/dist/types/sdk/host/control/index.d.ts

@@ -0,0 +1,2 @@
+export { BusyError, type ControlError, type ControlErrorCode, type ControlRequest, type ControlResponse, dispatchControl, TypedControlError, } from "./dispatch";
+export type { ControlInput, ControlSurface, ControlValue } from "./operations";

package/dist/types/sdk/host/control/operations.d.ts

@@ -0,0 +1,65 @@
+export type ControlValue = unknown;
+export type ControlInput = Record<string, unknown>;
+/**
+ * Narrow host contract used by control dispatch. Implementations adapt an
+ * AgentSession and its controllers without exposing those concrete types here.
+ */
+export interface ControlSurface {
+    prompt(text: string, images?: ControlValue): Promise<ControlValue> | ControlValue;
+    steer(text: string): Promise<ControlValue> | ControlValue;
+    followUp(text: string): Promise<ControlValue> | ControlValue;
+    abort(): Promise<ControlValue> | ControlValue;
+    abortAndPrompt(text: string): Promise<ControlValue> | ControlValue;
+    answerAsk(id: string, answer: ControlValue): Promise<ControlValue> | ControlValue;
+    answerGate(id: string, response: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
+    approvePlan(id: string, choice: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
+    invokeSkill(name: string, args: ControlValue): Promise<ControlValue> | ControlValue;
+    setPlanMode(on: boolean): Promise<ControlValue> | ControlValue;
+    operateGoal(op: string, objective?: string): Promise<ControlValue> | ControlValue;
+    replaceTodo(items: ControlValue): Promise<ControlValue> | ControlValue;
+    setModel(id: string, thinkingLevel?: ControlValue): Promise<ControlValue> | ControlValue;
+    cycleModel(): Promise<ControlValue> | ControlValue;
+    setThinking(level: ControlValue): Promise<ControlValue> | ControlValue;
+    cycleThinking(): Promise<ControlValue> | ControlValue;
+    setPermissionMode(mode: ControlValue): Promise<ControlValue> | ControlValue;
+    setQueueMode(kind: string, mode: ControlValue): Promise<ControlValue> | ControlValue;
+    runCompaction(): Promise<ControlValue> | ControlValue;
+    setAutoCompaction(on: boolean): Promise<ControlValue> | ControlValue;
+    setAutoRetry(on: boolean): Promise<ControlValue> | ControlValue;
+    abortRetry(): Promise<ControlValue> | ControlValue;
+    executeBash(cmd: string): Promise<ControlValue> | ControlValue;
+    abortBash(): Promise<ControlValue> | ControlValue;
+    newSession(): Promise<ControlValue> | ControlValue;
+    forkSession(): Promise<ControlValue> | ControlValue;
+    resumeSession(id: string): Promise<ControlValue> | ControlValue;
+    closeSession(): Promise<ControlValue> | ControlValue;
+    switchSession(id: string): Promise<ControlValue> | ControlValue;
+    branchSession(entryId: string): Promise<ControlValue> | ControlValue;
+    renameSession(name: string): Promise<ControlValue> | ControlValue;
+    handoffSession(target: ControlValue): Promise<ControlValue> | ControlValue;
+    exportHtml(): Promise<ControlValue> | ControlValue;
+    patchConfig(patch: ControlValue): Promise<ControlValue> | ControlValue;
+    reloadRuntime(components: ControlValue): Promise<ControlValue> | ControlValue;
+    login(provider: string): Promise<ControlValue> | ControlValue;
+    registerHostTools(defs: ControlValue): Promise<ControlValue> | ControlValue;
+    registerHostUri(defs: ControlValue): Promise<ControlValue> | ControlValue;
+    setServiceTier(tier: ControlValue): Promise<ControlValue> | ControlValue;
+    setActiveTools(names: ControlValue): Promise<ControlValue> | ControlValue;
+    removeQueueMessage(id: string): Promise<ControlValue> | ControlValue;
+    moveQueueMessage(id: string, position: {
+        before?: string;
+        after?: string;
+    }): Promise<ControlValue> | ControlValue;
+    updateQueueMessage(id: string, patch: ControlValue): Promise<ControlValue> | ControlValue;
+    setExtensionEnabled(id: string, on: boolean): Promise<ControlValue> | ControlValue;
+    clearContext(confirm: boolean): Promise<ControlValue> | ControlValue;
+    deleteSession(id: string, confirm: boolean): Promise<ControlValue> | ControlValue;
+    moveCwd(path: string): Promise<ControlValue> | ControlValue;
+    retryLast(): Promise<ControlValue> | ControlValue;
+    retryNow(): Promise<ControlValue> | ControlValue;
+    backgroundBash(): Promise<ControlValue> | ControlValue;
+    /** Returns the current revision for a registry revision resource. */
+    /** Installed per-session registry rows. Dispatch rejects other rows before invoking a surface method. */
+    installedOperations?: ReadonlySet<string>;
+    revisionProvider?(resource: string): Promise<string | undefined> | string | undefined;
+}

package/dist/types/sdk/host/events.d.ts

@@ -0,0 +1,35 @@
+import type { SdkFrame } from "./types";
+export interface EventFrame extends SdkFrame {
+    type: "event";
+    generation: number;
+    seq: number;
+}
+export type EventReplayGap = {
+    kind: "generation_reset";
+    fromGeneration: number;
+    toGeneration: number;
+    resyncQueries: string[];
+} | {
+    kind: "sequence_gap";
+    fromSeq: number;
+    toSeq: number;
+    resyncQueries: string[];
+};
+export interface EventReplay {
+    events: EventFrame[];
+    gap?: EventReplayGap;
+}
+export declare class SessionEventStream {
+    #private;
+    constructor(options?: {
+        generation?: number;
+        ringSize?: number;
+        resyncQueryIds?: string[];
+    });
+    get generation(): number;
+    get sequence(): number;
+    restart(): number;
+    emit(frame: SdkFrame): EventFrame;
+    /** Replays retained current-generation events and reports any required resynchronization. */
+    replay(lastSeq: number, generation?: number): EventReplay;
+}

package/dist/types/sdk/host/host.d.ts

@@ -0,0 +1,35 @@
+import { type EventFrame, SessionEventStream } from "./events";
+import { ReverseLeaseRuntime } from "./reverse-leases";
+import type { BrokerIndexWriter, HostEndpointAdapters, SdkFrame } from "./types";
+export type SdkRequestObserver = (kind: "control" | "query", connectionId: string, frame: SdkFrame) => void;
+export interface SessionSdkHostOptions extends HostEndpointAdapters {
+    control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+    query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+    /** Best-effort diagnostic observation of accepted control/query frames. */
+    onRequest?: SdkRequestObserver;
+    /** Runs only after a successful control response has been sent to the client. */
+    afterControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame) => void | Promise<void>;
+    installProviderDefinitions?: (capability: string, definitions: unknown) => void;
+    onProviderDefinitionsRemoved?: (capability: string) => void;
+    onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
+}
+/** SDK hosting is independent of notification configuration. Only root sessions host an endpoint. */
+export declare function shouldHostSdk(_settings: unknown, isTopLevel: boolean, env?: NodeJS.ProcessEnv): boolean;
+/** Adapter-based session host; bus wiring owns NotificationServer creation and transport framing. */
+export declare class SessionSdkHost {
+    #private;
+    readonly events: SessionEventStream;
+    readonly reverse: ReverseLeaseRuntime;
+    constructor(options: SessionSdkHostOptions);
+    get started(): boolean;
+    get generation(): number;
+    /** Current installed definitions for a live provider capability. */
+    getProviderDefinitions(capability: string): unknown | undefined;
+    /** Release reverse leases after the transport reports a WebSocket disconnect. */
+    handleDisconnect(connectionId: string): void;
+    /** Adds an event to the resumable event ring. Transport delivery is owned by bus wiring. */
+    emitEvent(frame: SdkFrame): EventFrame;
+    start(): Promise<"started" | "already">;
+    stop(): Promise<"stopped" | "already">;
+    registerWithBroker(writer: BrokerIndexWriter): Promise<void>;
+}

package/dist/types/sdk/host/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./events";
+export * from "./host";
+export * from "./reverse-leases";
+export * from "./types";

package/dist/types/sdk/host/query/cursor.d.ts

@@ -0,0 +1,62 @@
+import { type RevisionStore } from "./revision-store.js";
+export declare const CURSOR_TTL_MS: number;
+export declare const MAX_CURSORS_PER_CONNECTION = 32;
+export declare const MAX_CURSORS_PER_SESSION = 128;
+export interface CursorEnvelope {
+    cursorVersion: 1;
+    protocolMajor: 3;
+    sessionId: string;
+    resource: string;
+    revision: string;
+    highWatermark?: unknown;
+    position: unknown;
+    direction: string;
+    pageShape: unknown;
+}
+export interface CursorSelector {
+    queryId: string;
+    entryId?: string;
+    field?: string;
+    fileId?: string;
+    hunkId?: string;
+    resourceKind?: string;
+    resourceId?: string;
+    itemId?: string;
+}
+export interface CursorPosition {
+    offset?: number;
+    byteOffset?: number;
+    selector?: CursorSelector;
+}
+export declare function cursorSelector(position: unknown): CursorSelector | undefined;
+export declare function assertCursorSelector(cursor: CursorSelector | undefined, requested: Partial<CursorSelector>): CursorSelector;
+export interface CursorQueryContext {
+    sessionId: string;
+    resource?: string;
+    resourceId?: string;
+    direction: string;
+    pageShape: unknown;
+}
+export declare class CursorError extends Error {
+    readonly code: "cursor_expired" | "invalid_cursor" | "invalid_input" | "resource_gone" | "snapshot_capacity_exceeded";
+    readonly restartQuery: boolean;
+    constructor(code: "cursor_expired" | "invalid_cursor" | "invalid_input" | "resource_gone" | "snapshot_capacity_exceeded", restartQuery?: boolean, message?: string);
+}
+export declare function canonicalCursorJson(envelope: CursorEnvelope): string;
+export declare function cursorMac(envelope: CursorEnvelope, sessionToken: string | Uint8Array): string;
+export declare function signCursor(envelope: CursorEnvelope, sessionToken: string | Uint8Array): string;
+export declare function verifyCursor(cursor: string, sessionToken: string | Uint8Array): CursorEnvelope | undefined;
+/** Tracks cursor budgets and binds snapshot pins to authenticated cursor strings. */
+export declare class CursorRegistry {
+    #private;
+    private readonly sessionToken;
+    private readonly revisions;
+    private readonly now;
+    constructor(sessionToken: string | Uint8Array, revisions: RevisionStore, now?: () => number);
+    grant(connectionId: string, envelope: CursorEnvelope, resourceKind: string, resourceId: string): Promise<string>;
+    consume(cursor: string, connectionId: string, expected: CursorQueryContext): CursorEnvelope;
+    release(cursor: string): void;
+    close(): void;
+    sweep(): void;
+    get size(): number;
+}

package/dist/types/sdk/host/query/handlers.d.ts

@@ -0,0 +1,70 @@
+import { type CursorRegistry } from "./cursor.js";
+import type { RevisionStore } from "./revision-store.js";
+export declare const TARGET_PAGE_BYTES: number;
+export declare const RESPONSE_CEILING_BYTES: number;
+export interface SessionSurface {
+    getTranscriptEntries(): unknown[] | Promise<unknown[]>;
+    getContextSnapshot(): unknown | Promise<unknown>;
+    getGoalState(): unknown | Promise<unknown>;
+    getTodoState(): unknown | Promise<unknown>;
+    getDiff(): unknown | Promise<unknown>;
+    getUsage(): unknown | Promise<unknown>;
+    getModels(): unknown | Promise<unknown>;
+    getSkillState(): unknown | Promise<unknown>;
+    /** Q12 rows preserve workflow gate fields and include stable durable gate metadata. */
+    getGates(): unknown | Promise<unknown>;
+    getConfigItems(): unknown | Promise<unknown>;
+    getSessionMetadata(): unknown | Promise<unknown>;
+    getStats(): unknown | Promise<unknown>;
+    getBranchCandidates(): unknown | Promise<unknown>;
+    getLastAssistant(): unknown | Promise<unknown>;
+    getCapabilities(): unknown | Promise<unknown>;
+    getAuthProviders(): unknown | Promise<unknown>;
+    getTools(): unknown | Promise<unknown>;
+    getQueueMessages(): unknown | Promise<unknown>;
+    getExtensions(): unknown | Promise<unknown>;
+    getArtifactRange?(id: string, offset: number, length: number): {
+        bytes: Uint8Array;
+        totalBytes: number;
+    } | undefined | Promise<{
+        bytes: Uint8Array;
+        totalBytes: number;
+    } | undefined>;
+    getJobs(): unknown | Promise<unknown>;
+    /** Query rows backed by the session's installed binding map. */
+    installedQueries?: ReadonlySet<string>;
+}
+export interface QueryRequest {
+    id?: string;
+    query: string;
+    input?: Record<string, unknown>;
+    cursor?: string;
+    connectionId: string;
+}
+export interface QueryPage {
+    items: unknown[];
+    complete: boolean;
+    continuationCursor?: string;
+    revision: string;
+    preview?: boolean;
+}
+export interface QueryResponse {
+    id?: string;
+    ok: boolean;
+    page?: QueryPage;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        restartQuery?: boolean;
+    };
+}
+export declare class QueryHandlers {
+    #private;
+    private readonly surface;
+    private readonly sessionId;
+    private readonly revisions;
+    private readonly cursors;
+    constructor(surface: SessionSurface, sessionId: string, revisions: RevisionStore, cursors: CursorRegistry);
+    dispatch(request: QueryRequest): Promise<QueryResponse>;
+}

package/dist/types/sdk/host/query/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./cursor.js";
+export * from "./handlers.js";
+export * from "./revision-store.js";

package/dist/types/sdk/host/query/revision-store.d.ts

@@ -0,0 +1,60 @@
+export declare const MAX_REVISIONS_PER_RESOURCE = 8;
+export declare const MAX_PINNED_REVISIONS = 128;
+export declare const MAX_MEMORY_BYTES: number;
+export declare const SNAPSHOT_TTL_MS: number;
+export declare class RevisionStoreError extends Error {
+    readonly code: "resource_gone" | "snapshot_capacity_exceeded";
+    constructor(code: "resource_gone" | "snapshot_capacity_exceeded", message?: string);
+}
+/** Per-session MVCC snapshots. Payloads hold canonical JSON UTF-8. */
+export declare class RevisionStore {
+    #private;
+    readonly sessionId: string;
+    private readonly now;
+    constructor(sessionId: string, now?: () => number, options?: {
+        storageDir?: string;
+        onReadRange?: (start: number, end: number) => void;
+    });
+    createRevision(resourceKind: string, resourceId: string, payload: unknown): Promise<string>;
+    readRevision(resourceKind: string, resourceId: string, id: string): Promise<unknown>;
+    revisionByteLength(resourceKind: string, resourceId: string, id: string): Promise<number | undefined>;
+    readPage(resourceKind: string, resourceId: string, id: string, offset: number, targetBytes: number): Promise<{
+        items: unknown[];
+        complete: boolean;
+    } | undefined>;
+    /** Returns canonical root JSON in a UTF-8-safe bounded range without parsing it. */
+    readRootRange(resourceKind: string, resourceId: string, id: string, offset: number, length: number): Promise<{
+        body: string;
+        complete: boolean;
+        offset: number;
+    } | undefined>;
+    readStringRange(resourceKind: string, resourceId: string, id: string, field: string, offset: number, length: number): Promise<{
+        body: string;
+        complete: boolean;
+        offset: number;
+    } | undefined>;
+    readIndexedStringRange(resourceKind: string, resourceId: string, id: string, itemId: string, field: string, offset: number, length: number): Promise<{
+        body: string;
+        complete: boolean;
+        offset: number;
+    } | undefined>;
+    describeIndexedItem(resourceKind: string, resourceId: string, id: string, offset: number): Promise<{
+        itemId?: string;
+        fields: string[];
+    } | undefined>;
+    readTranscriptBodyRange(resourceId: string, id: string, entryId: string, offset: number, length: number): Promise<{
+        body: string;
+        complete: boolean;
+        offset: number;
+    } | undefined>;
+    pin(cursorId: string, resourceKind: string, resourceId: string, id: string): Promise<void>;
+    unpin(cursorId: string): void;
+    sweep(): void;
+    close(): Promise<void>;
+    get pinnedCount(): number;
+    get memoryBytes(): number;
+    /** Test-only accounting for the bounded serializer's staging buffer. */
+    get peakBufferedBytes(): number;
+    /** Test-only accounting for a spilled reader's raw chunk and decoded-text buffers. */
+    get peakReadBufferedBytes(): number;
+}

package/dist/types/sdk/host/reverse-leases.d.ts

@@ -0,0 +1,45 @@
+import type { SdkFrame } from "./types";
+export declare const REVERSE_HEARTBEAT_MS = 5000;
+export declare const REVERSE_LEASE_TTL_MS = 15000;
+export declare const REVERSE_RECLAIM_GRACE_MS = 15000;
+export declare const MAX_REVERSE_OUTSTANDING = 64;
+export declare const MAX_REVERSE_PAYLOAD_BYTES: number;
+export declare class ReverseLeaseError extends Error {
+    readonly code: "lease_unavailable" | "lease_expired" | "provider_lease_conflict" | "provider_required" | "not_lease_owner" | "payload_too_large" | "too_many_outstanding" | "unknown_request" | "idempotency_conflict";
+    constructor(code: "lease_unavailable" | "lease_expired" | "provider_lease_conflict" | "provider_required" | "not_lease_owner" | "payload_too_large" | "too_many_outstanding" | "unknown_request" | "idempotency_conflict", message?: "idempotency_conflict" | "lease_expired" | "lease_unavailable" | "not_lease_owner" | "payload_too_large" | "provider_lease_conflict" | "provider_required" | "too_many_outstanding" | "unknown_request");
+}
+export interface ProviderLease {
+    leaseId: string;
+    connectionId: string;
+    capability: string;
+    definitions: unknown;
+    expiresAt: number;
+    graceUntil?: number;
+    active: boolean;
+}
+export interface ReverseLeaseOptions {
+    now?: () => number;
+    leaseTtlMs?: number;
+    sendFrame: (connectionId: string, frame: SdkFrame) => void | Promise<void>;
+    installDefinitions?: (capability: string, definitions: unknown) => void;
+    onCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
+    onDefinitionsRemoved?: (capability: string) => void;
+}
+/** Session-local directed reverse RPC lease registry. */
+export declare class ReverseLeaseRuntime {
+    #private;
+    constructor(options: ReverseLeaseOptions);
+    registerProvider(connectionId: string, capability: string, definitions: unknown, expectedLeaseId?: string, idempotencyKey?: string): ProviderLease;
+    heartbeat(connectionId: string, leaseId: string): ProviderLease;
+    release(connectionId: string, leaseId: string, handoffTo?: string): ProviderLease;
+    disconnect(connectionId: string): void;
+    request(capability: string, method: string, payload: unknown): Promise<unknown>;
+    respond(connectionId: string, id: string, leaseId: string, result: unknown, error?: {
+        code: string;
+        message: string;
+    }): void;
+    getLease(capability: string): ProviderLease | undefined;
+    /** Installed definitions are observable only while their provider lease is live. */
+    getInstalledDefinitions(capability: string): unknown | undefined;
+    dispose(): void;
+}