better-supabase 0.5.0 → 0.6.0

package/dist/ai-sdk/workflow/index.d.ts

@@ -0,0 +1,249 @@
+import { a as AiMessage } from "../../message-CfDoR0Y6.js";
+import { A as AiStoredMessageStatus, E as AiRunStatus, i as AiChat } from "../../ai-chat-7amvXjmQ.js";
+import { o as StreamStore } from "../../store-CGjgWu5n.js";
+import { c as GatewayOptions, i as CostBackfillPayload, t as AiUsage } from "../../gateway-C1ssRHnf.js";
+import { n as AssistantContext, t as Assistant } from "../../assistant-DwdpDH1q.js";
+import { a as ModelSource } from "../../messages-DYP0sUTe.js";
+import { LanguageModelUsage, ModelMessage } from "ai";
+import { ModelCallStreamPart } from "@ai-sdk/workflow";
+//#region src/ai-sdk/workflow/turn.d.ts
+/** What `durableChat` starts the turn's workflow with. Every field is serializable. */
+interface DurableTurnInput {
+  readonly chatId: string;
+  readonly organizationId: string;
+  readonly userId: string;
+  readonly model: string;
+  /** The answer's id: every save of the turn updates this message. */
+  readonly messageId: string;
+  /** The stored user message the answer is saved under. */
+  readonly parentId: string;
+  /** The `ai_runs` row of the first segment, claimed before the start. */
+  readonly runId: string;
+  /** The first segment's stream: the World stream namespace and the stream store id. */
+  readonly streamId: string;
+  readonly messages: ModelMessage[];
+  readonly providerOptions: {
+    readonly gateway: GatewayOptions;
+  };
+}
+/** The hook payload that continues a turn once its approvals are decided. */
+interface DurableResume {
+  /** The next segment's stream, claimed by the caller. */
+  readonly streamId: string;
+  /** The next segment's `ai_runs` row. */
+  readonly runId: string;
+}
+/** The stop hook's payload. */
+interface DurableStop {
+  readonly reason?: string;
+}
+/** What the agent function gets for one segment. */
+interface DurableAgentArgs {
+  readonly chatId: string;
+  /** The segment's `ai_runs` row, for progress in `ai_run_steps`. */
+  readonly runId: string;
+  readonly messages: ModelMessage[];
+  /** The segment's World stream: pass it to `agent.stream({ writable })`. */
+  readonly writable: WritableStream<ModelCallStreamPart>;
+  readonly abortSignal: AbortSignal;
+  readonly model: string;
+  readonly providerOptions: {
+    readonly gateway: GatewayOptions;
+  };
+}
+/** The part of a `WorkflowAgent.stream` result the turn reads. */
+interface DurableAgentResult {
+  readonly messages: ModelMessage[];
+  readonly steps: readonly {
+    readonly sources?: readonly (ModelSource & {
+      readonly type?: string;
+    })[];
+    readonly providerMetadata?: unknown;
+  }[];
+  readonly totalUsage?: Partial<LanguageModelUsage>;
+}
+/** An approval the agent asked for, to record in `ai_tool_approvals`. */
+interface DurableApprovalRequest {
+  readonly approvalId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly input: unknown;
+  readonly signature?: string;
+}
+/** A decided approval, read back from the database. */
+interface DurableDecision {
+  readonly approvalId: string;
+  readonly approved: boolean;
+  readonly reason?: string;
+}
+interface DurableSaveInput {
+  readonly chatId: string;
+  readonly message: AiMessage;
+  readonly parentId: string;
+  readonly model: string;
+  readonly runId: string;
+  readonly status: AiStoredMessageStatus;
+}
+interface DurableApprovalsInput {
+  readonly chatId: string;
+  readonly runId: string;
+  readonly messageId: string;
+  readonly requests: readonly DurableApprovalRequest[];
+}
+interface DurableDecisionsInput {
+  readonly chatId: string;
+  readonly approvalIds: readonly string[];
+}
+interface DurableReleaseInput {
+  readonly chatId: string;
+  readonly streamId: string;
+  readonly organizationId: string;
+  readonly status: AiRunStatus;
+  readonly usage?: AiUsage;
+  readonly error?: string;
+}
+interface DurableStepTypes {
+  readonly save: {
+    readonly input: DurableSaveInput;
+    readonly output: void;
+  };
+  readonly approvals: {
+    readonly input: DurableApprovalsInput;
+    readonly output: void;
+  };
+  readonly decisions: {
+    readonly input: DurableDecisionsInput;
+    readonly output: DurableDecision[];
+  };
+  readonly release: {
+    readonly input: DurableReleaseInput;
+    readonly output: void;
+  };
+}
+type DurableStepName = keyof DurableStepTypes;
+type DurableStepInput<K extends DurableStepName> = DurableStepTypes[K]["input"];
+type DurableStepOutput<K extends DurableStepName> = DurableStepTypes[K]["output"];
+/** The database work of a turn (`durableSteps`), each run as a step. */
+type DurableStepCalls = { readonly [K in DurableStepName]: (input: DurableStepInput<K>) => Promise<DurableStepOutput<K>>; };
+/**
+ * The app's one `"use step"` function: `(name, input) =>
+ * runDurableStep(serviceChats(), name, input)`.
+ */
+type DurableStep = <K extends DurableStepName>(name: K, input: DurableStepInput<K>) => Promise<DurableStepOutput<K>>;
+/** A hook as `createHook` returns it: awaited once, or iterated for every payload. */
+type DurableHook<T> = PromiseLike<T> & AsyncIterable<T>;
+/** What `durableTurn` runs on; the workflow passes the Workflow SDK's functions. */
+interface DurableTurnDeps {
+  /** `getWorkflowMetadata().workflowRunId`. */
+  readonly runId: string;
+  /** `createHook`. */
+  readonly createHook: <T>(options: {
+    readonly token: string;
+  }) => DurableHook<T>;
+  /** `getWritable`. */
+  readonly getWritable: (options: {
+    readonly namespace: string;
+  }) => WritableStream<ModelCallStreamPart>;
+  /** Runs the agent for one segment: `(args) => agent.stream(args)`. */
+  readonly agent: (args: DurableAgentArgs) => Promise<DurableAgentResult>;
+  readonly step: DurableStep;
+}
+interface DurableTurnResult {
+  readonly status: AiRunStatus;
+  readonly messageId: string;
+  /** How many agent passes the turn took: one more for each wait on approvals. */
+  readonly segments: number;
+}
+/** The token of the hook that stops a durable turn. */
+export declare function durableStopToken(workflowRunId: string): string;
+/** The token of the hook that continues a turn after its approvals. */
+export declare function durableTurnToken(workflowRunId: string): string;
+/**
+ * One durable answer, inside a `"use workflow"` function. Each pass of the
+ * agent writes one segment: a World stream namespace, claimed in `ai_runs`.
+ * The answer is saved after each pass under `input.messageId`. When the
+ * agent asks for approvals, they go to `ai_tool_approvals`, the segment is
+ * released and the turn waits on its hook (`durableTurnToken`) for as long
+ * as the decisions take; it reads them back from the database rather than
+ * from the hook payload. The stop hook (`durableStopToken`) aborts it.
+ */
+export declare function durableTurn(input: DurableTurnInput, deps: DurableTurnDeps): Promise<DurableTurnResult>;
+//#endregion
+//#region src/ai-sdk/workflow/server.d.ts
+/** Who asks, for one request. */
+type DurableChatContext = AssistantContext;
+interface DurableChatOptions {
+  /** The assistant whose `prepare` checks and stores the user's turn. */
+  readonly assistant: Pick<Assistant, "prepare">;
+  /** The turn's `"use workflow"` function, which calls `durableTurn`. */
+  readonly workflow: (input: DurableTurnInput) => Promise<unknown>;
+  /** Keeps a copy of each segment the client reads, for when the World's stream is unavailable. */
+  readonly streams: StreamStore;
+  /** What the copy is kept for: seconds or a Postgres interval. Defaults to one day. */
+  readonly streamTtl?: number | string;
+  /** Makes message and stream ids. Defaults to `crypto.randomUUID()`. */
+  readonly generateId?: () => string;
+}
+/** A decision the client or an approval inbox sends. */
+interface DurableApprovalDecision {
+  readonly approvalId: string;
+  readonly approved: boolean;
+  readonly reason?: string;
+}
+interface DurableChat {
+  /**
+   * The POST route. A new user message starts the turn's workflow; a body
+   * with `approvals` decides them and continues the waiting turn. Both
+   * stream the segment (SSE) with the `x-workflow-run-id` header.
+   */
+  respond(request: Request, context: DurableChatContext): Promise<Response>;
+  /**
+   * The reconnect route (`GET /api/chat/:id/stream?startIndex=`): the chat's
+   * running segment, or its last one, from UI chunk `startIndex`. The
+   * stream store answers when the World's stream can't be read; 204 when
+   * the chat has no durable run.
+   */
+  resume(chatId: string, context: DurableChatContext, options?: {
+    readonly startIndex?: number;
+    readonly signal?: AbortSignal;
+  }): Promise<Response>;
+  /** Stops the running segment through the turn's stop hook, or cancels the run when the hook is gone. */
+  stop(chatId: string, context: DurableChatContext): Promise<Response>;
+  /**
+   * Decides approvals from outside the chat, such as an approval inbox, and
+   * continues the turn once none of its approvals is pending. Answers
+   * `{ continued, streamId }` as JSON.
+   */
+  decide(chatId: string, decisions: readonly DurableApprovalDecision[], context: DurableChatContext): Promise<Response>;
+}
+/** The response header that names the workflow run. */
+export declare const WORKFLOW_RUN_ID_HEADER = "x-workflow-run-id";
+/**
+ * Durable chat routes on the Workflow SDK: each turn is a workflow run
+ * (`durableTurn`), so an answer outlives the request, a reload replays it
+ * and an approval can wait for hours. The chat's runs stay in `ai_runs`
+ * with the workflow run id next to them.
+ */
+export declare function durableChat(options: DurableChatOptions): DurableChat;
+//#endregion
+//#region src/ai-sdk/workflow/steps.d.ts
+interface DurableStepOptions {
+  /** Called with the cost backfill payload when the gateway hasn't reported a cost yet. */
+  readonly enqueueCostBackfill?: (payload: CostBackfillPayload) => Promise<unknown>;
+}
+/**
+ * Saves a turn's answer (service role) with its AI SDK form next to the
+ * canonical one. The message id is the idempotency key: a retried step, or
+ * the save after the next agent pass, updates the same message.
+ */
+export declare function saveMessagesStep(chats: AiChat, input: DurableSaveInput): Promise<void>;
+/** A durable turn's database steps on a chat block's service transport. */
+export declare function durableSteps(chats: AiChat, options?: DurableStepOptions): DurableStepCalls;
+/**
+ * Runs one of a durable turn's database steps. Call it from the app's one
+ * `"use step"` function, so the Workflow SDK records and retries each call;
+ * a database error throws, which retries the step.
+ */
+export declare function runDurableStep<K extends DurableStepName>(chats: AiChat, name: K, input: DurableStepInput<K>, options?: DurableStepOptions): Promise<DurableStepOutput<K>>;
+//#endregion
+export type { DurableAgentArgs, DurableAgentResult, DurableApprovalDecision, DurableApprovalRequest, DurableApprovalsInput, DurableChat, DurableChatContext, DurableChatOptions, DurableDecision, DurableDecisionsInput, DurableHook, DurableReleaseInput, DurableResume, DurableSaveInput, DurableStep, DurableStepCalls, DurableStepInput, DurableStepName, DurableStepOptions, DurableStepOutput, DurableStop, DurableTurnDeps, DurableTurnInput, DurableTurnResult };