@assemblyline-agents/runtime 0.1.0

package/dist/state.d.ts

@@ -0,0 +1,736 @@
+import type { JsonObject, JsonValue, MemoryListInput, MemorySearchInput } from "@assemblyline-agents/core";
+import type { DeliveryFailureInput, DeliveryLeaseOptions, DeliveryObligationInput, DeliveryObligationPatch } from "./delivery-queue.js";
+/**
+ * Durable state contracts for the OpenEve runtime.
+ *
+ * The historical monolithic `StateAdapter` is decomposed into capability
+ * interfaces: `RunStore` is required, everything else is optional. The
+ * `StateAdapter` type stays the intersection of every facet so existing
+ * adapters (Postgres/File/InMemory) keep compiling without edits, while
+ * `StateStores` lets embedders bring only the facets they can persist.
+ */
+export type RunStatus = "created" | "running" | "waiting_for_approval" | "waiting_for_input" | "waiting_for_connection" | "suspended" | "completed" | "failed" | "cancelled";
+export type RunEventType = "run.accepted" | "context.bundle_built" | "sandbox.acquired" | "sandbox.snapshot_created" | "sandbox.snapshot_failed" | "sandbox.snapshot_skipped" | "sandbox.command_completed" | "sandbox.file_written" | "sandbox.file_read" | "harness.started" | "model.request_started" | "model.response_completed" | "tool.call_requested" | "tool.approval_requested" | "tool.approval_auto_resolved" | "eval.judged" | "tool.execution_started" | "tool.execution_completed" | "tool.execution_failed" | "human_input.requested" | "memory.sync_completed" | "delivery.obligation_created" | "delivery.sent" | "run.completed" | "run.failed" | "run.execution_error" | "run.max_duration_exceeded" | "model.request_retried" | "run.suspend_requested" | "run.suspended" | "run.resumed" | "run.cancel_requested" | "run.cancelled" | "agent.disabled" | "agent.enabled" | string;
+export interface RunRecord {
+    id: string;
+    agentRevision: string;
+    status: RunStatus;
+    input: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+    contextBundleId?: string;
+    sandboxId?: string;
+    sandboxSnapshotId?: string;
+    memoryRevision?: string;
+    /** Explicit undefined is accepted by update patches to clear a pending intent. */
+    controlIntent?: RunControlIntent | undefined;
+    /** Machine-readable failure reason, set when the run reaches `failed`. Null for successes. */
+    terminalReason?: string;
+    /** Human-readable failure message, set alongside `terminalReason`. */
+    terminalError?: string;
+}
+export type RunControlIntent = "suspend" | "cancel";
+export interface RuntimeSettingRecord {
+    scope: string;
+    key: string;
+    value: JsonValue;
+    updatedAt: string;
+}
+export interface RuntimeControlEvent {
+    id: string;
+    scope: string;
+    type: string;
+    timestamp: string;
+    data: JsonObject;
+}
+export interface RunEvent {
+    id: string;
+    runId: string;
+    sequence: number;
+    type: RunEventType;
+    timestamp: string;
+    data: JsonObject;
+}
+export interface ToolCallRecord {
+    id: string;
+    runId: string;
+    toolName: string;
+    status: "requested" | "waiting_for_approval" | "running" | "completed" | "failed" | "cancelled" | "timeout";
+    input: unknown;
+    result?: unknown;
+    modelOutput?: unknown;
+    error?: string;
+    idempotencyKey: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CheckpointRecord {
+    id: string;
+    runId: string;
+    name: string;
+    createdAt: string;
+    data: JsonObject;
+}
+export type CheckpointRetentionReason = "active_compaction" | "terminal_ttl";
+export interface CheckpointRetentionOptions {
+    /** Report candidate rows/bytes without deleting anything. */
+    dryRun?: boolean;
+    /** Restrict maintenance to one run. */
+    runId?: string;
+    /** Restrict active compaction to these checkpoint names. Terminal TTL still applies to all names. */
+    activeNames?: string[] | undefined;
+    /** Clock used for TTL cutoffs. Defaults to the adapter/runtime clock. */
+    now?: Date | string | undefined;
+    /** Active/waiting runs keep only this many latest checkpoints per (run_id, name). */
+    maxActivePerRunName?: number | undefined;
+    /** Completed/cancelled terminal runs lose checkpoints after this age. */
+    terminalTtlMs?: number | undefined;
+    /** Failed terminal runs lose checkpoints after this age. */
+    failedRunTtlMs?: number | undefined;
+    /** Scheduled terminal runs can use a shorter checkpoint TTL. */
+    scheduledRunTtlMs?: number | undefined;
+}
+export interface CheckpointRetentionResult {
+    dryRun: boolean;
+    candidateRows: number;
+    candidateBytes: number;
+    prunedRows: number;
+    prunedBytes: number;
+    byReason: Record<CheckpointRetentionReason, {
+        rows: number;
+        bytes: number;
+    }>;
+}
+export interface DeliveryObligation {
+    id: string;
+    runId: string;
+    channel: string;
+    payload: JsonObject;
+    idempotencyKey: string;
+    status: "pending" | "sending" | "sent" | "failed";
+    attemptCount: number;
+    maxAttempts: number;
+    nextAttemptAt: string;
+    leaseToken?: string;
+    leaseExpiresAt?: string;
+    lastError?: string;
+    sentAt?: string;
+    failedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ConversationRecord {
+    id: string;
+    /** Stable logical agent identity. Unlike agentRevision, this survives deploys. */
+    agentScope?: string;
+    agentRevision: string;
+    channel: string;
+    subject?: string;
+    title?: string;
+    archivedAt?: string;
+    metadata: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ConversationCursor {
+    updatedAt: string;
+    id: string;
+}
+export interface MessageCursor {
+    createdAt: string;
+    id: string;
+}
+export interface MessageRecord {
+    id: string;
+    conversationId: string;
+    runId?: string;
+    role: "user" | "assistant" | "tool" | "system";
+    content: JsonObject;
+    createdAt: string;
+}
+export type ConversationTurnStatus = "pending" | "running" | "blocked" | "completed" | "failed" | "cancelled";
+/**
+ * Durable ingress mailbox row. A conversation may have at most one
+ * `running`/`blocked` row; later turns remain `pending` in provider order.
+ */
+export interface ConversationTurnRecord {
+    id: string;
+    agentScope: string;
+    conversationId: string;
+    channel: string;
+    eventId: string;
+    payload: JsonObject;
+    idempotencyScope: string;
+    idempotencyKey: string;
+    status: ConversationTurnStatus;
+    runId?: string;
+    attemptCount: number;
+    maxAttempts: number;
+    nextAttemptAt: string;
+    leaseToken?: string;
+    leaseExpiresAt?: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ScheduleRecord {
+    id: string;
+    name: string;
+    cron: string;
+    timezone?: string;
+    metadata: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ScheduleRunRecord {
+    id: string;
+    scheduleId: string;
+    runId?: string;
+    status: string;
+    runAt: string;
+    idempotencyKey: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FileIndexRecord {
+    id: string;
+    runId?: string;
+    path: string;
+    kind: "memory" | "artifact" | "file";
+    blobKey: string;
+    sha256: string;
+    sizeBytes: number;
+    metadata: JsonObject;
+    createdAt: string;
+}
+export type UsageBillingMode = "api_key" | "chatgpt" | "byok" | "subscription" | "unknown";
+export type UsageTokenSource = "provider_reported" | "provider_reconciled" | "unavailable";
+export type UsageCostSource = "provider_reported" | "provider_reconciled" | "unavailable";
+export type UsageRecordKind = "transaction" | "control_total" | "adjustment";
+export interface UsageRecordInput {
+    idempotencyKey?: string;
+    runId?: string;
+    parentRunId?: string;
+    agentId?: string;
+    agentRevision?: string;
+    subagent?: string;
+    turnId?: string;
+    iteration?: number;
+    provider?: string;
+    providerRequestId?: string;
+    model?: string;
+    responseModel?: string;
+    billingMode?: UsageBillingMode;
+    recordKind?: UsageRecordKind;
+    /** Total provider input including cached input. */
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Subset of inputTokens served from cache. */
+    cachedTokens?: number;
+    /** Subset of inputTokens written to an explicit provider cache. */
+    cacheWriteTokens?: number;
+    /** Subset of outputTokens consumed by reasoning. */
+    reasoningTokens?: number;
+    /** Actual provider-reported/reconciled USD. Never use for estimates. */
+    costUsd?: number | null;
+    upstreamCostUsd?: number | null;
+    currency?: string;
+    tokenSource?: UsageTokenSource;
+    costSource?: UsageCostSource;
+    providerReceipt?: JsonObject;
+    receiptSha256?: string;
+    metadata?: JsonObject;
+    occurredAt?: string;
+}
+export interface UsageRecord {
+    id: string;
+    idempotencyKey: string;
+    runId?: string;
+    parentRunId?: string;
+    agentId?: string;
+    agentRevision?: string;
+    subagent?: string;
+    turnId?: string;
+    iteration?: number;
+    provider?: string;
+    providerRequestId?: string;
+    model?: string;
+    responseModel?: string;
+    billingMode: UsageBillingMode;
+    recordKind: UsageRecordKind;
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    /** Exact integer micro-dollars serialized as a decimal string. */
+    costMicros: string | null;
+    upstreamCostMicros: string | null;
+    /** Convenience projections; exact accounting uses the micro-dollar fields. */
+    costUsd: number | null;
+    upstreamCostUsd: number | null;
+    currency: string;
+    tokenSource: UsageTokenSource;
+    costSource: UsageCostSource;
+    providerReceipt: JsonObject;
+    receiptSha256?: string;
+    metadata: JsonObject;
+    occurredAt: string;
+    createdAt: string;
+}
+export type UsageGroupBy = "agentId" | "agentRevision" | "runId" | "parentRunId" | "subagent" | "provider" | "model" | "responseModel" | "billingMode" | "currency" | "tokenSource" | "costSource" | "recordKind" | "day" | "month";
+export interface UsageQuery {
+    runId?: string;
+    parentRunId?: string;
+    agentId?: string;
+    agentRevision?: string;
+    subagent?: string;
+    provider?: string;
+    model?: string;
+    responseModel?: string;
+    billingMode?: UsageBillingMode;
+    currency?: string;
+    tokenSource?: UsageTokenSource;
+    costSource?: UsageCostSource;
+    recordKind?: UsageRecordKind;
+    from?: string;
+    to?: string;
+    before?: {
+        occurredAt: string;
+        id: string;
+    };
+    limit?: number;
+}
+export interface UsageSummaryQuery extends Omit<UsageQuery, "before" | "limit"> {
+    groupBy?: UsageGroupBy[];
+}
+export interface UsageAggregate {
+    dimensions: JsonObject;
+    recordCount: string;
+    inputTokens: string;
+    outputTokens: string;
+    cachedTokens: string;
+    cacheWriteTokens: string;
+    reasoningTokens: string;
+    actualCostMicros: string;
+    upstreamCostMicros: string;
+    currency: string;
+    unavailableCostRecords: string;
+    unreconciledTokenRecords: string;
+    /** Records without provider-reported/reconciled cash. */
+    unreconciledRecords: string;
+}
+export interface SandboxSnapshotRecord {
+    id: string;
+    runId: string;
+    sandboxId: string;
+    snapshotId: string;
+    metadata: JsonObject;
+    createdAt: string;
+}
+export interface SandboxSyncJobRecord {
+    id: string;
+    runId: string;
+    sandboxId: string;
+    status: "pending" | "running" | "completed" | "failed" | "blocked_requires_operator";
+    idempotencyKey: string;
+    reason: string;
+    manifest: JsonObject;
+    error?: string;
+    attemptCount: number;
+    maxAttempts: number;
+    nextAttemptAt: string;
+    leaseToken?: string;
+    leaseExpiresAt?: string;
+    completedAt?: string;
+    failedAt?: string;
+    lastError?: string;
+    metadata: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SandboxSessionRecord {
+    id: string;
+    sessionKey: string;
+    provider: string;
+    sandboxId: string;
+    runId?: string;
+    state: "live" | "warm" | "dirty" | "clean" | "blocked_requires_operator";
+    dirty: boolean;
+    lastSeenAt: string;
+    lastSyncedAt?: string;
+    snapshotId?: string;
+    syncJobId?: string;
+    manifest: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+}
+export type SandboxSessionInput = Omit<SandboxSessionRecord, "id" | "createdAt" | "updatedAt"> & {
+    id?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};
+export type SandboxSessionPatch = {
+    [K in keyof Omit<SandboxSessionRecord, "id" | "createdAt" | "sessionKey">]?: Omit<SandboxSessionRecord, "id" | "createdAt" | "sessionKey">[K] | undefined;
+};
+export type SandboxSyncJobInput = Omit<SandboxSyncJobRecord, "id" | "createdAt" | "updatedAt" | "attemptCount" | "maxAttempts" | "nextAttemptAt" | "metadata"> & {
+    attemptCount?: number;
+    maxAttempts?: number;
+    nextAttemptAt?: string;
+    metadata?: JsonObject;
+};
+export interface SandboxSyncLeaseOptions {
+    now?: Date;
+    limit?: number;
+    leaseForMs?: number;
+}
+export interface SandboxSyncFailureInput {
+    error: string;
+    now?: Date;
+    retryDelayMs?: number;
+}
+export interface SandboxSyncExecutionResult {
+    jobId: string;
+    status: "completed" | "retrying" | "failed";
+    run?: RunRecord;
+    error?: string;
+}
+export interface SandboxSyncDiagnostics {
+    total: number;
+    byStatus: Record<string, number>;
+    due: number;
+    leased: number;
+    expiredLeases: number;
+    failed: number;
+    blockedRequiresOperator: number;
+}
+export interface SandboxSyncJobInspection {
+    job: SandboxSyncJobRecord;
+    due: boolean;
+    leaseExpired: boolean;
+}
+export type SandboxSyncJobPatch = {
+    [Key in keyof Omit<SandboxSyncJobRecord, "id" | "createdAt">]?: Omit<SandboxSyncJobRecord, "id" | "createdAt">[Key] | undefined;
+};
+export interface MemoryScope {
+    agentScope: string;
+    userId?: string;
+    conversationId?: string;
+    projectId?: string;
+}
+export interface MemoryDocument {
+    scope: MemoryScope;
+    path: string;
+    body: string | {
+        blobKey: string;
+    };
+    contentType: "text/markdown" | "application/json" | "text/plain";
+    title?: string;
+    summary?: string;
+    tags: string[];
+    confidence?: "low" | "medium" | "high";
+    sourceRefs?: string[];
+    tokenEstimate: number;
+    sha256: string;
+    revision: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MemorySearchResult {
+    path: string;
+    title?: string;
+    summary?: string;
+    snippet: string;
+    revision: string;
+    tags: string[];
+    updatedAt: string;
+    rankReason: string;
+}
+export interface MemoryEmbeddingProvider {
+    model: string;
+    dimensions?: number;
+    maxInputTokens?: number;
+    embed(input: {
+        text: string;
+        purpose: "query" | "document";
+        model?: string;
+        metadata?: JsonObject;
+    }): Promise<{
+        embedding: number[];
+        model?: string;
+        dimensions?: number;
+    }> | {
+        embedding: number[];
+        model?: string;
+        dimensions?: number;
+    };
+}
+export interface MemoryEmbeddingRecord {
+    id: string;
+    scope: MemoryScope;
+    path: string;
+    model: string;
+    dimensions: number;
+    contentSha256: string;
+    embedding: number[];
+    stale: boolean;
+    metadata: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Required facet: runs, events, tool calls, checkpoints, deliveries
+ * (including the durable delivery queue), and idempotency reservations.
+ */
+export interface RunStore {
+    createRun(input: Omit<RunRecord, "id" | "createdAt" | "updatedAt">): Promise<RunRecord>;
+    updateRun(id: string, patch: Partial<Omit<RunRecord, "id" | "createdAt">>): Promise<RunRecord>;
+    /**
+     * Heartbeat: bump `updatedAt` only, and only while the run is still
+     * `created`/`running`. Unlike `updateRun`, this must never write any other
+     * column, so a heartbeat racing a status transition cannot clobber it.
+     */
+    touchRun?(id: string): Promise<void>;
+    /** Atomically request suspend/cancel with cancel precedence across replicas. */
+    requestRunControl?(id: string, intent: RunControlIntent): Promise<RunRecord>;
+    /** Atomically apply the latest pending control intent and clear it. */
+    settleRunControl?(id: string): Promise<RunRecord>;
+    getRun(id: string): Promise<RunRecord | undefined>;
+    listRuns(): Promise<RunRecord[]>;
+    appendEvent(runId: string, type: RunEventType, data?: JsonObject): Promise<RunEvent>;
+    listEvents(runId: string): Promise<RunEvent[]>;
+    createToolCall(input: Omit<ToolCallRecord, "id" | "createdAt" | "updatedAt">): Promise<ToolCallRecord>;
+    updateToolCall(id: string, patch: Partial<Omit<ToolCallRecord, "id" | "createdAt">>): Promise<ToolCallRecord>;
+    listToolCalls(runId: string): Promise<ToolCallRecord[]>;
+    createCheckpoint(input: Omit<CheckpointRecord, "id" | "createdAt">): Promise<CheckpointRecord>;
+    listCheckpoints(runId: string): Promise<CheckpointRecord[]>;
+    compactCheckpoints?(options?: CheckpointRetentionOptions): Promise<CheckpointRetentionResult>;
+    createDelivery(input: DeliveryObligationInput): Promise<DeliveryObligation>;
+    updateDelivery(id: string, patch: DeliveryObligationPatch): Promise<DeliveryObligation>;
+    listDeliveries(runId: string): Promise<DeliveryObligation[]>;
+    leaseDueDeliveries?(options?: DeliveryLeaseOptions): Promise<DeliveryObligation[]>;
+    completeDeliverySend?(id: string, leaseToken: string, patch?: {
+        payload?: JsonObject;
+    }): Promise<DeliveryObligation>;
+    failDeliverySend?(id: string, leaseToken: string, failure: DeliveryFailureInput): Promise<DeliveryObligation>;
+    recoverExpiredDeliveries?(now?: Date): Promise<DeliveryObligation[]>;
+    listRunsByStatus?(statuses: RunStatus[], options?: {
+        updatedBefore?: string;
+        limit?: number;
+    }): Promise<RunRecord[]>;
+    reserveIdempotencyKey(scope: string, key: string, ownerId?: string): Promise<boolean>;
+    /** Release owned connections/resources; called once during graceful shutdown. */
+    close?(): Promise<void> | void;
+}
+/** Optional facet: conversations and message history. */
+export interface ConversationStore {
+    upsertConversation(input: {
+        id: string;
+        agentScope?: string;
+        agentRevision: string;
+        channel: string;
+        subject?: string;
+        title?: string;
+        metadata?: JsonObject;
+    }): Promise<ConversationRecord>;
+    getConversation(id: string): Promise<ConversationRecord | undefined>;
+    listConversations?(input: {
+        agentScope: string;
+        channel?: string;
+        subject?: string;
+        archived?: boolean;
+        before?: ConversationCursor;
+        limit?: number;
+    }): Promise<ConversationRecord[]>;
+    updateConversation?(id: string, patch: {
+        title?: string | null;
+        archivedAt?: string | null;
+        metadata?: JsonObject;
+    }): Promise<ConversationRecord | undefined>;
+    listRecentConversationsBySubject?(input: {
+        channel: string;
+        subject: string;
+        since?: string;
+        limit?: number;
+        excludeId?: string;
+    }): Promise<ConversationRecord[]>;
+    appendMessage(input: {
+        conversationId: string;
+        runId?: string;
+        role: MessageRecord["role"];
+        content: JsonObject;
+    }): Promise<MessageRecord>;
+    listRecentMessages(conversationId: string, limit?: number): Promise<MessageRecord[]>;
+    listMessages?(input: {
+        conversationId: string;
+        before?: MessageCursor;
+        limit?: number;
+    }): Promise<MessageRecord[]>;
+}
+/** Optional facet: durable, per-conversation FIFO ingress mailbox. */
+export interface ConversationTurnStore {
+    enqueueConversationTurn(input: {
+        agentScope: string;
+        conversationId: string;
+        channel: string;
+        eventId: string;
+        payload: JsonObject;
+        idempotencyScope: string;
+        idempotencyKey: string;
+        maxAttempts?: number;
+    }): Promise<{
+        turn: ConversationTurnRecord;
+        inserted: boolean;
+    }>;
+    leaseNextConversationTurn(options: {
+        agentScope: string;
+        leaseForMs: number;
+        now?: Date;
+    }): Promise<ConversationTurnRecord | undefined>;
+    attachConversationTurnRun(id: string, leaseToken: string, runId: string): Promise<ConversationTurnRecord>;
+    settleConversationTurn(id: string, leaseToken: string, status: "blocked" | "completed" | "failed" | "cancelled", options?: {
+        runId?: string;
+        error?: string;
+    }): Promise<ConversationTurnRecord>;
+    settleConversationTurnByRunId(runId: string, status: "blocked" | "completed" | "failed" | "cancelled", options?: {
+        error?: string;
+    }): Promise<ConversationTurnRecord | undefined>;
+    retryConversationTurn(id: string, leaseToken: string, error: string): Promise<ConversationTurnRecord>;
+    recoverExpiredConversationTurns(now?: Date): Promise<ConversationTurnRecord[]>;
+    listConversationTurns(options?: {
+        agentScope?: string;
+        conversationId?: string;
+        status?: ConversationTurnStatus;
+    }): Promise<ConversationTurnRecord[]>;
+}
+/** Optional facet: schedule registrations and dedupe of schedule runs. */
+export interface ScheduleStateStore {
+    registerSchedule(input: {
+        id: string;
+        name: string;
+        cron: string;
+        timezone?: string;
+        metadata?: JsonObject;
+    }): Promise<ScheduleRecord>;
+    recordScheduleRun(input: {
+        scheduleId: string;
+        runId?: string;
+        runAt: string;
+        idempotencyKey: string;
+        status?: string;
+    }): Promise<ScheduleRunRecord>;
+}
+/** Optional facet: index of memory/artifact/file blobs written by runs. */
+export interface FileIndexStore {
+    recordFileIndex(input: {
+        runId?: string;
+        path: string;
+        kind: FileIndexRecord["kind"];
+        blobKey: string;
+        sha256: string;
+        sizeBytes: number;
+        metadata?: JsonObject;
+    }): Promise<FileIndexRecord>;
+    listFileIndexes?(runId?: string): Promise<FileIndexRecord[]>;
+}
+/** Optional facet: source-backed model usage observability. */
+export interface UsageStore {
+    recordUsage(input: UsageRecordInput): Promise<UsageRecord>;
+    listUsage(runId?: string): Promise<UsageRecord[]>;
+    queryUsage?(query: UsageQuery): Promise<UsageRecord[]>;
+    summarizeUsage?(query: UsageSummaryQuery): Promise<UsageAggregate[]>;
+}
+/** Optional facet: sandbox sessions, snapshots, and the sandbox-sync queue. */
+export interface SandboxSessionStore {
+    recordSandboxSnapshot(input: {
+        runId: string;
+        sandboxId: string;
+        snapshotId: string;
+        metadata?: JsonObject;
+    }): Promise<SandboxSnapshotRecord>;
+    upsertSandboxSession(input: SandboxSessionInput): Promise<SandboxSessionRecord>;
+    getSandboxSession(sessionKey: string): Promise<SandboxSessionRecord | undefined>;
+    listSandboxSessions?(options?: {
+        dirty?: boolean;
+    }): Promise<SandboxSessionRecord[]>;
+    updateSandboxSession(sessionKey: string, patch: SandboxSessionPatch): Promise<SandboxSessionRecord>;
+    createSandboxSyncJob(input: SandboxSyncJobInput): Promise<SandboxSyncJobRecord>;
+    updateSandboxSyncJob(id: string, patch: SandboxSyncJobPatch): Promise<SandboxSyncJobRecord>;
+    listSandboxSyncJobs(runId?: string): Promise<SandboxSyncJobRecord[]>;
+    enqueueSandboxSyncJob(input: SandboxSyncJobInput): Promise<SandboxSyncJobRecord>;
+    leaseSandboxSyncJobs(options?: SandboxSyncLeaseOptions): Promise<SandboxSyncJobRecord[]>;
+    completeSandboxSyncJob(id: string, leaseToken: string, patch?: {
+        manifest?: JsonObject;
+        metadata?: JsonObject;
+    }): Promise<SandboxSyncJobRecord>;
+    failSandboxSyncJob(id: string, leaseToken: string, failure: SandboxSyncFailureInput): Promise<SandboxSyncJobRecord>;
+    recoverExpiredSandboxSyncJobs(now?: Date): Promise<SandboxSyncJobRecord[]>;
+}
+/** Optional facet: durable memory documents and embeddings. */
+export interface MemoryStateStore {
+    /**
+     * Reports whether the durable store can persist and query vector
+     * embeddings. Omitted means supported for compatibility with existing
+     * adapters; stores with an optional vector backend must return false until
+     * that backend is configured.
+     */
+    supportsMemoryEmbeddings?(): boolean;
+    listMemoryDocuments(scope: MemoryScope, input?: MemoryListInput): Promise<MemoryDocument[]>;
+    searchMemoryDocuments?(scope: MemoryScope, input: MemorySearchInput): Promise<MemorySearchResult[]>;
+    getMemoryDocument(scope: MemoryScope, path: string): Promise<MemoryDocument | undefined>;
+    upsertMemoryDocument(document: MemoryDocument): Promise<MemoryDocument>;
+    deleteMemoryDocument(scope: MemoryScope, path: string): Promise<void>;
+    listMemoryDocumentsNeedingEmbeddings(scope: MemoryScope, options: {
+        model: string;
+        limit?: number;
+    }): Promise<MemoryDocument[]>;
+    upsertMemoryEmbedding(input: Omit<MemoryEmbeddingRecord, "id" | "createdAt" | "updatedAt">): Promise<MemoryEmbeddingRecord>;
+    searchMemoryEmbeddings(scope: MemoryScope, input: MemorySearchInput, embedding: number[], options: {
+        model: string;
+        limit?: number;
+    }): Promise<MemorySearchResult[]>;
+    markMemoryEmbeddingsStale(scope: MemoryScope, path: string, currentSha256: string): Promise<void>;
+}
+/** Optional durable runtime settings and non-run control-plane audit log. */
+export interface RuntimeSettingsStore {
+    getSetting(scope: string, key: string): Promise<RuntimeSettingRecord | undefined>;
+    setSetting(scope: string, key: string, value: RuntimeSettingRecord["value"]): Promise<RuntimeSettingRecord>;
+    appendRuntimeControlEvent(scope: string, type: string, data?: JsonObject): Promise<RuntimeControlEvent>;
+    listRuntimeControlEvents(scope: string): Promise<RuntimeControlEvent[]>;
+}
+/**
+ * The historical monolithic state contract. Runtime settings remain outside
+ * this public intersection so existing third-party adapters keep compiling;
+ * the runtime adds an in-memory settings fallback during normalization.
+ */
+export type StateAdapter = RunStore & ConversationStore & ScheduleStateStore & FileIndexStore & UsageStore & SandboxSessionStore & MemoryStateStore;
+/** Internal normalized state contract after optional facets are filled. */
+export type ResolvedStateAdapter = StateAdapter & RuntimeSettingsStore & ConversationTurnStore;
+/**
+ * Facet-shaped state configuration for `RuntimeOptions.state`. Only `runs`
+ * is required; missing optional facets fall back to non-durable in-memory
+ * implementations (the runtime logs one `state.degraded` warning at boot).
+ */
+export interface StateStores {
+    runs: RunStore;
+    conversations?: ConversationStore;
+    conversationTurns?: ConversationTurnStore;
+    schedules?: ScheduleStateStore;
+    files?: FileIndexStore;
+    usage?: UsageStore;
+    sandboxSessions?: SandboxSessionStore;
+    memory?: MemoryStateStore;
+    settings?: RuntimeSettingsStore;
+}
+export declare function isRunStore(value: unknown): value is RunStore;
+export declare function isConversationStore(value: unknown): value is ConversationStore;
+export declare function isScheduleStateStore(value: unknown): value is ScheduleStateStore;
+export declare function isFileIndexStore(value: unknown): value is FileIndexStore;
+export declare function isUsageStore(value: unknown): value is UsageStore;
+export declare function isSandboxSessionStore(value: unknown): value is SandboxSessionStore;
+export declare function isMemoryStateStore(value: unknown): value is MemoryStateStore;
+export declare function isRuntimeSettingsStore(value: unknown): value is RuntimeSettingsStore;
+export declare function isConversationTurnStore(value: unknown): value is ConversationTurnStore;
+/** Detects a monolithic StateAdapter (vs a facet-shaped `StateStores`). */
+export declare function isStateAdapter(value: unknown): value is StateAdapter;
+//# sourceMappingURL=state.d.ts.map