@teamkeel/functions-runtime 0.458.0 → 0.460.0

package/dist/index.d.cts

@@ -2,6 +2,49 @@ import * as kysely from 'kysely';
 import { Kysely } from 'kysely';
 export { default as KSUID } from 'ksuid';
 import * as opentelemetry from '@opentelemetry/api';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { LanguageModel } from 'ai';
+export { z } from 'zod';
+
+interface RecipientUser {
+    id: string;
+    email?: string | null;
+}
+interface RecipientIdentity {
+    id: string;
+    email?: string | null;
+}
+interface EmailActionButton {
+    label: string;
+    url: string;
+}
+interface StructuredEmailContent {
+    title?: string;
+    body: string;
+    actions?: EmailActionButton[];
+}
+type EmailContent = string | StructuredEmailContent;
+interface EmailRecipientGroup {
+    emails?: string | string[];
+    users?: string | RecipientUser | Array<string | RecipientUser>;
+    identities?: string | RecipientIdentity | Array<string | RecipientIdentity>;
+    teams?: string | string[];
+}
+interface EmailRecipients {
+    to: EmailRecipientGroup;
+    cc?: EmailRecipientGroup;
+    bcc?: EmailRecipientGroup;
+}
+interface EmailInput {
+    recipients: EmailRecipients;
+    subject: string;
+    content: EmailContent;
+}
+
+interface NotifyApi {
+    email(input: EmailInput): Promise<string>;
+}
+declare function createNotifier(): NotifyApi;
 
 declare namespace ErrorPresets {
     export { NotFoundError$1 as NotFound };
@@ -166,13 +209,14 @@ declare class ModelAPI {
      * @param {Function} _ Used to be a function that returns the default values for a row in this table. No longer used.
      * @param {TableConfigMap} tableConfigMap
      */
-    constructor(tableName: string, _: Function, tableConfigMap?: TableConfigMap);
+    constructor(tableName: string, _: Function, tableConfigMap?: TableConfigMap, fileFieldsMap?: {});
     _tableName: string;
     _tableConfigMap: {
         [x: string]: {
             [x: string]: RelationshipConfig;
         };
     };
+    _fileFields: any;
     _modelName: any;
     create(values: any): Promise<any>;
     findOne(where?: {}): Promise<any>;
@@ -180,6 +224,8 @@ declare class ModelAPI {
     update(where: any, values: any): Promise<any>;
     delete(where: any): Promise<any>;
     where(where: any): QueryBuilder;
+    _selectExistingFileValues(where: any, fileColumns: any): Promise<{}[]>;
+    _deferReplacedFiles(existingRows: any, fileColumns: any, newRow: any): void;
 }
 
 /**
@@ -350,6 +396,28 @@ declare class FlowsAPI {
      * @returns {Promise<FlowRun>} The created flow run
      */
     start(inputs?: Object): Promise<FlowRun$1>;
+    /**
+     * Mints a signed link that lets an external, unauthenticated actor execute this flow. The flow
+     * must be declared with @externalAccess. Each time the link is opened a fresh flow run is created;
+     * a reusable link can be opened many times, otherwise it permits exactly one run.
+     * @param {Object} [options] Signed link options
+     * @param {Object} [options.inputs] Default inputs applied to every run created from the link
+     * @param {Date} [options.expiresAt] When the link stops being valid
+     * @param {boolean} [options.reusable] Whether the link can be opened more than once
+     * @returns {Promise<{url: string, expiresAt: Date|null, flow: {name: string, runId: string|null}}>} The signed link
+     */
+    signedLink(options?: {
+        inputs?: Object | undefined;
+        expiresAt?: Date | undefined;
+        reusable?: boolean | undefined;
+    }): Promise<{
+        url: string;
+        expiresAt: Date | null;
+        flow: {
+            name: string;
+            runId: string | null;
+        };
+    }>;
     /**
      * Gets a flow run by ID.
      * @param {string} runId The flow run ID
@@ -424,6 +492,10 @@ declare class FlowRun$1 {
     cancel(): Promise<FlowRun$1>;
 }
 
+declare function createIntegrationServer(name: any, identity: any): {
+    do: (request: any) => Promise<unknown>;
+};
+
 interface RequestHeadersMap {
     [key: string]: string;
 }
@@ -539,7 +611,10 @@ declare class File extends InlineFile {
     get isPublic(): boolean;
     read(): Promise<Buffer>;
     store(expires?: Date | null): Promise<File>;
-    getPresignedUrl(): Promise<URL>;
+    getPresignedUrl(options?: {
+        contentDisposition?: "inline" | "attachment";
+        filename?: string;
+    }): Promise<URL>;
     getPresignedUploadUrl(): Promise<URL>;
     toDbRecord(): FileDbRecord;
     toJSON(): FileDbRecord;
@@ -1335,6 +1410,75 @@ declare class NonRetriableError extends Error {
     constructor(message?: string);
 }
 
+/** A JSON-serializable message in an agent conversation. Library-neutral —
+ * engine adapters map this to their provider's shape. */
+type AgentMessage = {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string;
+    toolCalls?: ToolCallRequest[];
+} | {
+    role: "tool";
+    toolCallId: string;
+    toolName: string;
+    result: string;
+};
+interface ToolCallRequest {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** A tool as presented to the model. `parameters` is a JSON Schema object. */
+interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface TurnRequest {
+    model: string;
+    system?: string;
+    messages: AgentMessage[];
+    tools?: ToolSpec[];
+    /** Force the model to call a specific tool (used for structured output). */
+    toolChoice?: "auto" | {
+        name: string;
+    };
+}
+interface TurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+interface TurnResult {
+    /** Empty string when the model only returned tool calls. */
+    text: string;
+    toolCalls: ToolCallRequest[];
+    usage: TurnUsage;
+    stopReason: "end_turn" | "tool_calls";
+}
+/** The turn primitive: ONE model call, no looping, no tool execution.
+ * The flows replay engine owns the loop; adapters must never auto-execute tools. */
+interface TurnEngine {
+    turn(req: TurnRequest): Promise<TurnResult>;
+}
+type ScriptEntry = TurnResult | ((req: TurnRequest) => TurnResult);
+/** Deterministic fake engine for tests. Returns scripted results in order. */
+declare class ScriptedEngine implements TurnEngine {
+    private readonly script;
+    private _requests;
+    private index;
+    constructor(script: ScriptEntry[]);
+    get requests(): readonly TurnRequest[];
+    turn(req: TurnRequest): Promise<TurnResult>;
+}
+/** Helpers for building scripted turns concisely in tests. */
+declare const scriptedTurn: {
+    text(text: string): TurnResult;
+    /** Auto-generated ids increment per process — pass an explicit `id` when asserting on ids in tests. */
+    toolCall(name: string, args: Record<string, unknown>, id?: string): TurnResult;
+};
+
 declare const enum STEP_STATUS {
     NEW = "NEW",
     RUNNING = "RUNNING",
@@ -1374,6 +1518,22 @@ interface FlowContext<C extends FlowConfig, E, S, Id, I, H extends NullableHardw
     secrets: S;
     identity: Id;
     trace: TraceAPI;
+    module(name: string): {
+        secret(key: string): string;
+        server: {
+            do(request: {
+                method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+                path: string;
+                query?: Record<string, string | string[]>;
+                headers?: Record<string, string>;
+                body?: unknown;
+            }): Promise<{
+                status: number;
+                headers: Record<string, string[]>;
+                body: unknown;
+            }>;
+        };
+    };
 }
 type NullableHardware = Hardware | undefined;
 type Hardware = {
@@ -1382,9 +1542,13 @@ type Hardware = {
 interface Printer {
     name: string;
 }
-type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
-    [key: string]: JsonSerializable;
+type JsonValue$1<T> = T extends string | number | boolean | null ? T : T extends (...args: any[]) => any ? never : T extends (infer E)[] ? JsonValue$1<E>[] : T extends object ? keyof T extends never ? never : {
+    [K in keyof T]: JsonValue$1<T[K]>;
+} : never;
+type Serializable<T> = string | number | boolean | null | void | {
+    [K in keyof T]: JsonValue$1<T[K]>;
 };
+type StepReturn<R> = [R] extends [JsonValue$1<R> | void] ? R : JsonValue$1<R>;
 type StepOptions<C extends FlowConfig> = {
     stage?: ExtractStageKeys<C>;
     /** Number of times to retry the step after it fails. Defaults to 4. */
@@ -1397,18 +1561,18 @@ type StepOptions<C extends FlowConfig> = {
     onFailure?: () => Promise<void> | void;
 };
 type Step<C extends FlowConfig> = {
-    <R extends JsonSerializable | void>(
+    <R extends Serializable<R>>(
     /** The unique name of this step. */
     name: string, 
     /** Configuration options for the step. */
     options: StepOptions<C>, 
     /** The step function to execute. */
-    fn: StepFunction<C, R>): Promise<R>;
-    <R extends JsonSerializable | void>(
+    fn: StepFunction<C, StepReturn<R>>): Promise<R>;
+    <R extends Serializable<R>>(
     /** The unique name of this step. */
     name: string, 
     /** The step function to execute. */
-    fn: StepFunction<C, R>): Promise<R>;
+    fn: StepFunction<C, StepReturn<R>>): Promise<R>;
 };
 type StepArgs<C extends FlowConfig> = {
     attempt: number;
@@ -1446,17 +1610,147 @@ type StageConfigObject = {
     initiallyHidden?: boolean;
 };
 type StageConfig = string | StageConfigObject;
+declare function insertNewStep(db: Kysely<any>, runId: string, name: string, stage: string | undefined): Promise<void>;
 declare function createFlowContext<C extends FlowConfig, E, S, Id, I, H extends NullableHardware>(runId: string, data: any, action: string | null, callback: string | null, element: string | null, spanId: string, ctx: {
     env: E;
     now: () => Date;
     secrets: S;
     identity: Id;
     trace: TraceAPI;
+    engine?: TurnEngine;
+    module: FlowContext<C, E, S, Id, I, H>["module"];
 }): FlowContext<C, E, S, Id, I, H>;
 
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+interface ToolDefinition<P = any> {
+    /** snake_case identifier the model sees. */
+    name: string;
+    description: string;
+    /** Extra guidance on when/how to use the tool, appended to the description. */
+    usage?: string;
+    /** Standard Schema (Zod v4) for the tool's arguments. */
+    parameters: StandardSchemaV1<unknown, P>;
+    /** true = always gate behind a UI approval step; predicate = gate when it returns true. */
+    approval?: boolean | ((args: P) => boolean);
+    execute: (args: P) => Promise<JsonValue | void>;
+}
+declare function defineTool<P>(config: ToolDefinition<P>): Readonly<ToolDefinition<P>>;
+
+interface AgentConfig<I = any, R = any> {
+    /** Unique agent name; used to namespace checkpointed steps. */
+    name: string;
+    model: string;
+    instructions: string;
+    tools?: ReadonlyArray<ToolDefinition>;
+    /** Sealed prompt template — callers pass inputs, never a raw prompt. */
+    prompt: (args: {
+        inputs: I;
+        context: Record<string, unknown>;
+    }) => string;
+    /** Result contract. Omit for free-text agents (run resolves to final assistant text). */
+    result?: StandardSchemaV1<unknown, R>;
+    /** Max LLM turns before the run fails. Default 10. */
+    maxTurns?: number;
+    /**
+     * Pre-run hook; the object it returns merges into the prompt template context.
+     * Like the agent body, this runs again on every orchestrator replay, so any
+     * side effects must be wrapped in `ctx.step(...)` to stay idempotent (see the
+     * `beforeRun` test, which loads its value through a checkpointed step).
+     */
+    beforeRun?: (ctx: any, args: {
+        inputs: I;
+    }) => Promise<Record<string, unknown> | void>;
+    /**
+     * Post-run hook, called with the final result once the agent completes. Like
+     * `beforeRun` it runs again on every orchestrator replay, so any side effects
+     * (writes, notifications) must be wrapped in `ctx.step(...)` to stay
+     * idempotent — an un-checkpointed write here repeats on each replay.
+     */
+    afterRun?: (ctx: any, result: R | string) => Promise<void>;
+}
+interface Agent<I = any, R = any> {
+    readonly name: string;
+    readonly config: AgentConfig<I, R>;
+    run(ctx: any, inputs: I): Promise<any>;
+}
+declare function defineAgent<I = any, R = any>(config: AgentConfig<I, R>): Agent<I, R>;
+
+interface AiSdkEngineOptions {
+    /** Standard API key (sk-ant-api...), sent as x-api-key. */
+    apiKey?: string;
+    /** Bearer token (e.g. sk-ant-oat... OAuth tokens, or the future platform
+     * LLM proxy's scoped tokens), sent as Authorization: Bearer. */
+    authToken?: string;
+    /** Override the provider base URL (future: the platform LLM proxy). */
+    baseURL?: string;
+}
+/** Reference TurnEngine over the Vercel AI SDK. One turn per call: tools are
+ * declared WITHOUT execute functions, so generateText returns tool calls
+ * without running them or looping. */
+declare class AiSdkEngine implements TurnEngine {
+    private opts;
+    constructor(opts: AiSdkEngineOptions);
+    resolveModel(model: string): LanguageModel;
+    turn(req: TurnRequest): Promise<TurnResult>;
+}
+
+type LlmOptions<R> = {
+    /** Provider-prefixed model, e.g. "anthropic/claude-sonnet-4-6". */
+    model: string;
+    prompt: string;
+    /** Optional system instructions. */
+    system?: string;
+    /** Standard Schema for the typed result. Omit for plain text. */
+    result?: StandardSchemaV1<unknown, R>;
+    /** Max wall-clock ms for the step (default 300000). */
+    timeout?: number;
+};
+/**
+ * Run one typed LLM call as a single checkpointed flow step. No tools, no loop:
+ * it's an ordinary step, so the result is cached on replay and retried on
+ * transient failure. Pass a `result` schema for structured output (validated
+ * with a bounded repair loop) or omit it to get the model's plain text.
+ *
+ * Takes the flow `ctx` explicitly so it can be called as a free function:
+ *
+ *   const triage = await experimental.LlmFlowStep(ctx, "classify", {
+ *     model: "anthropic/claude-haiku-4-5",
+ *     prompt: `Classify this ticket: ${body}`,
+ *     result: z.object({ category: z.enum(["billing", "bug", "other"]) }),
+ *   });
+ */
+declare function LlmFlowStep<R>(ctx: any, name: string, options: LlmOptions<R> & {
+    result: StandardSchemaV1<unknown, R>;
+}): Promise<R>;
+declare function LlmFlowStep(ctx: any, name: string, options: LlmOptions<never>): Promise<string>;
+
+type experimental_Agent<I = any, R = any> = Agent<I, R>;
+type experimental_AgentConfig<I = any, R = any> = AgentConfig<I, R>;
+type experimental_AgentMessage = AgentMessage;
+type experimental_AiSdkEngine = AiSdkEngine;
+declare const experimental_AiSdkEngine: typeof AiSdkEngine;
+declare const experimental_LlmFlowStep: typeof LlmFlowStep;
+type experimental_LlmOptions<R> = LlmOptions<R>;
+type experimental_ScriptedEngine = ScriptedEngine;
+declare const experimental_ScriptedEngine: typeof ScriptedEngine;
+type experimental_ToolDefinition<P = any> = ToolDefinition<P>;
+type experimental_TurnEngine = TurnEngine;
+type experimental_TurnRequest = TurnRequest;
+type experimental_TurnResult = TurnResult;
+declare const experimental_defineAgent: typeof defineAgent;
+declare const experimental_defineTool: typeof defineTool;
+declare const experimental_scriptedTurn: typeof scriptedTurn;
+declare namespace experimental {
+  export { type experimental_Agent as Agent, type experimental_AgentConfig as AgentConfig, type experimental_AgentMessage as AgentMessage, experimental_AiSdkEngine as AiSdkEngine, experimental_LlmFlowStep as LlmFlowStep, type experimental_LlmOptions as LlmOptions, experimental_ScriptedEngine as ScriptedEngine, type experimental_ToolDefinition as ToolDefinition, type experimental_TurnEngine as TurnEngine, type experimental_TurnRequest as TurnRequest, type experimental_TurnResult as TurnResult, experimental_defineAgent as defineAgent, experimental_defineTool as defineTool, experimental_scriptedTurn as scriptedTurn };
+}
+
 declare const createTraceAPI: typeof createTraceAPI$1;
 declare function ksuid(): string;
 
+declare const notify: NotifyApi;
+
 type IDWhereCondition = {
     equals?: string | null;
     notEquals?: string | null;
@@ -1695,5 +1989,18 @@ type FlowListResult = {
         hasNextPage: boolean;
     };
 };
+type SignedLinkOptions<Inputs = any> = {
+    inputs?: Inputs;
+    expiresAt?: Date;
+    reusable?: boolean;
+};
+type SignedLinkResult = {
+    url: string;
+    expiresAt: Date | null;
+    flow: {
+        name: string;
+        runId: string | null;
+    };
+};
 
-export { type BooleanArrayQueryWhereCondition, type BooleanArrayWhereCondition, type BooleanWhereCondition, type ContextAPI, type DateArrayQueryWhereCondition, type DateArrayWhereCondition, type DateQueryInput, type DateWhereCondition, Duration, type DurationString, type DurationWhereCondition, ErrorPresets, type Errors, type ExtractStageKeys, File, type FlowConfig, type FlowConfigAPI, type FlowContext, type FlowFunction, type FlowListOptions, type FlowListResult, type FlowRun, type FlowRunStatus, type FlowRunStep, FlowsAPI, type FuncWithConfig, type FunctionConfig, type Hardware, type IDWhereCondition, InlineFile, type ListResult, ModelAPI, NonRetriableError, type NullableHardware, type NumberArrayQueryWhereCondition, type NumberArrayWhereCondition, type NumberWhereCondition, PERMISSION_STATE, type PageInfo, type PartialPageInfo, Permissions, type Printer, type RelativeDateString, RequestHeaders, type Response, RetryBackoffExponential, RetryBackoffLinear, RetryConstant, STEP_STATUS, STEP_TYPE, Signature, type SortDirection, type Step, type StringArrayQueryWhereCondition, type StringArrayWhereCondition, type StringWhereCondition, type Task, TaskAPI, type TaskCreateOptions, type TaskFlowFunction, type TaskStatus, type TimestampQueryInput, type TraceAPI, type TraceAttributeValue, type TraceAttributes, type UI, type UIApiResponses, checkBuiltInPermissions, createFlowContext, createTraceAPI, handleFlow, handleJob, handleRequest, handleRoute, handleSubscriber, ksuid, tracing, useDatabase };
+export { type BooleanArrayQueryWhereCondition, type BooleanArrayWhereCondition, type BooleanWhereCondition, type ContextAPI, type DateArrayQueryWhereCondition, type DateArrayWhereCondition, type DateQueryInput, type DateWhereCondition, Duration, type DurationString, type DurationWhereCondition, type EmailContent, type EmailInput, type EmailRecipientGroup, type EmailRecipients, ErrorPresets, type Errors, type ExtractStageKeys, File, type FlowConfig, type FlowConfigAPI, type FlowContext, type FlowFunction, type FlowListOptions, type FlowListResult, type FlowRun, type FlowRunStatus, type FlowRunStep, FlowsAPI, type FuncWithConfig, type FunctionConfig, type Hardware, type IDWhereCondition, InlineFile, type ListResult, ModelAPI, NonRetriableError, type NotifyApi, type NullableHardware, type NumberArrayQueryWhereCondition, type NumberArrayWhereCondition, type NumberWhereCondition, PERMISSION_STATE, type PageInfo, type PartialPageInfo, Permissions, type Printer, type RecipientIdentity, type RecipientUser, type RelativeDateString, RequestHeaders, type Response, RetryBackoffExponential, RetryBackoffLinear, RetryConstant, STEP_STATUS, STEP_TYPE, Signature, type SignedLinkOptions, type SignedLinkResult, type SortDirection, type Step, type StringArrayQueryWhereCondition, type StringArrayWhereCondition, type StringWhereCondition, type Task, TaskAPI, type TaskCreateOptions, type TaskFlowFunction, type TaskStatus, type TimestampQueryInput, type TraceAPI, type TraceAttributeValue, type TraceAttributes, type UI, type UIApiResponses, checkBuiltInPermissions, createFlowContext, createIntegrationServer, createNotifier, createTraceAPI, experimental, handleFlow, handleJob, handleRequest, handleRoute, handleSubscriber, insertNewStep, ksuid, notify, tracing, useDatabase };