@mquan/portal 0.0.1

package/dist/src/storage/database.js

@@ -0,0 +1,354 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const MIGRATIONS = [
+    {
+        version: 1,
+        name: "durable_portal_records",
+        sql: `
+      CREATE TABLE sessions (
+        portal_session_id TEXT PRIMARY KEY,
+        provider TEXT NOT NULL CHECK (provider IN ('codex', 'claude')),
+        installation TEXT NOT NULL,
+        account_fingerprint TEXT NOT NULL,
+        vendor_session_id TEXT NOT NULL,
+        workspace TEXT,
+        title TEXT,
+        observed_at INTEGER NOT NULL,
+        updated_at INTEGER,
+        state TEXT NOT NULL CHECK (state IN ('active', 'idle', 'historical', 'unknown')),
+        state_confidence TEXT NOT NULL CHECK (state_confidence IN ('verified', 'inferred', 'unavailable')),
+        indexed INTEGER NOT NULL DEFAULT 0 CHECK (indexed IN (0, 1)),
+        connected INTEGER NOT NULL DEFAULT 0 CHECK (connected IN (0, 1)),
+        messageable INTEGER NOT NULL DEFAULT 0 CHECK (messageable IN (0, 1)),
+        UNIQUE (provider, installation, account_fingerprint, vendor_session_id)
+      );
+
+      CREATE INDEX sessions_workspace_updated_idx
+        ON sessions (workspace, updated_at DESC);
+
+      CREATE TABLE transcript_entries (
+        entry_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        source_id TEXT NOT NULL,
+        role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'tool', 'system', 'other')),
+        text TEXT NOT NULL,
+        occurred_at INTEGER,
+        content_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        UNIQUE (session_id, source_id)
+      );
+
+      CREATE INDEX transcript_entries_session_time_idx
+        ON transcript_entries (session_id, occurred_at, entry_id);
+      CREATE INDEX transcript_entries_hash_idx
+        ON transcript_entries (content_hash);
+
+      CREATE TABLE ingestion_cursors (
+        provider TEXT NOT NULL CHECK (provider IN ('codex', 'claude')),
+        source_scope TEXT NOT NULL,
+        cursor TEXT,
+        watermark TEXT,
+        last_success INTEGER,
+        last_error TEXT,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (provider, source_scope)
+      );
+
+      CREATE TABLE messages (
+        message_id TEXT PRIMARY KEY,
+        sender_session_id TEXT NOT NULL REFERENCES sessions(portal_session_id),
+        target_session_id TEXT NOT NULL REFERENCES sessions(portal_session_id),
+        body TEXT NOT NULL,
+        state TEXT NOT NULL CHECK (state IN ('queued', 'delivering', 'delivered', 'failed', 'replied')),
+        created_at INTEGER NOT NULL,
+        delivered_at INTEGER,
+        reply_to TEXT REFERENCES messages(message_id),
+        idempotency_key TEXT NOT NULL,
+        error TEXT,
+        UNIQUE (sender_session_id, idempotency_key)
+      );
+
+      CREATE INDEX messages_target_state_created_idx
+        ON messages (target_session_id, state, created_at);
+    `,
+    },
+    {
+        version: 2,
+        name: "recall_index",
+        sql: `
+      CREATE TABLE chunks (
+        chunk_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        first_entry_id TEXT NOT NULL REFERENCES transcript_entries(entry_id) ON DELETE CASCADE,
+        last_entry_id TEXT NOT NULL REFERENCES transcript_entries(entry_id) ON DELETE CASCADE,
+        ordinal INTEGER NOT NULL,
+        text TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        occurred_at INTEGER,
+        embedding_model TEXT,
+        embedding_json TEXT,
+        UNIQUE (first_entry_id, ordinal)
+      );
+
+      CREATE INDEX chunks_session_time_idx ON chunks (session_id, occurred_at, chunk_id);
+      CREATE INDEX chunks_embedding_model_idx ON chunks (embedding_model, chunk_id);
+
+      CREATE VIRTUAL TABLE chunks_fts USING fts5(
+        text,
+        content='chunks',
+        content_rowid='rowid',
+        tokenize='porter unicode61 remove_diacritics 2'
+      );
+
+      CREATE TRIGGER chunks_fts_insert AFTER INSERT ON chunks BEGIN
+        INSERT INTO chunks_fts(rowid, text) VALUES (new.rowid, new.text);
+      END;
+
+      CREATE TRIGGER chunks_fts_delete AFTER DELETE ON chunks BEGIN
+        INSERT INTO chunks_fts(chunks_fts, rowid, text)
+          VALUES ('delete', old.rowid, old.text);
+      END;
+
+      CREATE TRIGGER chunks_fts_update AFTER UPDATE OF text ON chunks BEGIN
+        INSERT INTO chunks_fts(chunks_fts, rowid, text)
+          VALUES ('delete', old.rowid, old.text);
+        INSERT INTO chunks_fts(rowid, text) VALUES (new.rowid, new.text);
+      END;
+
+      CREATE TABLE embedding_buckets (
+        model TEXT NOT NULL,
+        bucket TEXT NOT NULL,
+        chunk_id TEXT NOT NULL REFERENCES chunks(chunk_id) ON DELETE CASCADE,
+        PRIMARY KEY (model, bucket, chunk_id)
+      ) WITHOUT ROWID;
+
+      CREATE INDEX embedding_buckets_chunk_idx
+        ON embedding_buckets (model, chunk_id);
+    `,
+    },
+    {
+        version: 3,
+        name: "session_credentials",
+        sql: `
+      CREATE TABLE session_credentials (
+        credential_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        secret_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        revoked_at INTEGER
+      );
+
+      CREATE INDEX session_credentials_session_idx
+        ON session_credentials (session_id, revoked_at);
+    `,
+    },
+    {
+        version: 4,
+        name: "connection_leases",
+        sql: `
+      CREATE TABLE connection_leases (
+        session_id TEXT PRIMARY KEY REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        last_seen INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX connection_leases_expiry_idx ON connection_leases (expires_at);
+    `,
+    },
+    {
+        version: 5,
+        name: "credential_expiration",
+        sql: `
+      ALTER TABLE session_credentials ADD COLUMN expires_at INTEGER;
+      UPDATE session_credentials
+      SET expires_at = created_at + 86400000
+      WHERE expires_at IS NULL;
+    `,
+    },
+    {
+        version: 6,
+        name: "inbox_delivery_claims",
+        sql: `
+      ALTER TABLE messages ADD COLUMN delivery_claimed_at INTEGER;
+      ALTER TABLE messages ADD COLUMN delivery_attempts INTEGER NOT NULL DEFAULT 0;
+      CREATE INDEX messages_claim_expiry_idx
+        ON messages (target_session_id, state, delivery_claimed_at);
+    `,
+    },
+    {
+        version: 7,
+        name: "managed_session_names",
+        sql: `
+      ALTER TABLE sessions ADD COLUMN managed_name TEXT;
+      CREATE INDEX sessions_workspace_managed_name_idx
+        ON sessions (workspace, managed_name) WHERE managed_name IS NOT NULL;
+    `,
+    },
+    {
+        version: 8,
+        name: "managed_message_delivery",
+        sql: `
+      CREATE TABLE runner_leases (
+        session_id TEXT PRIMARY KEY REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        last_seen INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX runner_leases_expiry_idx ON runner_leases (expires_at);
+
+      CREATE TABLE message_receipts (
+        message_id TEXT PRIMARY KEY REFERENCES messages(message_id) ON DELETE CASCADE,
+        target_turn_id TEXT,
+        received_at INTEGER,
+        completed_at INTEGER,
+        status TEXT NOT NULL CHECK (status IN ('claimed', 'running', 'completed', 'failed')),
+        answer TEXT,
+        tool_results_json TEXT,
+        error TEXT
+      );
+    `,
+    },
+    {
+        version: 9,
+        name: "session_profiles",
+        sql: `
+      CREATE TABLE session_profiles (
+        session_id TEXT PRIMARY KEY REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        display_name TEXT NOT NULL,
+        description TEXT NOT NULL,
+        topics_json TEXT NOT NULL,
+        source TEXT NOT NULL CHECK (source IN ('explicit', 'derived')),
+        transcript_watermark TEXT,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX session_profiles_updated_idx
+        ON session_profiles (updated_at DESC, session_id);
+    `,
+    },
+    {
+        version: 10,
+        name: "remote_task_events",
+        sql: `
+      CREATE TABLE remote_tasks (
+        server_url TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        local_session_id TEXT NOT NULL REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        local_route_id TEXT NOT NULL,
+        remote_route_id TEXT NOT NULL,
+        direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+        state TEXT NOT NULL CHECK (state IN ('offered', 'accepted', 'declined', 'running', 'completed', 'failed')),
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        PRIMARY KEY (server_url, task_id)
+      );
+
+      CREATE INDEX remote_tasks_local_state_idx
+        ON remote_tasks (local_session_id, state, updated_at DESC);
+
+      CREATE TABLE remote_task_events (
+        server_url TEXT NOT NULL,
+        event_id TEXT NOT NULL,
+        envelope_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        local_session_id TEXT NOT NULL REFERENCES sessions(portal_session_id) ON DELETE CASCADE,
+        local_route_id TEXT NOT NULL,
+        remote_route_id TEXT NOT NULL,
+        direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+        kind TEXT NOT NULL CHECK (kind IN (
+          'offer', 'accepted', 'declined', 'running', 'progress',
+          'question', 'answer', 'completed', 'failed'
+        )),
+        state TEXT NOT NULL CHECK (state IN ('offered', 'accepted', 'declined', 'running', 'completed', 'failed')),
+        payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),
+        sender_label TEXT NOT NULL,
+        sender_reference TEXT NOT NULL,
+        authenticated INTEGER NOT NULL DEFAULT 0 CHECK (authenticated = 0),
+        local_message_id TEXT REFERENCES messages(message_id) ON DELETE SET NULL,
+        occurred_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        recorded_at INTEGER NOT NULL,
+        delivery_state TEXT NOT NULL CHECK (delivery_state IN ('queued', 'delivering', 'delivered', 'failed', 'not_applicable')),
+        delivery_claimed_at INTEGER,
+        delivery_attempts INTEGER NOT NULL DEFAULT 0,
+        runner_started_at INTEGER,
+        target_turn_id TEXT,
+        received_at INTEGER,
+        completed_at INTEGER,
+        answer TEXT,
+        tool_results_json TEXT CHECK (tool_results_json IS NULL OR json_valid(tool_results_json)),
+        error TEXT,
+        PRIMARY KEY (server_url, event_id),
+        UNIQUE (server_url, envelope_id),
+        UNIQUE (local_message_id),
+        FOREIGN KEY (server_url, task_id) REFERENCES remote_tasks(server_url, task_id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX remote_task_events_task_time_idx
+        ON remote_task_events (server_url, task_id, occurred_at, event_id);
+      CREATE INDEX remote_task_events_runner_queue_idx
+        ON remote_task_events (local_session_id, direction, delivery_state, delivery_claimed_at, occurred_at);
+    `,
+    },
+];
+export class PortalDatabase {
+    filename;
+    connection;
+    constructor(filename) {
+        this.filename = filename;
+        if (filename !== ":memory:") {
+            const directory = dirname(filename);
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            chmodSync(directory, 0o700);
+        }
+        this.connection = new DatabaseSync(filename);
+        if (filename !== ":memory:")
+            chmodSync(filename, 0o600);
+        this.connection.exec("PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+        if (filename !== ":memory:") {
+            this.connection.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;");
+        }
+        this.migrate();
+    }
+    close() {
+        this.connection.close();
+    }
+    transaction(operation) {
+        this.connection.exec("BEGIN IMMEDIATE");
+        try {
+            const result = operation();
+            this.connection.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.connection.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    migrate() {
+        this.connection.exec(`
+      CREATE TABLE IF NOT EXISTS schema_migrations (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at INTEGER NOT NULL
+      );
+    `);
+        for (const migration of MIGRATIONS) {
+            this.transaction(() => {
+                const applied = this.connection
+                    .prepare("SELECT 1 AS applied FROM schema_migrations WHERE version = ?")
+                    .get(migration.version);
+                if (applied !== undefined)
+                    return;
+                this.connection.exec(migration.sql);
+                this.connection
+                    .prepare("INSERT INTO schema_migrations(version, name, applied_at) VALUES (?, ?, ?)")
+                    .run(migration.version, migration.name, Date.now());
+            });
+        }
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/src/storage/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../src/storage/database.ts"],"names":[],"mappings":"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"}

package/dist/src/storage/repository.d.ts

@@ -0,0 +1,275 @@
+import type { CapabilityConfidence, ProviderName, SessionState, TranscriptEntry } from "../provider/types.js";
+import type { RecallCitation } from "../recall/types.js";
+import { PortalDatabase } from "./database.js";
+export interface SessionIdentity {
+    provider: ProviderName;
+    vendorSessionId: string;
+    installation?: string;
+    accountFingerprint?: string;
+}
+export interface SessionUpsert extends SessionIdentity {
+    workspace: string | null;
+    title: string | null;
+    managedName?: string | null;
+    observedAt?: Date;
+    updatedAt: Date | null;
+    state: SessionState;
+    stateConfidence: CapabilityConfidence;
+    indexed: boolean;
+    connected: boolean;
+    messageable: boolean;
+}
+export interface StoredSession extends Required<SessionIdentity> {
+    portalSessionId: string;
+    workspace: string | null;
+    title: string | null;
+    managedName: string | null;
+    observedAt: Date;
+    updatedAt: Date | null;
+    state: SessionState;
+    stateConfidence: CapabilityConfidence;
+    indexed: boolean;
+    connected: boolean;
+    messageable: boolean;
+}
+export type SessionProfileSource = "explicit" | "derived";
+export interface SessionProfileUpsert {
+    sessionId: string;
+    displayName: string;
+    description: string;
+    topics: readonly string[];
+    source: SessionProfileSource;
+    transcriptWatermark: string | null;
+    updatedAt?: Date;
+}
+export interface StoredSessionProfile {
+    sessionId: string;
+    displayName: string;
+    description: string;
+    topics: string[];
+    source: SessionProfileSource;
+    transcriptWatermark: string | null;
+    updatedAt: Date;
+}
+export interface IngestionResult {
+    inserted: number;
+    updated: number;
+    unchanged: number;
+    removed: number;
+    chunkIds: string[];
+}
+export interface StoredChunk {
+    chunkId: string;
+    sessionId: string;
+    text: string;
+    embeddingModel: string | null;
+    embedding: readonly number[] | null;
+}
+export interface LexicalCandidate {
+    chunkId: string;
+    text: string;
+    lexicalRank: number;
+    citation: RecallCitation;
+}
+export interface SemanticCandidate {
+    chunkId: string;
+    text: string;
+    similarity: number;
+    citation: RecallCitation;
+}
+export interface CandidateQuery {
+    workspace: string;
+    providers?: readonly ProviderName[];
+    occurredAfter?: Date;
+    occurredBefore?: Date;
+    limit: number;
+}
+export interface IngestionCursor {
+    provider: ProviderName;
+    sourceScope: string;
+    cursor: string | null;
+    watermark: string | null;
+    lastSuccess: Date | null;
+    lastError: string | null;
+    updatedAt: Date;
+}
+export type MessageState = "queued" | "delivering" | "delivered" | "failed" | "replied";
+export interface StoredMessage {
+    messageId: string;
+    senderSessionId: string;
+    targetSessionId: string;
+    body: string;
+    state: MessageState;
+    createdAt: Date;
+    deliveredAt: Date | null;
+    replyTo: string | null;
+    idempotencyKey: string;
+    error: string | null;
+}
+export interface MessageReceipt {
+    messageId: string;
+    targetTurnId: string | null;
+    receivedAt: Date | null;
+    completedAt: Date | null;
+    status: "claimed" | "running" | "completed" | "failed";
+    answer: string | null;
+    toolResults: unknown[];
+    error: string | null;
+}
+export type RemoteTaskDirection = "inbound" | "outbound";
+export type RemoteTaskState = "offered" | "accepted" | "declined" | "running" | "completed" | "failed";
+export type RemoteTaskEventKind = "offer" | "accepted" | "declined" | "running" | "progress" | "question" | "answer" | "completed" | "failed";
+export type RemoteEventDeliveryState = "queued" | "delivering" | "delivered" | "failed" | "not_applicable";
+export interface RemoteTaskEventInput {
+    serverUrl: string;
+    taskId: string;
+    eventId: string;
+    envelopeId: string;
+    localSessionId: string;
+    localRouteId: string;
+    remoteRouteId: string;
+    direction: RemoteTaskDirection;
+    kind: RemoteTaskEventKind;
+    state: RemoteTaskState;
+    payload: unknown;
+    senderLabel: string;
+    senderReference: string;
+    authenticated?: false;
+    localMessageId?: string | null;
+    occurredAt: Date;
+    expiresAt: Date;
+    recordedAt?: Date;
+}
+export interface StoredRemoteTask {
+    serverUrl: string;
+    taskId: string;
+    localSessionId: string;
+    localRouteId: string;
+    remoteRouteId: string;
+    direction: RemoteTaskDirection;
+    state: RemoteTaskState;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+export interface StoredRemoteTaskEvent {
+    serverUrl: string;
+    taskId: string;
+    eventId: string;
+    envelopeId: string;
+    localSessionId: string;
+    localRouteId: string;
+    remoteRouteId: string;
+    direction: RemoteTaskDirection;
+    kind: RemoteTaskEventKind;
+    state: RemoteTaskState;
+    payload: unknown;
+    senderLabel: string;
+    senderReference: string;
+    authenticated: boolean;
+    localMessageId: string | null;
+    occurredAt: Date;
+    expiresAt: Date;
+    recordedAt: Date;
+    deliveryState: RemoteEventDeliveryState;
+    deliveryClaimedAt: Date | null;
+    deliveryAttempts: number;
+    runnerStartedAt: Date | null;
+    targetTurnId: string | null;
+    receivedAt: Date | null;
+    completedAt: Date | null;
+    answer: string | null;
+    toolResults: unknown[];
+    error: string | null;
+}
+export interface RemoteTaskEventRecord {
+    task: StoredRemoteTask;
+    event: StoredRemoteTaskEvent;
+    inserted: boolean;
+}
+export declare class PortalRepository {
+    readonly database: PortalDatabase;
+    constructor(database: PortalDatabase);
+    upsertSession(input: SessionUpsert): StoredSession;
+    getSession(portalSessionId: string): StoredSession | null;
+    bindSessionVendorId(portalSessionId: string, vendorSessionId: string): StoredSession;
+    findSession(identity: SessionIdentity): StoredSession | null;
+    listSessions(workspace?: string): StoredSession[];
+    upsertSessionProfile(input: SessionProfileUpsert): StoredSessionProfile;
+    getSessionProfile(sessionId: string): StoredSessionProfile | null;
+    listSessionProfiles(workspace?: string): StoredSessionProfile[];
+    ingestTranscript(portalSessionId: string, entries: readonly TranscriptEntry[]): IngestionResult;
+    markSessionIndexed(portalSessionId: string): void;
+    chunksNeedingEmbedding(portalSessionId: string, model: string): StoredChunk[];
+    saveEmbedding(chunkId: string, model: string, vector: readonly number[]): void;
+    saveEmbeddings(model: string, embeddings: readonly {
+        chunkId: string;
+        vector: readonly number[];
+    }[]): void;
+    lexicalCandidates(ftsQuery: string, query: CandidateQuery): LexicalCandidate[];
+    semanticCandidates(model: string, vector: readonly number[], query: CandidateQuery): SemanticCandidate[];
+    explainLexicalQuery(ftsQuery: string, query: CandidateQuery): string[];
+    workspaceFreshness(workspace: string): Date | null;
+    upsertCursor(input: Omit<IngestionCursor, "updatedAt">): IngestionCursor;
+    getCursor(provider: ProviderName, sourceScope: string): IngestionCursor | null;
+    countTranscriptEntries(sessionId: string): number;
+    enqueueMessage(input: {
+        senderSessionId: string;
+        targetSessionId: string;
+        body: string;
+        idempotencyKey: string;
+        replyTo?: string | null;
+    }): StoredMessage;
+    createMessageIdempotencyKey(): string;
+    countMessagesSince(senderSessionId: string, since: Date): number;
+    hasRunningDelivery(senderSessionId: string, targetSessionId: string): boolean;
+    getMessage(messageId: string): StoredMessage | null;
+    getMessageByIdempotency(senderSessionId: string, idempotencyKey: string): StoredMessage | null;
+    updateMessageState(messageId: string, state: MessageState, options?: {
+        deliveredAt?: Date | null;
+        error?: string | null;
+    }): StoredMessage;
+    listInbox(targetSessionId: string, state?: MessageState): StoredMessage[];
+    receiveQueuedMessages(targetSessionId: string, acknowledgements?: readonly string[], claimTtlMs?: number): StoredMessage[];
+    touchRunnerLease(sessionId: string, ttlMs?: number): Date;
+    hasActiveRunnerLease(sessionId: string, now?: Date): boolean;
+    clearRunnerLease(sessionId: string): void;
+    claimNextRunnerMessage(targetSessionId: string, claimTtlMs?: number): StoredMessage | null;
+    markRunnerMessageReceived(messageId: string, targetSessionId: string, turnId: string): MessageReceipt;
+    markRunnerMessageStarting(messageId: string, targetSessionId: string): MessageReceipt;
+    completeRunnerMessage(messageId: string, targetSessionId: string, input: {
+        turnId: string;
+        answer: string | null;
+        toolResults: readonly unknown[];
+    }): MessageReceipt;
+    failRunnerMessage(messageId: string, targetSessionId: string, error: string): MessageReceipt;
+    getMessageReceipt(messageId: string): MessageReceipt | null;
+    private requireMessageReceipt;
+    recordRemoteTaskEvent(input: RemoteTaskEventInput): RemoteTaskEventRecord;
+    getRemoteTask(serverUrl: string, taskId: string): StoredRemoteTask | null;
+    getRemoteTaskEvent(serverUrl: string, eventId: string): StoredRemoteTaskEvent | null;
+    getRemoteTaskEventByEnvelope(serverUrl: string, envelopeId: string): StoredRemoteTaskEvent | null;
+    getRemoteTaskEventByLocalMessage(localMessageId: string): StoredRemoteTaskEvent | null;
+    listRemoteTaskEvents(serverUrl: string, taskId: string): StoredRemoteTaskEvent[];
+    linkRemoteTaskEventToLocalMessage(serverUrl: string, eventId: string, localMessageId: string): StoredRemoteTaskEvent;
+    claimNextRemoteTaskEvent(localSessionId: string, claimTtlMs?: number): StoredRemoteTaskEvent | null;
+    markRemoteTaskEventStarting(serverUrl: string, eventId: string, localSessionId: string): StoredRemoteTaskEvent;
+    markRemoteTaskEventReceived(serverUrl: string, eventId: string, localSessionId: string, turnId: string): StoredRemoteTaskEvent;
+    completeRemoteTaskEvent(serverUrl: string, eventId: string, localSessionId: string, input: {
+        turnId: string;
+        answer: string | null;
+        toolResults: readonly unknown[];
+    }): StoredRemoteTaskEvent;
+    failRemoteTaskEvent(serverUrl: string, eventId: string, localSessionId: string, error: string): StoredRemoteTaskEvent;
+    private requireRemoteTask;
+    private requireRemoteTaskEvent;
+    private validateRemoteLocalMessage;
+    issueSessionCredential(sessionId: string): string;
+    authenticateSession(sessionId: string, token: string): StoredSession;
+    revokeSessionCredential(token: string): void;
+    touchConnectionLease(sessionId: string, ttlMs?: number): Date;
+    hasActiveConnectionLease(sessionId: string, now?: Date): boolean;
+    clearConnectionLease(sessionId: string): void;
+    private validateReply;
+}
+export declare function compileFtsQuery(query: string): string;