better-supabase 0.12.0 → 0.13.0

package/dist/ai-chat-B00sIOjY.d.ts

@@ -0,0 +1,619 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-mijqfoJN.js";
+import { t as StandardSchemaV1 } from "./standard-16AIDny5.js";
+import { r as FieldsOf } from "./block-fields-DnXkMney.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DBPhgF3W.js";
+import { r as BlockTemporalOptions } from "./block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { i as AiMessage, s as AiMessageRole } from "./message-Bg4TKA12.js";
+import { g as JobHandler } from "./types-CB5MvzuE.js";
+import { n as FinalRunState, r as RunState } from "./run-state-CPo-1X2B.js";
+//#region src/blocks/ai-chat/durable.d.ts
+/** Where a run is: written by `runs.claim`, `release` and `stop`. */
+type AiRunState = Exclude<RunState, "waiting">;
+/** One generation of a chat, as `ai_runs` stores it. */
+interface AiRun {
+  readonly id: string;
+  readonly chatId: string;
+  readonly ownerId: string;
+  readonly assistantMessageId: string | undefined;
+  readonly streamId: string | undefined;
+  /** `ai-sdk` for a request-bound answer, `workflow` for a durable one. */
+  readonly engine: string;
+  /** The durable engine's own run id, such as a Workflow SDK run. */
+  readonly externalRunId: string | undefined;
+  readonly model: string | undefined;
+  readonly status: AiRunState;
+  readonly usage: Readonly<Record<string, unknown>>;
+  readonly costMicroUsd: number | undefined;
+  readonly error: string | undefined;
+  readonly startedAt: Temporal.Instant;
+  readonly endedAt: Temporal.Instant | undefined;
+}
+interface AiRunQuery {
+  /** One chat's runs; without it, the caller's own. */
+  readonly chatId?: string;
+  /** `true` keeps unfinished runs, `false` finished ones. */
+  readonly active?: boolean;
+  /** At most 200; defaults to 50. */
+  readonly limit?: number;
+}
+type AiRunStepStatus = "running" | "done" | "error" | "skipped";
+/** One step of a long run's progress, as `ai_run_steps` stores it. */
+interface AiRunStep {
+  readonly id: string;
+  readonly runId: string;
+  readonly chatId: string;
+  /** The idempotency key: recording the same key again updates the step. */
+  readonly key: string;
+  readonly label: string;
+  readonly status: AiRunStepStatus;
+  readonly detail: Readonly<Record<string, unknown>>;
+  readonly startedAt: Temporal.Instant;
+  readonly endedAt: Temporal.Instant | undefined;
+}
+interface AiRunStepInput {
+  readonly key: string;
+  /** Defaults to the key on the first record, then keeps the stored label. */
+  readonly label?: string;
+  /** Defaults to `running`. */
+  readonly status?: AiRunStepStatus;
+  /** Merged into the stored detail. */
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+/** An undecided approval in the caller's inbox, with its chat's title. */
+interface AiPendingApproval extends AiToolApproval {
+  readonly chatTitle: string;
+}
+/** Run lookups and steps; `AiChat.runs` has all of them. */
+interface AiRuns {
+  get(runId: string): AsyncResult<AiRun>;
+  list(query?: AiRunQuery): AsyncResult<readonly AiRun[]>;
+  /** Records the durable engine's run id on a claimed run (service role). */
+  attach(runId: string, externalRunId: string): AsyncResult<boolean>;
+  readonly steps: {
+    /** Records or updates one step by its key (service role). */
+    record(runId: string, step: AiRunStepInput): AsyncResult<AiRunStep>;
+    list(runId: string): AsyncResult<readonly AiRunStep[]>;
+  };
+  /** The caller's undecided approvals across chats, newest first. */
+  pendingApprovals(size?: number): AsyncResult<readonly AiPendingApproval[]>;
+}
+type AiHarnessStatus = "active" | "idle" | "stopped" | "error";
+/**
+ * What a coding-agent harness keeps per chat to pick the conversation up again.
+ * The states are the harness's own JSON; nothing here reads them.
+ */
+interface AiHarnessSession {
+  readonly chatId: string;
+  readonly harnessId: string;
+  readonly ownerId: string;
+  readonly resumeState: unknown;
+  readonly continueState: unknown;
+  readonly sandboxId: string | undefined;
+  readonly status: AiHarnessStatus;
+  readonly lockHolder: string | undefined;
+  readonly lockedUntil: Temporal.Instant | undefined;
+  readonly lastActiveAt: Temporal.Instant;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** The fields to change; a field that is absent keeps its value. */
+interface AiHarnessSessionPatch {
+  readonly resumeState?: unknown;
+  readonly continueState?: unknown;
+  /** Registers the session's sandbox in `ai_sandboxes`; `null` marks it stopped. */
+  readonly sandboxId?: string | null;
+  /** Who runs the sandbox, such as `vercel`. Defaults to `harness`. */
+  readonly sandboxProvider?: string;
+  readonly status?: AiHarnessStatus;
+}
+/**
+ * The experimental harness session store, on the service role: `lock` keeps two
+ * turns from driving one sandbox, `save` refuses a session another holder
+ * locked (`AI_HARNESS_LOCKED`).
+ */
+interface AiHarnessSessions {
+  load(chatId: string, harnessId: string): AsyncResult<AiHarnessSession | undefined>;
+  save(chatId: string, harnessId: string, patch: AiHarnessSessionPatch, options?: {
+    readonly holder?: string;
+  }): AsyncResult<AiHarnessSession>;
+  /** `true` when `holder` holds the lock for `ttlSeconds` (default 300). */
+  lock(chatId: string, harnessId: string, holder: string, options?: {
+    readonly ttlSeconds?: number;
+  }): AsyncResult<boolean>;
+  unlock(chatId: string, harnessId: string, holder: string): AsyncResult<boolean>;
+}
+/**
+ * The harness session store of the `ai-chat` block (experimental). It takes a
+ * service transport: harness state stays on the server.
+ */
+declare function createHarnessSessions(options: AiChatOptions): AiHarnessSessions;
+//#endregion
+//#region src/blocks/ai-chat/sandboxes.d.ts
+type AiSandboxStatus = "running" | "stopping" | "stopped";
+interface AiSandbox {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly userId: string | undefined;
+  readonly chatId: string | undefined;
+  /** The harness session the sandbox belongs to, when a harness started it. */
+  readonly harnessId: string | undefined;
+  /**
+   * Who runs it, such as `vercel` or `anthropic`; `harness` for a harness
+   * session's sandbox saved without one.
+   */
+  readonly provider: string;
+  readonly sandboxId: string;
+  /** A provider container id, such as Anthropic's code execution container. */
+  readonly containerId: string | undefined;
+  readonly status: AiSandboxStatus;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly idleSeconds: number;
+  readonly error: string | undefined;
+  readonly lastUsedAt: Temporal.Instant;
+  readonly expiresAt: Temporal.Instant | undefined;
+  readonly stoppedAt: Temporal.Instant | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface NewAiSandbox {
+  readonly provider: string;
+  readonly sandboxId: string;
+  readonly userId?: string;
+  readonly chatId?: string;
+  readonly harnessId?: string;
+  readonly containerId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /**
+   * Seconds without use before the idle-stop claim takes it; ai-chat's
+   * `sandboxIdleAfter` by default.
+   */
+  readonly idleSeconds?: number;
+  readonly expiresAt?: Temporal.Instant;
+}
+/** Stops one sandbox at its provider. A throw keeps it running for the next try. */
+type AiSandboxStopper = (sandbox: AiSandbox) => Promise<unknown>;
+/**
+ * The sandboxes chats and harness sessions started, in `ai_sandboxes`, with one
+ * idle-stop claim for all of them.
+ */
+interface AiSandboxes {
+  /** Records a sandbox, or marks a known one running and used (service role). */
+  register(organizationId: string, sandbox: NewAiSandbox): AsyncResult<AiSandbox>;
+  /** Marks a sandbox used now (service role). `false` when it is not running. */
+  touch(sandboxId: string): AsyncResult<boolean>;
+  /** The chat's running sandbox at a provider, to reuse it (service role). */
+  forChat(chatId: string, provider: string): AsyncResult<AiSandbox | undefined>;
+  list(organizationId: string, options?: {
+    readonly chatId?: string;
+  }): AsyncResult<readonly AiSandbox[]>;
+  /**
+   * Claims idle and expired sandboxes to stop (service role). A sandbox whose
+   * harness session is locked by a turn is skipped.
+   */
+  idle(options?: {
+    readonly batch?: number;
+    readonly leaseSeconds?: number;
+  }): AsyncResult<readonly AiSandbox[]>;
+  /**
+   * Records a claimed stop. A stopped harness sandbox stops its session too;
+   * `false` when a turn used the sandbox again since the claim.
+   */
+  finishStop(sandboxId: string, stopped: boolean, error?: string): AsyncResult<boolean>;
+  /**
+   * Claims idle sandboxes, stops each with `stop`, and records the outcome.
+   * Returns how many stopped.
+   */
+  stopIdle(stop: AiSandboxStopper, options?: {
+    readonly batch?: number;
+  }): AsyncResult<number>;
+  /** A job handler that runs `stopIdle`; schedule it every few minutes. */
+  idleStopJob(stop: AiSandboxStopper, options?: {
+    readonly batch?: number;
+  }): JobHandler<unknown>;
+}
+//#endregion
+//#region src/blocks/ai-chat/ai-chat.d.ts
+type AiChatVisibility = "private" | "organization";
+interface AiChatRecord {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string;
+  readonly projectId: string | undefined;
+  readonly agentId: string | undefined;
+  readonly title: string;
+  readonly model: string | undefined;
+  readonly visibility: AiChatVisibility;
+  readonly pinned: boolean;
+  readonly archivedAt: Temporal.Instant | undefined;
+  /** A temporary chat expires at `expiresAt` and never reaches the chat list. */
+  readonly temporary: boolean;
+  readonly expiresAt: Temporal.Instant | undefined;
+  /** The message the chat shows: the end of the active branch. */
+  readonly leafId: string | undefined;
+  /** The stream of the answer being written, while one runs. */
+  readonly activeStreamId: string | undefined;
+  readonly activeRunId: string | undefined;
+  readonly lastMessageAt: Temporal.Instant;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface AiChatInput {
+  /** A client-made id, so a retried create returns the same chat. */
+  readonly id?: string;
+  readonly title?: string;
+  readonly model?: string | null;
+  readonly projectId?: string | null;
+  readonly agentId?: string | null;
+  /** `organization` needs `ai_chat.share`. */
+  readonly visibility?: AiChatVisibility;
+  readonly pinned?: boolean;
+  readonly temporary?: boolean;
+  /** The service role only: the user the chat belongs to. */
+  readonly ownerId?: string;
+}
+interface AiChatPatch {
+  readonly title?: string;
+  readonly model?: string | null;
+  readonly projectId?: string | null;
+  readonly visibility?: AiChatVisibility;
+  readonly pinned?: boolean;
+  readonly archived?: boolean;
+}
+interface AiChatQuery {
+  readonly organizationId?: string | null;
+  /** Full-text search over titles and message text. */
+  readonly search?: string;
+  readonly projectId?: string;
+  readonly pinned?: boolean;
+  readonly archived?: boolean;
+  /** The `next` cursor of the previous page. */
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+interface AiChatPage<F extends object = Record<never, never>> {
+  readonly items: readonly (AiChatRecord & F)[];
+  /** Pass as `after` for the next page; `undefined` on the last one. */
+  readonly next: string | undefined;
+}
+interface AiProject {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ownerId: string;
+  readonly name: string;
+  readonly instructions: string;
+  readonly defaultModel: string | undefined;
+  readonly pinned: boolean;
+  readonly archivedAt: Temporal.Instant | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface AiProjectInput {
+  readonly name?: string;
+  readonly instructions?: string;
+  readonly defaultModel?: string | null;
+  readonly pinned?: boolean;
+  readonly archived?: boolean;
+}
+type AiStoredMessageStatus = "complete" | "aborted" | "error";
+/** A message as the tree stores it: the canonical fields plus its place. */
+interface AiStoredMessage extends AiMessage {
+  readonly parentId: string | undefined;
+  /** `canonical`, or the format `native` holds (such as `ai-sdk-ui`). */
+  readonly format: string;
+  /** The SDK's own message, when `path(..., { native: true })` asks for it. */
+  readonly native: unknown;
+  readonly model: string | undefined;
+  readonly status: AiStoredMessageStatus;
+  readonly createdAt: Temporal.Instant;
+  /** How many messages share this one's parent, itself included. */
+  readonly siblingCount: number;
+  /** Its position among them, from 0, oldest first. */
+  readonly siblingIndex: number;
+}
+interface AiMessageSibling {
+  readonly id: string;
+  readonly role: AiMessageRole;
+  readonly createdAt: Temporal.Instant;
+}
+type AiUserMessageTrigger = "submit-message" | "regenerate-message";
+interface AiAppendResult {
+  /** The stored id: a fresh one when the message edits an earlier one. */
+  readonly messageId: string;
+  readonly parentId: string | undefined;
+  /** `false` for a retry, or for `regenerate-message`, which adds nothing. */
+  readonly created: boolean;
+}
+interface AiAssistantMessageOptions {
+  readonly parentId: string;
+  readonly status?: AiStoredMessageStatus;
+  readonly model?: string;
+  /** The format of `native`, such as `ai-sdk-ui`. */
+  readonly format?: string;
+  readonly native?: unknown;
+  /** The run `runs.claim` returned. */
+  readonly runId?: string | undefined;
+}
+interface AiSaveResult {
+  readonly messageId: string;
+  readonly parentId: string | undefined;
+  readonly created: boolean;
+}
+interface AiStreamClaim {
+  /** `false` while another live stream writes the chat's answer. */
+  readonly claimed: boolean;
+  readonly streamId: string | undefined;
+  readonly runId: string | undefined;
+}
+/** How a run ended, as `runs.release` records it. */
+type AiRunStatus = Extract<AiRunState, FinalRunState>;
+interface AiRunRelease {
+  readonly status?: AiRunStatus;
+  readonly usage?: Readonly<Record<string, unknown>>;
+  readonly generationId?: string;
+  readonly error?: string;
+  readonly costMicroUsd?: number;
+}
+type AiApprovalDecision = "pending" | "approved" | "denied";
+interface AiToolApproval {
+  readonly approvalId: string;
+  readonly chatId: string;
+  readonly runId: string | undefined;
+  readonly messageId: string | undefined;
+  readonly tool: string;
+  readonly toolCallId: string;
+  readonly input: unknown;
+  readonly decision: AiApprovalDecision;
+  readonly reason: string | undefined;
+  readonly signature: string | undefined;
+  readonly decidedBy: string | undefined;
+  readonly decidedAt: Temporal.Instant | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface AiToolApprovalRequest {
+  readonly approvalId: string;
+  readonly tool: string;
+  readonly toolCallId: string;
+  readonly input?: unknown;
+  readonly runId?: string;
+  readonly messageId?: string;
+  /**
+   * A signature over the input, so the decision can't be replayed on other
+   * input.
+   */
+  readonly signature?: string;
+}
+type AiToolPolicy = "auto" | "ask" | "deny";
+interface AiPendingInput {
+  readonly id: string;
+  readonly chatId: string;
+  readonly runId: string | undefined;
+  readonly toolCallId: string | undefined;
+  readonly question: string;
+  /** A JSON Schema for the answer. */
+  readonly schema: unknown;
+  readonly answer: unknown;
+  readonly answeredAt: Temporal.Instant | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface AiPendingInputRequest {
+  readonly question: string;
+  readonly schema?: unknown;
+  readonly runId?: string;
+  readonly toolCallId?: string;
+}
+interface AiFeedback {
+  readonly chatId: string;
+  readonly messageId: string;
+  /** `1` up, `-1` down, `0` cleared. */
+  readonly rating: -1 | 0 | 1;
+  readonly reason: string | undefined;
+  readonly comment: string | undefined;
+}
+interface AiChatShare {
+  readonly id: string;
+  readonly leafId: string;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly revokedAt: Temporal.Instant | undefined;
+}
+/** A new share link. The token is shown once; only its hash is stored. */
+interface AiShareLink {
+  readonly id: string;
+  readonly token: string;
+  readonly leafId: string;
+  readonly createdAt: Temporal.Instant;
+}
+interface SharedAiChat {
+  readonly chat: {
+    readonly id: string;
+    readonly title: string;
+    readonly model: string | undefined;
+    readonly createdAt: Temporal.Instant;
+  };
+  readonly leafId: string;
+  readonly messages: readonly AiStoredMessage[];
+}
+interface AiModel {
+  readonly id: string;
+  readonly provider: string;
+  readonly name: string;
+  readonly pricing: Readonly<Record<string, unknown>>;
+  readonly capabilities: Readonly<Record<string, unknown>>;
+  /** Entitlement keys that unlock it; empty for every tenant. */
+  readonly plans: readonly string[];
+  readonly enabled: boolean;
+  readonly refreshedAt: Temporal.Instant | undefined;
+}
+interface AiModelInput {
+  readonly id: string;
+  readonly provider?: string;
+  readonly name?: string;
+  readonly pricing?: Readonly<Record<string, unknown>>;
+  readonly capabilities?: Readonly<Record<string, unknown>>;
+  readonly plans?: readonly string[];
+  readonly enabled?: boolean;
+}
+type AiModerationStage = "input" | "output" | "tool";
+type AiModerationAction = "allow" | "flag" | "redact" | "block";
+interface AiModerationEvent {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly chatId: string | undefined;
+  readonly messageId: string | undefined;
+  readonly userId: string | undefined;
+  readonly stage: AiModerationStage;
+  /** What the moderator flagged, such as `pii` or `prompt-injection`. */
+  readonly category: string;
+  readonly score: number | undefined;
+  readonly action: AiModerationAction;
+  readonly createdAt: Temporal.Instant;
+}
+interface AiModerationInput {
+  readonly organizationId: string;
+  readonly stage: AiModerationStage;
+  readonly action: AiModerationAction;
+  readonly category: string;
+  readonly chatId?: string;
+  readonly messageId?: string;
+  readonly userId?: string;
+  readonly score?: number;
+}
+interface AiChatOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the chat columns the app adds
+   * (`blocks.ai-chat.options.extraColumns`), keyed by column name. It types and
+   * parses them on the chat reads, and validates them on `chats.create` and
+   * `chats.update`, which return a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<AiChat<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /**
+   * Calls as the user: `rpcTransport(supabase)` or
+   * `sqlTransport(postgres.asUser(claims))`.
+   */
+  readonly transport: BlockTransport;
+  /**
+   * Calls as the service role, for what only the server writes (assistant
+   * messages, stream claims, approvals, the model catalog). Defaults to
+   * `transport`, which then has to be a service transport.
+   */
+  readonly service?: BlockTransport;
+  /** The module schema (`blocks["ai-chat"].schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** `F` is the extra chat fields `options.fields` describes. */
+interface AiChat<F extends object = Record<never, never>> {
+  readonly chats: {
+    /** Keys besides the input's own are the chat's extra columns. */
+    create(organizationId: string, input?: AiChatInput & Partial<F>): AsyncResult<AiChatRecord & F>;
+    get(chatId: string): AsyncResult<AiChatRecord & F>;
+    list(query?: AiChatQuery): AsyncResult<AiChatPage<F>>;
+    update(chatId: string, patch: AiChatPatch & Partial<F>): AsyncResult<AiChatRecord & F>;
+    remove(chatId: string): AsyncResult<boolean>;
+    /** Deletes expired temporary chats (service role); returns how many. */
+    purge(batch?: number): AsyncResult<number>;
+  };
+  readonly projects: {
+    create(organizationId: string, input: AiProjectInput & {
+      readonly name: string;
+    }): AsyncResult<AiProject>;
+    update(projectId: string, input: AiProjectInput): AsyncResult<AiProject>;
+    list(organizationId: string): AsyncResult<readonly AiProject[]>;
+    remove(projectId: string): AsyncResult<boolean>;
+  };
+  readonly messages: {
+    /**
+     * Stores the user's message under the chat's leaf. A retry with the same id
+     * is a no-op; the same id with other parts is an edit, stored as a sibling
+     * with a fresh id.
+     */
+    appendUser(chatId: string, message: AiMessage, options?: {
+      readonly trigger?: AiUserMessageTrigger;
+      readonly messageId?: string;
+    }): AsyncResult<AiAppendResult>;
+    /** Stores an answer (service role); a retry with the same id updates it. */
+    saveAssistant(chatId: string, message: AiMessage, options: AiAssistantMessageOptions): AsyncResult<AiSaveResult>;
+    /** The messages from the root to `leafId`, default the chat's leaf. */
+    path(chatId: string, options?: {
+      readonly leafId?: string;
+      readonly native?: boolean;
+    }): AsyncResult<readonly AiStoredMessage[]>;
+    siblings(chatId: string, messageId: string): AsyncResult<readonly AiMessageSibling[]>;
+    /** Shows the branch through `messageId`; returns the new leaf. */
+    switchBranch(chatId: string, messageId: string): AsyncResult<string>;
+  };
+  /**
+   * The sandboxes chats and harness sessions started, with one idle-stop claim
+   * for both (service role, except `list`).
+   */
+  readonly sandboxes: AiSandboxes;
+  /** Runs: the stream claim, lookups, steps and the approval inbox. */
+  readonly runs: AiRuns & {
+    /** Claims the chat's answer for one stream (service role). */
+    claim(chatId: string, streamId: string, options?: {
+      readonly model?: string;
+      readonly messageId?: string;
+      readonly engine?: string;
+      /** The durable engine's own run id, such as a Workflow SDK run. */
+      readonly externalRunId?: string;
+    }): AsyncResult<AiStreamClaim>;
+    release(chatId: string, streamId: string, options?: AiRunRelease): AsyncResult<boolean>;
+    /** Asks the running answer to stop; `undefined` when none runs. */
+    stop(chatId: string): AsyncResult<{
+      readonly streamId: string;
+      readonly runId: string;
+    } | undefined>;
+    /** Writes the gateway's cost for a generation, once it is known. */
+    setCost(generationId: string, costMicroUsd: number, usage?: Readonly<Record<string, unknown>>): AsyncResult<boolean>;
+  };
+  readonly approvals: {
+    request(chatId: string, request: AiToolApprovalRequest): AsyncResult<AiToolApproval>;
+    decide(approvalId: string, approved: boolean, reason?: string): AsyncResult<AiToolApproval>;
+    list(chatId: string, approvalIds?: readonly string[]): AsyncResult<readonly AiToolApproval[]>;
+    /** Sets a tool's policy for a tenant (`ai_chat.admin`); `null` removes it. */
+    setPolicy(organizationId: string, tool: string, policy: AiToolPolicy | null): AsyncResult<AiToolPolicy | undefined>;
+    policies(organizationId: string): AsyncResult<Readonly<Record<string, AiToolPolicy>>>;
+  };
+  readonly inputs: {
+    open(chatId: string, request: AiPendingInputRequest): AsyncResult<AiPendingInput>;
+    answer(inputId: string, answer: unknown): AsyncResult<AiPendingInput>;
+  };
+  readonly feedback: {
+    rate(chatId: string, messageId: string, rating: -1 | 0 | 1, options?: {
+      readonly reason?: string;
+      readonly comment?: string;
+    }): AsyncResult<AiFeedback>;
+  };
+  readonly shares: {
+    create(chatId: string, leafId?: string): AsyncResult<AiShareLink>;
+    revoke(shareId: string): AsyncResult<boolean>;
+    list(chatId: string): AsyncResult<readonly AiChatShare[]>;
+    /** Reads a shared chat by its token; anyone with the token may. */
+    get(token: string): AsyncResult<SharedAiChat>;
+  };
+  readonly models: {
+    /** The enabled models the tenant's plans allow. */
+    allowed(organizationId?: string | null): AsyncResult<readonly AiModel[]>;
+    /** Upserts the catalog (service role); `prune` deletes the rest. */
+    upsert(models: readonly AiModelInput[], options?: {
+      readonly prune?: boolean;
+    }): AsyncResult<number>;
+  };
+  readonly moderation: {
+    record(event: AiModerationInput): AsyncResult<AiModerationEvent>;
+    list(organizationId: string, size?: number): AsyncResult<readonly AiModerationEvent[]>;
+  };
+}
+/** The topic of one chat's events (`message.saved`, `stream.started`, ...). */
+declare function aiChatTopic(chatId: string, prefix?: string): string;
+/** The topic that tells a user their chat list changed. */
+declare function aiChatListTopic(userId: string, prefix?: string): string;
+declare function createAiChat<S extends StandardSchemaV1 | undefined = undefined>(options: AiChatOptions<S>): AiChat<FieldsOf<S>>;
+//#endregion
+export { AiRunStep as $, AiStoredMessageStatus as A, AiSandbox as B, AiProject as C, AiSaveResult as D, AiRunStatus as E, AiUserMessageTrigger as F, AiHarnessSession as G, AiSandboxStopper as H, SharedAiChat as I, AiHarnessStatus as J, AiHarnessSessionPatch as K, aiChatListTopic as L, AiToolApproval as M, AiToolApprovalRequest as N, AiShareLink as O, AiToolPolicy as P, AiRunState as Q, aiChatTopic as R, AiPendingInputRequest as S, AiRunRelease as T, AiSandboxes as U, AiSandboxStatus as V, NewAiSandbox as W, AiRun as X, AiPendingApproval as Y, AiRunQuery as Z, AiModerationAction as _, AiChatInput as a, AiModerationStage as b, AiChatPatch as c, AiChatShare as d, AiRunStepInput as et, AiChatVisibility as f, AiModelInput as g, AiModel as h, AiChat as i, AiStreamClaim as j, AiStoredMessage as k, AiChatQuery as l, AiMessageSibling as m, AiApprovalDecision as n, AiRuns as nt, AiChatOptions as o, AiFeedback as p, AiHarnessSessions as q, AiAssistantMessageOptions as r, createHarnessSessions as rt, AiChatPage as s, AiAppendResult as t, AiRunStepStatus as tt, AiChatRecord as u, AiModerationEvent as v, AiProjectInput as w, AiPendingInput as x, AiModerationInput as y, createAiChat as z };