@axiom-lattice/pg-stores 3.3.12 → 3.4.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Pool, PoolConfig, PoolClient } from 'pg';
 export { Pool, PoolConfig } from 'pg';
-import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, ConnectionStore, ConnectionEntry, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, ProjectFilter, Project, CreateProjectRequest, UpdateProjectRequest, UpdateProjectCapabilityBundlesResult, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, QueryWorkflowRunsOptions, QueryWorkflowRunsResult, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, BindingMutablePatch, BindingListParams, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationInput, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, UpdateA2AApiKeyInput, A2AApiKeyEntry, OpenAuditStore, OpenAuditQuery, OpenAuditRecord, OpenAuditAppendInput, AgentWebAppStore, AgentWebApp, CreateAgentWebAppInput, AgentWebAppStorePatch, AgentWebAppUpdateOptions, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, TaskDependentListQuery, UpdateTaskRequest, TaskMutationSnapshot, TaskWorkItemStore, CreateWorkItemRequest, TaskWorkItem, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, CollectionStore, Collection, CreateCollectionRequest, UpdateCollectionRequest, VectorStoreProvider, VectorStoreCreateParams, CapabilityBundleStore, CapabilityBundle, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput, CapabilityBundleDeleteResult, ProjectRoomStore, ProjectRoom, ProjectMembershipStore, ProjectMembership, ProjectHumanRole, ProjectMembershipMutationResult, ProjectBotMembershipStore, ProjectBotMembership, ProjectRoomMessageStore, ProjectRoomMessage, ProjectRoomReadStateStore, ProjectRoomReadState, UserPushSubscriptionStore, UserPushSubscription, ModelProviderStore, ModelProviderEntry, CreateModelProviderRequest, UpdateModelProviderRequest, ModelProviderStatus, ModelProviderModelEntry, ProviderModelInput, LeaseStore, LeaseRecord, OutboxStore, OutboxEvent, PluginDeploymentStore, PluginDeployment, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
+import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, ConnectionStore, ConnectionEntry, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, ProjectFilter, Project, CreateProjectRequest, UpdateProjectRequest, UpdateProjectCapabilityBundlesResult, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, QueryWorkflowRunsOptions, QueryWorkflowRunsResult, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, BindingMutablePatch, BindingListParams, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationInput, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, UpdateA2AApiKeyInput, A2AApiKeyEntry, OpenAuditStore, OpenAuditQuery, OpenAuditRecord, OpenAuditAppendInput, AgentWebAppStore, AgentWebApp, CreateAgentWebAppInput, AgentWebAppStorePatch, AgentWebAppUpdateOptions, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, TaskDependentListQuery, UpdateTaskRequest, TaskMutationSnapshot, TaskWorkItemStore, CreateWorkItemRequest, TaskWorkItem, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, CollectionStore, Collection, CreateCollectionRequest, UpdateCollectionRequest, VectorStoreProvider, VectorStoreCreateParams, CapabilityBundleStore, CapabilityBundle, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput, CapabilityBundleDeleteResult, ProjectRoomStore, ProjectRoom, ProjectMembershipStore, ProjectMembership, ProjectHumanRole, ProjectMembershipMutationResult, ProjectBotMembershipStore, ProjectBotMembership, ProjectRoomMessageStore, ProjectRoomMessage, ProjectRoomReadStateStore, ProjectRoomReadState, UserPushSubscriptionStore, UserPushSubscription, ModelProviderStore, ModelProviderEntry, CreateModelProviderRequest, UpdateModelProviderRequest, ModelProviderStatus, ModelProviderModelEntry, ProviderModelInput, LeaseStore, LeaseRecord, OutboxStore, OutboxEvent, PluginDeploymentStore, PluginDeployment, ChannelReplyJobStore, CreateChannelReplyJobInput, ChannelReplyJob, CheckpointStorage, CheckpointMaintenance, ThreadCheckpointStorage, StoreProtocol, StorePutInput, StoreItem, StoreSearchInput, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
 export { AgentWebApp, AgentWebAppAppearance, AgentWebAppFeatures, AgentWebAppScope, AgentWebAppStatus, AgentWebAppStore, Assistant, AssistantStore, Binding, BindingRegistry, CapabilityBundle, CapabilityBundleStore, ChannelInstallation, ChannelInstallationStore, ConnectionEntry, ConnectionStore, CreateAgentWebAppInput, CreateAssistantRequest, CreateBindingInput, CreateCapabilityBundleInput, CreateChannelInstallationInput, CreateChannelInstallationRequest, CreateDatabaseConfigRequest, CreateEvalCaseRequest, CreateEvalProjectRequest, CreateEvalRunRequest, CreateEvalSuiteRequest, CreateMcpServerConfigRequest, CreateMenuItemInput, CreateMetricsServerConfigRequest, CreateProjectRequest, CreateRunStepRequest, CreateShareRequest, CreateSkillRequest, CreateTenantRequest, CreateThreadRequest, CreateUserRequest, CreateUserTenantLinkRequest, CreateWorkflowRunRequest, CreateWorkspaceRequest, DatabaseConfig, DatabaseConfigEntry, DatabaseConfigStore, DatabaseType, EvalCase, EvalProject, EvalProjectReport, EvalRun, EvalRunResult, EvalStore, EvalSuite, LarkChannelInstallationConfig, McpServerConfigEntry, McpServerConfigStore, MenuItem, MenuRegistry, MetricsServerConfig, MetricsServerConfigEntry, MetricsServerConfigStore, Project, ProjectStore, ResourceAddress, RunStep, ScheduleExecutionType, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ShareRecord, ShareResult, ShareVisibility, SharedResourceStore, Skill, SkillStore, StorageType, Tenant, TenantStatus, TenantStore, Thread, ThreadStore, UpdateAgentWebAppInput, UpdateCapabilityBundleInput, UpdateChannelInstallationRequest, UpdateDatabaseConfigRequest, UpdateMcpServerConfigRequest, UpdateMetricsServerConfigRequest, UpdateProjectRequest, UpdateRunStepRequest, UpdateTenantRequest, UpdateUserRequest, UpdateUserTenantLinkRequest, UpdateWorkflowRunRequest, UpdateWorkspaceRequest, User, UserStore, UserTenantLink, UserTenantLinkStore, UserTenantRole, WorkflowRun, WorkflowTrackingStore, Workspace, WorkspaceStore } from '@axiom-lattice/protocols';
-import { IMessageQueueStore, AddMessageParams, PendingMessage, QueueScope, ClaimMessagesOptions, ThreadInfo } from '@axiom-lattice/core';
+import { IMessageQueueStore, AddMessageParams, PendingMessage, QueueScope, ClaimMessagesOptions, ThreadInfo, IAgentRunLedger, BeginAgentRunInput, AgentRunRecord, CreatePendingAgentRunInput, ListPendingRunsOptions, ClaimAgentRunInput, DeleteAgentRunExpected, AgentRunStatus, RollbackFailureResult, AgentRunRollbackResult, AgentRunExpiredOutcome, SettleExpiredRunOptions, AgentRunCounts, AgentRunSource, ReapedAgentRun } from '@axiom-lattice/core';
 export { AddMessageParams, PendingMessage, ThreadInfo } from '@axiom-lattice/core';
 import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 import { DocumentInterface } from '@langchain/core/documents';
@@ -78,6 +78,10 @@ declare class PostgreSQLThreadStore implements ThreadStore {
      * Check if thread exists
      */
     hasThread(tenantId: string, threadId: string): Promise<boolean>;
+    /**
+     * List expired threads across all tenants, oldest expiry first.
+     */
+    listExpiredThreads(now: Date, limit: number): Promise<Thread[]>;
     /**
      * Ensure store is initialized
      */
@@ -943,6 +947,9 @@ declare class ThreadMessageQueueStore implements IMessageQueueStore {
     getQueueSize(threadId: string, scope?: QueueScope): Promise<number>;
     /**
      * Get all threads with pending or processing messages
+     *
+     * @returns One entry per full scope, with `hasPending` distinguishing
+     * processing-only threads (no pending row) from threads with work to drain.
      */
     getThreadsWithPendingMessages(): Promise<ThreadInfo[]>;
     /**
@@ -1937,6 +1944,309 @@ declare class PostgreSQLPluginDeploymentStore implements PluginDeploymentStore {
     delete(tenantId: string, pluginType: string): Promise<boolean>;
 }
 
+/**
+ * PostgreSQL Agent Run Ledger
+ *
+ * Durable run lifecycle and task queue. `source='run_api'` rows are claimed by
+ * the run-task worker; `source='legacy'` rows preserve the existing
+ * observational ledger/message-queue behavior.
+ */
+
+/** Options accepted by {@link PostgreSQLAgentRunLedger}. */
+interface PostgreSQLAgentRunLedgerOptions {
+    /** Externally managed pool. When supplied, migrations are not run here. */
+    pool?: Pool;
+    /** Connection string or pool config used to create a pool. */
+    poolConfig?: string | PoolConfig;
+    /** Set to `false` to skip running this store's migration automatically. */
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL implementation of {@link IAgentRunLedger}.
+ *
+ * @remarks
+ * - Run rows are the durable queue for `run_api` and `project_task` work.
+ *   Claim is an atomic CAS guarded by the same-thread running rule.
+ * - Legacy `beginRun` keeps the historical reconcile-then-insert behavior and
+ *   writes `source='legacy'`.
+ * - `reapExpired` reports expired run-queue rows without mutating them;
+ *   `reapLegacyExpired` preserves the supervisor's legacy settle behavior.
+ */
+declare class PostgreSQLAgentRunLedger implements IAgentRunLedger {
+    private pool;
+    private ownsPool;
+    private initialized;
+    private initPromise;
+    private migrationManager;
+    /**
+     * @param options An externally managed pool, or a pool config/connection URL.
+     */
+    constructor(options: PostgreSQLAgentRunLedgerOptions);
+    /** Runs pending migrations once. */
+    initialize(): Promise<void>;
+    /** Ends the pool when this store owns it. */
+    dispose(): Promise<void>;
+    /**
+     * Creates a running legacy run, reconciling any existing running row first.
+     *
+     * @remarks The caller holds the `thread-run` lease, so a surviving `running`
+     * row is stale (its owner can no longer hold the lease) even when its ledger
+     * lease has not expired yet.
+     */
+    beginRun(input: BeginAgentRunInput): Promise<AgentRunRecord>;
+    /** Creates an unowned pending run-queue row. */
+    createPendingRun(input: CreatePendingAgentRunInput): Promise<AgentRunRecord>;
+    /** Lists claimable run-queue rows, oldest available first. */
+    listPendingRuns(options?: ListPendingRunsOptions): Promise<AgentRunRecord[]>;
+    /** Atomically claims a pending run-queue row. */
+    claimRun(input: ClaimAgentRunInput): Promise<AgentRunRecord | undefined>;
+    /**
+     * Claims under a per-tenant running cap.
+     *
+     * @remarks Serializes claims for one tenant with a transaction-scoped
+     * advisory lock, counts running rows, then runs the same claim statement.
+     * The lock is shared with admission creates so cap checks cannot race.
+     */
+    private claimRunWithTenantCap;
+    /** Captures the checkpoint a running run-queue row started from. */
+    setBaseCheckpoint(tenantId: string, runId: string, owner: string, baseCheckpointId: string | null): Promise<boolean>;
+    /** Records the resolved capability runtime revision for a running run. */
+    setCapabilityRevision(tenantId: string, runId: string, owner: string, revision: string | null): Promise<boolean>;
+    /** Deletes a run row immediately, optionally guarded by status/owner. */
+    deleteRun(tenantId: string, runId: string, expected?: DeleteAgentRunExpected): Promise<boolean>;
+    /** Deletes terminal rows finished before `cutoffMs`, oldest first. */
+    deleteTerminalBefore(cutoffMs: number, limit: number): Promise<number>;
+    /** Extends a running run's lease when `owner` still holds it. */
+    heartbeatRun(runId: string, owner: string, leaseMs: number): Promise<boolean>;
+    /** Settles a running run when `owner` still holds it. */
+    settleRun(runId: string, owner: string, status: Exclude<AgentRunStatus, "pending" | "running">, error?: string): Promise<boolean>;
+    /** Settles a running run only when no rollback is pending. */
+    settleRunUnlessRollbackRequested(runId: string, owner: string, status: Exclude<AgentRunStatus, "pending" | "running">, error?: string): Promise<boolean>;
+    /** Terminates an uncaptured rollback run with a repair signal. */
+    settleRollbackFailure(tenantId: string, runId: string, error: string): Promise<boolean>;
+    /** Records one bounded rollback failure and optionally converges. */
+    recordRollbackFailure(tenantId: string, runId: string, error: string, maxAttempts: number): Promise<RollbackFailureResult | undefined>;
+    /** Reads a run within a tenant. */
+    getRun(tenantId: string, runId: string): Promise<AgentRunRecord | undefined>;
+    /** Finds the active (pending/running) run for a ProjectTask. */
+    getActiveRunForTask(tenantId: string, taskId: string): Promise<AgentRunRecord | undefined>;
+    /** Lists a thread's runs, newest first (including pending rows). */
+    listRuns(tenantId: string, threadId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<AgentRunRecord[]>;
+    /** Finds the thread's running run, if any. */
+    findRunning(tenantId: string, threadId: string): Promise<AgentRunRecord | undefined>;
+    /** Requests cancellation, settling pending/expired rows interrupted. */
+    requestCancel(tenantId: string, runId: string): Promise<"cancelled" | "requested" | "not_found" | "terminal">;
+    /** Deletes a pending run or flags a running run for rollback. */
+    requestRollback(tenantId: string, runId: string): Promise<AgentRunRollbackResult>;
+    /** Atomically reclaims an expired running row without requeueing it. */
+    recoverExpiredRun(runId: string, owner: string, leaseMs: number): Promise<AgentRunRecord | undefined>;
+    /** Atomically requeues or interrupts an expired run-queue row. */
+    settleExpiredRun(runId: string, outcome: AgentRunExpiredOutcome, options?: SettleExpiredRunOptions): Promise<boolean>;
+    /** Counts runs grouped by lifecycle status. */
+    counts(): Promise<AgentRunCounts>;
+    /** Reports expired run-queue rows for the requested sources. */
+    reapExpired(sources?: readonly AgentRunSource[]): Promise<ReapedAgentRun[]>;
+    /** Lists rollback work that still needs a checkpoint rewind. */
+    listRollbackRuns(): Promise<ReapedAgentRun[]>;
+    /** Settles expired legacy rows, preserving the historical supervisor behavior. */
+    reapLegacyExpired(): Promise<ReapedAgentRun[]>;
+}
+
+/** Options accepted by {@link PostgreSQLChannelReplyJobStore}. */
+interface PostgreSQLChannelReplyJobStoreOptions {
+    /** Externally managed pool. When supplied, migrations are not run here. */
+    pool?: Pool;
+    /** Connection string or pool config used to create a pool. */
+    poolConfig?: string | PoolConfig;
+    /** Set to `false` to skip running this store's migration automatically. */
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL {@link ChannelReplyJobStore}.
+ *
+ * @remarks Claims are a single conditional `UPDATE` (CAS) guarded by status,
+ * `available_at`, and lease expiry, so competing replicas cannot both win.
+ * Lease/created/updated/delivered timestamps use the database clock; only the
+ * caller-supplied `availableAt` epoch is stored as-is.
+ */
+declare class PostgreSQLChannelReplyJobStore implements ChannelReplyJobStore {
+    private pool;
+    private ownsPool;
+    private initialized;
+    private initPromise;
+    private migrationManager;
+    /** @param options An externally managed pool, or a pool config/connection URL. */
+    constructor(options: PostgreSQLChannelReplyJobStoreOptions);
+    /** Runs pending migrations once. */
+    initialize(): Promise<void>;
+    /** Ends the pool when this store owns it. */
+    dispose(): Promise<void>;
+    /** Creates a pending job with database-clock created/updated timestamps. */
+    create(input: CreateChannelReplyJobInput): Promise<ChannelReplyJob>;
+    /** Reads one job within a tenant scope. */
+    get(tenantId: string, runId: string): Promise<ChannelReplyJob | null>;
+    /** Lists claimable pending jobs that are due at `now`, oldest first. */
+    listPending(now: number, limit?: number): Promise<ChannelReplyJob[]>;
+    /**
+     * Atomically leases a claimable job.
+     *
+     * @param now Accepted for interface symmetry; PostgreSQL uses the database clock.
+     */
+    claim(tenantId: string, runId: string, owner: string, leaseMs: number, now?: number): Promise<ChannelReplyJob | null>;
+    /**
+     * Marks a job delivered when `owner` still holds the lease.
+     *
+     * @param now Accepted for interface symmetry; PostgreSQL uses the database clock.
+     */
+    markDelivered(tenantId: string, runId: string, owner: string, outputMessageId?: string | null, now?: number): Promise<ChannelReplyJob | null>;
+    /**
+     * Returns a job to pending with an incremented attempt count.
+     *
+     * @param now Accepted for interface symmetry; PostgreSQL uses the database clock.
+     */
+    reschedule(tenantId: string, runId: string, owner: string, error: string, availableAt: number, now?: number): Promise<ChannelReplyJob | null>;
+    /**
+     * Marks a job terminally failed when `owner` still holds the lease.
+     *
+     * @param now Accepted for interface symmetry; PostgreSQL uses the database clock.
+     */
+    markFailed(tenantId: string, runId: string, owner: string, error: string, now?: number): Promise<ChannelReplyJob | null>;
+    /** Deletes one job. Returns whether a row was removed. */
+    delete(tenantId: string, runId: string): Promise<boolean>;
+    /** Deletes terminal jobs whose last update is older than `before`. */
+    deleteTerminalBefore(before: number, limit?: number): Promise<number>;
+}
+
+/**
+ * Raised when a checkpoint copy targets a thread that already owns rows.
+ */
+declare class CheckpointTargetNotEmptyError extends Error {
+    /** Machine-readable conflict code. */
+    readonly code: "CHECKPOINT_TARGET_NOT_EMPTY";
+    /**
+     * @param threadId - Non-empty target thread id.
+     */
+    constructor(threadId: string);
+}
+/**
+ * Raised when a checkpoint rewind targets a base checkpoint that does not exist.
+ */
+declare class CheckpointBaseNotFoundError extends Error {
+    /** Machine-readable failure code. */
+    readonly code: "CHECKPOINT_BASE_NOT_FOUND";
+    /** Thread owning the missing base checkpoint. */
+    readonly threadId: string;
+    /** Base checkpoint id that was not found. */
+    readonly baseCheckpointId: string;
+    /**
+     * @param threadId - Thread owning the missing base checkpoint.
+     * @param baseCheckpointId - Base checkpoint id that was not found.
+     */
+    constructor(threadId: string, baseCheckpointId: string);
+}
+/**
+ * Checkpoint accounting and maintenance over LangGraph's built-in
+ * `PostgresSaver` tables.
+ *
+ * `get` is a read-only aggregate. `copyThread`, `deleteThread`, `deleteAfter`,
+ * and `pruneThread` are the explicit maintenance operations; each runs in one
+ * transaction and touches only the `checkpoints`, `checkpoint_blobs`, and
+ * `checkpoint_writes` tables created by `PostgresSaver.setup()`. No migration
+ * is added.
+ */
+declare class PostgreSQLCheckpointStorage implements CheckpointStorage, CheckpointMaintenance {
+    private readonly pool;
+    /**
+     * @param pool - PostgreSQL pool shared with the rest of the store config.
+     */
+    constructor(pool: Pool);
+    /**
+     * Measure the checkpoint storage used by one thread.
+     *
+     * @param threadId - Thread id whose checkpoint rows should be measured.
+     * @returns Counts and byte sizes grouped by checkpoint storage category.
+     */
+    get(threadId: string): Promise<ThreadCheckpointStorage>;
+    /**
+     * Copy every checkpoint row from a source thread to an empty target thread.
+     *
+     * @param sourceThreadId - Thread whose rows are copied.
+     * @param targetThreadId - Empty thread that receives the rows.
+     * @returns Resolves when the copy commits; an empty source is a no-op.
+     * @throws {CheckpointTargetNotEmptyError} When the target already owns rows.
+     */
+    copyThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
+    /**
+     * Retain only the latest N checkpoints per checkpoint namespace.
+     *
+     * @param threadId - Thread whose checkpoint history is pruned.
+     * @param options - Retention options.
+     * @param options.keepLatest - Number of latest checkpoints to retain per namespace.
+     * @returns Counts of deleted checkpoint, blob, and write rows.
+     */
+    pruneThread(threadId: string, options: {
+        keepLatest: number;
+    }): Promise<{
+        checkpoints: number;
+        blobs: number;
+        writes: number;
+    }>;
+    /**
+     * Delete the checkpoints that descend from a base checkpoint.
+     *
+     * Descendants are discovered by following both same-namespace
+     * `parent_checkpoint_id` edges and cross-namespace `metadata.parents` edges
+     * (LangGraph's `{ "<parent checkpoint_ns>": "<parent checkpoint id>" }` map on
+     * subgraph checkpoints), recursively across every namespace. Out-of-order or
+     * clock-skewed ids do not affect the result. Writes keyed to the base
+     * checkpoint belong to the rolled-back run's first superstep and are deleted
+     * too. Blobs referenced only by deleted checkpoints are removed.
+     *
+     * @param threadId - Thread whose later checkpoint history is deleted.
+     * @param baseCheckpointId - Checkpoint to retain as the new tip, or `null` to
+     * delete every checkpoint for the thread.
+     * @returns Resolves when the deletion commits; no descendants is a no-op.
+     * @throws {RangeError} When `baseCheckpointId` is an empty string.
+     * @throws {CheckpointBaseNotFoundError} When the base checkpoint does not
+     * exist on the thread.
+     */
+    deleteAfter(threadId: string, baseCheckpointId: string | null): Promise<void>;
+    /**
+     * Delete every checkpoint row for a thread.
+     *
+     * @param threadId - Thread whose checkpoint rows are deleted.
+     * @returns Resolves when the deletion commits.
+     */
+    deleteThread(threadId: string): Promise<void>;
+}
+
+/**
+ * PostgreSQL tenant-scoped namespaced key-value store.
+ *
+ * @remarks
+ * - `namespace` is a `TEXT[]`; prefix search compares `namespace[1:n]`.
+ * - `filter` uses JSONB containment (`value @> $filter`).
+ * - `query` is a case-insensitive substring over `value::text`.
+ * - Expired items are excluded from reads/searches and hard-deleted by
+ *   {@link deleteExpired}.
+ */
+declare class PostgreSQLStore implements StoreProtocol {
+    private readonly pool;
+    /**
+     * @param pool - Pool shared with the rest of the store config.
+     */
+    constructor(pool: Pool);
+    put(tenantId: string, input: StorePutInput): Promise<StoreItem>;
+    get(tenantId: string, namespace: string[], key: string): Promise<StoreItem | null>;
+    delete(tenantId: string, namespace: string[], key: string): Promise<boolean>;
+    search(tenantId: string, input: StoreSearchInput): Promise<StoreItem[]>;
+    listNamespaces(tenantId: string, prefix?: string[], limit?: number): Promise<string[][]>;
+    deleteExpired(now: Date, limit: number): Promise<number>;
+}
+
 declare function createPgStoreConfig(connectionString: string): Promise<{
     workspace: PostgreSQLWorkspaceStore;
     project: PostgreSQLProjectStore;
@@ -1974,8 +2284,12 @@ declare function createPgStoreConfig(connectionString: string): Promise<{
     lease: PostgreSQLLeaseStore;
     outbox: PostgreSQLOutboxStore;
     pluginDeployment: PostgreSQLPluginDeploymentStore;
+    agentRun: PostgreSQLAgentRunLedger;
+    channelReplyJob: PostgreSQLChannelReplyJobStore;
     vectorStoreProvider: PGVectorStoreProvider;
     checkpoint: PostgresSaver;
+    checkpointStorage: PostgreSQLCheckpointStorage;
+    store: PostgreSQLStore;
 }>;
 
 /**
@@ -2136,6 +2450,12 @@ declare class MigrationManager {
  * Initial migration: Create threads table
  */
 declare const createThreadsTable: Migration;
+/**
+ * Migration: Add per-thread expiry (`expires_at`) for the TTL sweeper.
+ *
+ * A partial index keeps expiry scans cheap while leaving non-TTL threads out.
+ */
+declare const addThreadExpiresAt: Migration;
 
 /**
  * Thread table tenant isolation migration
@@ -2481,4 +2801,34 @@ declare const createPluginDeployments: Migration;
  */
 declare const dropPluginDeploymentAuthToken: Migration;
 
-export { ChannelBindingStore, type ChannelBindingStoreOptions, type ChannelIdentityMapping, ChannelIdentityMappingStore, type ChannelIdentityMappingStoreOptions, type CreateChannelIdentityMappingInput, DuplicateProjectMembershipError, DuplicateProjectRoomMessageIdempotencyKeyError, MenuStore, type MenuStoreOptions, type Migration, MigrationManager, PGVectorStoreProvider, PostgreSQLA2AApiKeyStore, type PostgreSQLA2AApiKeyStoreOptions, PostgreSQLAgentWebAppStore, type PostgreSQLAgentWebAppStoreOptions, PostgreSQLAssistantStore, type PostgreSQLAssistantStoreOptions, PostgreSQLCapabilityBundleStore, type PostgreSQLCapabilityBundleStoreOptions, PostgreSQLChannelInstallationStore, type PostgreSQLChannelInstallationStoreOptions, PostgreSQLCollectionStore, type PostgreSQLCollectionStoreOptions, PostgreSQLConnectionStore, PostgreSQLDatabaseConfigStore, type PostgreSQLDatabaseConfigStoreOptions, PostgreSQLEvalStore, type PostgreSQLEvalStoreOptions, PostgreSQLMcpServerConfigStore, type PostgreSQLMcpServerConfigStoreOptions, PostgreSQLMetricsServerConfigStore, type PostgreSQLMetricsServerConfigStoreOptions, PostgreSQLModelProviderStore, type PostgreSQLModelProviderStoreOptions, PostgreSQLOpenAuditStore, type PostgreSQLOpenAuditStoreOptions, PostgreSQLPluginDeploymentStore, PostgreSQLProjectBotMembershipStore, PostgreSQLProjectMembershipStore, PostgreSQLProjectRoomMessageStore, PostgreSQLProjectRoomReadStateStore, PostgreSQLProjectRoomStore, PostgreSQLProjectStore, type PostgreSQLProjectStoreOptions, PostgreSQLScheduleStorage, type PostgreSQLScheduleStorageOptions, PostgreSQLSkillStore, type PostgreSQLSkillStoreOptions, PostgreSQLTaskWorkItemStore, type PostgreSQLTaskWorkItemStoreOptions, PostgreSQLTenantStore, type PostgreSQLTenantStoreOptions, type PostgreSQLThreadMessageQueueStoreOptions, PostgreSQLThreadStore, type PostgreSQLThreadStoreOptions, PostgreSQLUserStore, type PostgreSQLUserStoreOptions, PostgreSQLUserTenantLinkStore, type PostgreSQLUserTenantLinkStoreOptions, PostgreSQLWorkflowTrackingStore, type PostgreSQLWorkflowTrackingStoreOptions, PostgreSQLWorkspaceStore, type PostgreSQLWorkspaceStoreOptions, PostgresSharedResourceStore, type PostgresSharedResourceStoreOptions, ProjectBotMembershipIdConflictError, ProjectMembershipIdConflictError, ProjectRoomMessageIdConflictError, ThreadMessageQueueStore, addAssistantTenantId, addEnvToEvalRuns, addFileContentType, addHoldoutToEvalRuns, addInterruptColumnsToEval, addInterruptPolicyToEvalCases, addMcpAppContentType, addProjectConfigColumn, addScheduleTenantId, addSkillTenantId, addStepThreadId, addTaskIdToEvalRuns, addThreadTenantId, addWorkflowRunsTenantStatusUpdatedIndex, alterChannelInstallationsTable, changeAssistantPrimaryKey, changeSkillPrimaryKey, changeThreadPrimaryKey, createA2AApiKeysTable, createAgentWebAppsTable, createAssistantsTable, createCapabilityBundlesTable, createChannelBindingsTable, createChannelIdentityMappingTables, createChannelInstallationsTable, createCollectionsTable, createDatabaseConfigsTable, createEvalCasesTable, createEvalProjectsTable, createEvalRunResultsTable, createEvalRunsTable, createEvalSuitesTable, createMcpServerConfigsTable, createMenuItemsTable, createMetricsConfigsTable, createPGVectorStoreProvider, createPgStoreConfig, createPluginDeployments, createProjectRoomReadStates, createProjectRoomTables, createProjectsTable, createScheduledTasksTable, createSharedResourcesTable, createSkillsTable, createTenantsTable, createThreadMessageQueueTable, createThreadsTable, createUsersTable, createWorkflowTrackingTables, createWorkspacesTable, dropPluginDeploymentAuthToken, enforceUniqueEvalProjectName, evalMigrations, mapRowToRunStep, mapRowToWorkflowRun, safeParse };
+/**
+ * Creates the durable agent run ledger.
+ *
+ * @remarks
+ * The partial unique index enforces the ledger invariant: at most one
+ * `running` row per `(tenant_id, thread_id)`.
+ */
+declare const createAgentRunLedgerTable: Migration;
+
+/**
+ * Durable channel reply jobs used by the cross-replica reply dispatcher.
+ *
+ * @remarks Lease-based claims make the row the single source of truth for
+ * "which replica is delivering this run's channel reply". Timestamps are epoch
+ * milliseconds from the database clock.
+ */
+declare const createChannelReplyJobsTable: Migration;
+
+/**
+ * Namespaced KV store migrations.
+ */
+
+/**
+ * Migration: create the tenant-scoped namespaced KV store table.
+ *
+ * GIN indexes support namespace prefix and JSONB containment filters; the
+ * partial expiry index supports the TTL sweeper.
+ */
+declare const createStoreItemsTable: Migration;
+
+export { ChannelBindingStore, type ChannelBindingStoreOptions, type ChannelIdentityMapping, ChannelIdentityMappingStore, type ChannelIdentityMappingStoreOptions, CheckpointBaseNotFoundError, CheckpointTargetNotEmptyError, type CreateChannelIdentityMappingInput, DuplicateProjectMembershipError, DuplicateProjectRoomMessageIdempotencyKeyError, MenuStore, type MenuStoreOptions, type Migration, MigrationManager, PGVectorStoreProvider, PostgreSQLA2AApiKeyStore, type PostgreSQLA2AApiKeyStoreOptions, PostgreSQLAgentRunLedger, type PostgreSQLAgentRunLedgerOptions, PostgreSQLAgentWebAppStore, type PostgreSQLAgentWebAppStoreOptions, PostgreSQLAssistantStore, type PostgreSQLAssistantStoreOptions, PostgreSQLCapabilityBundleStore, type PostgreSQLCapabilityBundleStoreOptions, PostgreSQLChannelInstallationStore, type PostgreSQLChannelInstallationStoreOptions, PostgreSQLChannelReplyJobStore, type PostgreSQLChannelReplyJobStoreOptions, PostgreSQLCheckpointStorage, PostgreSQLCollectionStore, type PostgreSQLCollectionStoreOptions, PostgreSQLConnectionStore, PostgreSQLDatabaseConfigStore, type PostgreSQLDatabaseConfigStoreOptions, PostgreSQLEvalStore, type PostgreSQLEvalStoreOptions, PostgreSQLMcpServerConfigStore, type PostgreSQLMcpServerConfigStoreOptions, PostgreSQLMetricsServerConfigStore, type PostgreSQLMetricsServerConfigStoreOptions, PostgreSQLModelProviderStore, type PostgreSQLModelProviderStoreOptions, PostgreSQLOpenAuditStore, type PostgreSQLOpenAuditStoreOptions, PostgreSQLPluginDeploymentStore, PostgreSQLProjectBotMembershipStore, PostgreSQLProjectMembershipStore, PostgreSQLProjectRoomMessageStore, PostgreSQLProjectRoomReadStateStore, PostgreSQLProjectRoomStore, PostgreSQLProjectStore, type PostgreSQLProjectStoreOptions, PostgreSQLScheduleStorage, type PostgreSQLScheduleStorageOptions, PostgreSQLSkillStore, type PostgreSQLSkillStoreOptions, PostgreSQLStore, PostgreSQLTaskWorkItemStore, type PostgreSQLTaskWorkItemStoreOptions, PostgreSQLTenantStore, type PostgreSQLTenantStoreOptions, type PostgreSQLThreadMessageQueueStoreOptions, PostgreSQLThreadStore, type PostgreSQLThreadStoreOptions, PostgreSQLUserStore, type PostgreSQLUserStoreOptions, PostgreSQLUserTenantLinkStore, type PostgreSQLUserTenantLinkStoreOptions, PostgreSQLWorkflowTrackingStore, type PostgreSQLWorkflowTrackingStoreOptions, PostgreSQLWorkspaceStore, type PostgreSQLWorkspaceStoreOptions, PostgresSharedResourceStore, type PostgresSharedResourceStoreOptions, ProjectBotMembershipIdConflictError, ProjectMembershipIdConflictError, ProjectRoomMessageIdConflictError, ThreadMessageQueueStore, addAssistantTenantId, addEnvToEvalRuns, addFileContentType, addHoldoutToEvalRuns, addInterruptColumnsToEval, addInterruptPolicyToEvalCases, addMcpAppContentType, addProjectConfigColumn, addScheduleTenantId, addSkillTenantId, addStepThreadId, addTaskIdToEvalRuns, addThreadExpiresAt, addThreadTenantId, addWorkflowRunsTenantStatusUpdatedIndex, alterChannelInstallationsTable, changeAssistantPrimaryKey, changeSkillPrimaryKey, changeThreadPrimaryKey, createA2AApiKeysTable, createAgentRunLedgerTable, createAgentWebAppsTable, createAssistantsTable, createCapabilityBundlesTable, createChannelBindingsTable, createChannelIdentityMappingTables, createChannelInstallationsTable, createChannelReplyJobsTable, createCollectionsTable, createDatabaseConfigsTable, createEvalCasesTable, createEvalProjectsTable, createEvalRunResultsTable, createEvalRunsTable, createEvalSuitesTable, createMcpServerConfigsTable, createMenuItemsTable, createMetricsConfigsTable, createPGVectorStoreProvider, createPgStoreConfig, createPluginDeployments, createProjectRoomReadStates, createProjectRoomTables, createProjectsTable, createScheduledTasksTable, createSharedResourcesTable, createSkillsTable, createStoreItemsTable, createTenantsTable, createThreadMessageQueueTable, createThreadsTable, createUsersTable, createWorkflowTrackingTables, createWorkspacesTable, dropPluginDeploymentAuthToken, enforceUniqueEvalProjectName, evalMigrations, mapRowToRunStep, mapRowToWorkflowRun, safeParse };