blink 0.1.72 → 0.1.74

package/dist/node/index.node-BBpGHHxe.d.ts

@@ -0,0 +1,460 @@
+import * as http from "http";
+import { InferToolInput, InferToolOutput, InferUIMessageChunk, StreamTextResult, Tool, ToolSet, UIMessage } from "ai";
+import * as hono_utils_http_status0 from "hono/utils/http-status";
+import * as hono_types0 from "hono/types";
+import * as hono_hono_base0 from "hono/hono-base";
+
+//#region src/agent/context.d.ts
+interface Context {
+  readonly chat: ChatContext;
+  /**
+   * Store is basic key-value storage for the agent.
+   *
+   * Commonly used for: authentication state, caching external resources, or other state.
+   */
+  readonly store: StoreContext;
+}
+interface ChatContext {
+  /**
+   * ensure gets or creates a chat by key for the agent.
+   *
+   * @param key A unique key for the chat (e.g. "github-pr-1234")
+   * @returns the gotten or created chat.
+   */
+  ensure(key: string): Promise<EnsuredChat>;
+  /**
+   * message sends a message to a chat.
+   *
+   * If the chat does not exist, an error will be thrown.
+   *
+   * @param key the key of the chat.
+   * @param message the message to send.
+   * @param options the options for the message.
+   */
+  message(key: string, message: Omit<UIMessage, "id">, options?: MessageOptions): Promise<void>;
+}
+interface StoreContext {
+  /**
+   * get retrieves a value from storage.
+   *
+   * @param key the key of the value.
+   * @returns the value.
+   */
+  get(key: string): Promise<string | undefined>;
+  /**
+   * set a value.
+   *
+   * @param key the key of the value.
+   * @param value the value to set.
+   */
+  set(key: string, value: string, options?: {
+    /**
+     * ttl is the number of seconds to keep the value.
+     *
+     * If not set, the value will never expire.
+     */
+    ttl?: number;
+  }): Promise<void>;
+  /**
+   * delete a value.
+   *
+   * @param key the key of the value.
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * list all values by prefix.
+   *
+   * @param prefix the prefix of the keys.
+   * @returns the values.
+   */
+  list(prefix?: string, options?: {
+    /**
+     * limit is the maximum number of values to return.
+     *
+     * Defaults to 100. Limit is 1000.
+     */
+    limit?: number;
+    /**
+     * cursor is the cursor to start from.
+     *
+     * If not set, the list will start from the beginning.
+     */
+    cursor?: string;
+  }): Promise<{
+    entries: Array<{
+      key: string;
+      ttl?: number;
+    }>;
+    cursor?: string;
+  }>;
+}
+//#endregion
+//#region src/agent/internal/types.d.ts
+type Promisable<T> = T | Promise<T>;
+//#endregion
+//#region src/agent/chat.d.ts
+interface Chat {
+  readonly key: string;
+}
+interface EnsuredChat extends Chat {
+  readonly created: boolean;
+}
+type ChatBehavior = "enqueue" | "interrupt" | "append";
+interface MessageOptions {
+  /**
+   * behavior of the chat when sending this message.
+   *
+   * - "enqueue" will add messages to the chat and start the chat eventually.
+   * - "interrupt" will interrupt the chat if running and send messages.
+   * - "append" will add messages to the chat.
+   */
+  readonly behavior?: ChatBehavior;
+  /**
+   * createdAt is the timestamp of the message.
+   *
+   * If not set, the message will be created at the current time.
+   *
+   * Use this to handle incoming messages displaying at the
+   * timestamp of their origin (e.g. a comment from GitHub).
+   */
+  readonly createdAt?: Date;
+}
+interface ChatEvent<MESSAGE extends UIMessage> {
+  readonly key: string;
+  readonly messages: MESSAGE[];
+  readonly abortSignal?: AbortSignal;
+  readonly context: Context;
+}
+type ChatResponse<MESSAGE extends UIMessage> = {
+  toUIMessageStream: StreamTextResult<any, any>["toUIMessageStream"];
+} | Response | ReadableStream<InferUIMessageChunk<MESSAGE>> | void;
+type ChatHandler<MESSAGE extends UIMessage> = (event: ChatEvent<MESSAGE>) => Promisable<ChatResponse<MESSAGE>>;
+//#endregion
+//#region src/agent/ui.d.ts
+type UIOptionIcon = `lucide:${string}` | `simple-icons:${string}`;
+type UIOptionSelectValue<ID extends string = string> = {
+  readonly id: ID;
+  readonly label: string;
+  /**
+   * description will provide additional context to the user in the UI.
+   */
+  readonly description?: string | Array<{
+    readonly text: string;
+    readonly color?: "primary" | "muted" | "warning";
+  }>;
+  /**
+   * icon is a slug of a Lucide or SimpleIcons icon.
+   * This will only be rendered in a web-based UI.
+   *
+   * Find icons:
+   * - https://simpleicons.org/
+   * - https://lucide.dev/icons/
+   */
+  readonly icon?: UIOptionIcon;
+};
+type UIOptionSelect<Values extends readonly UIOptionSelectValue[] = readonly UIOptionSelectValue[]> = {
+  readonly type: "select";
+  /**
+   * label indicates the purpose of the option.
+   * If omitted, it will not be displayed in the UI.
+   */
+  readonly label?: string;
+  /**
+   * icon is a slug of a Lucide or SimpleIcons icon.
+   * This will only be rendered in a web-based UI.
+   *
+   * Find icons:
+   * - https://simpleicons.org/
+   * - https://lucide.dev/icons/
+   */
+  readonly icon?: UIOptionIcon;
+  /**
+   * defaultValue is the default value for the option.
+   * If omitted, the option will not be selected by default.
+   */
+  readonly defaultValue: Values[number]["id"];
+  readonly values: Values;
+};
+type UIOptions = Record<string, string>;
+type WithUIOptions<OPTIONS extends UIOptions, MESSAGE extends UIMessage = UIMessage> = MESSAGE & {
+  readonly role: "user";
+  readonly metadata: MESSAGE["metadata"] & {
+    readonly options: OPTIONS;
+  };
+};
+type ExtractUIOptions<M> = M extends WithUIOptions<infer O> ? O : UIOptions;
+type UIOptionsSchema<OPTIONS extends UIOptions = UIOptions> = { [K in keyof OPTIONS]: UIOptionSelect<Array<UIOptionSelectValue<OPTIONS[K]>>> };
+interface UIEvent<MESSAGE extends UIMessage> {
+  readonly selectedOptions?: ExtractUIOptions<MESSAGE>;
+}
+type UIHandler<MESSAGE extends UIMessage> = (event: UIEvent<MESSAGE>) => Promisable<UIOptionsSchema<ExtractUIOptions<MESSAGE>> | void>;
+/**
+ * lastUIOptions finds the last user message with options.
+ * Options are stored in message metadata to preserve the history
+ * of changing options.
+ *
+ * @param messages - The messages to search.
+ * @returns The last user message with options, or undefined if no such message exists.
+ */
+declare function lastUIOptions<MESSAGE extends UIMessage>(messages: MESSAGE[]): ExtractUIOptions<MESSAGE> | undefined;
+//#endregion
+//#region src/agent/agent.d.ts
+interface ServeOptions {
+  /**
+   * apiUrl is the URL of the Blink API server which the agent
+   * uses to create chats, send messages, and manage storage.
+   *
+   * Defaults `BLINK_API_URL`. If not set, the agent will warn
+   * and throw an error if a request is attempted to the API.
+   */
+  apiUrl?: string;
+  /**
+   * host is the host to serve the agent on.
+   *
+   * Defaults to `HOST` or `127.0.0.1.
+   */
+  host?: string;
+  /**
+   * port is the port to serve the agent on.
+   *
+   * Defaults to `PORT` or `3000`.
+   */
+  port?: number;
+}
+type RequestHandler = (request: Request, context: Context) => Promisable<Response | void>;
+type ErrorHandler = (error: Error) => Promisable<Response | void>;
+interface Agent<MESSAGE extends UIMessage> {
+  on(event: "chat", handler: ChatHandler<MESSAGE>): Agent<MESSAGE>;
+  on(event: "ui", handler: UIHandler<MESSAGE>): Agent<MESSAGE>;
+  on(event: "request", handler: RequestHandler): Agent<MESSAGE>;
+  on(event: "error", handler: ErrorHandler): Agent<MESSAGE>;
+  serve(options?: ServeOptions): http.Server;
+}
+type OverloadedParameters<T> = T extends {
+  (...a: infer A): any;
+  (...a: infer B): any;
+  (...a: infer C): any;
+  (...a: infer D): any;
+  (...a: infer E): any;
+} ? A | B | C | D | E : never;
+type OnTuples<M extends UIMessage> = OverloadedParameters<Agent<M>["on"]>;
+type OnEvent<M extends UIMessage> = OnTuples<M>[0];
+type OnHandler<M extends UIMessage, E extends OnEvent<M>> = Extract<OnTuples<M>, [E, any]>[1];
+type Listeners<M extends UIMessage> = { [E in OnEvent<M>]: Array<OnHandler<M, E>> };
+/**
+ * agent constructs a new agent.
+ *
+ * @param options
+ * @returns
+ */
+declare function agent<MESSAGE extends UIMessage>(): Agent<MESSAGE>;
+declare const api: hono_hono_base0.HonoBase<{
+  Bindings: {
+    listeners: Listeners<any>;
+    context: Context;
+  };
+}, {
+  "*": {
+    $all: {
+      input: {};
+      output: {};
+      outputFormat: string;
+      status: hono_utils_http_status0.StatusCode;
+    };
+  };
+} | (hono_types0.MergeSchemaPath<{
+  "/chat": {
+    $post: {
+      input: {
+        json: {
+          messages: UIMessage[];
+          chat: Chat;
+        };
+      };
+      output: {};
+      outputFormat: string;
+      status: hono_utils_http_status0.StatusCode;
+    };
+  };
+} & {
+  "/capabilities": {
+    $get: {
+      input: {};
+      output: {
+        ui: boolean;
+        chat: boolean;
+        request: boolean;
+        error: boolean;
+      };
+      outputFormat: "json";
+      status: 200;
+    };
+  };
+} & {
+  "/health": {
+    $get: {
+      input: {};
+      output: "OK";
+      outputFormat: "body";
+      status: 200;
+    };
+  };
+} & {
+  "/ui": {
+    $get: {
+      input: {};
+      output: {
+        error: string;
+      };
+      outputFormat: "json";
+      status: 400;
+    } | {
+      input: {};
+      output: {
+        [x: string]: {
+          readonly type: "select";
+          readonly label?: string | undefined;
+          readonly icon?: (`lucide:${string}` | `simple-icons:${string}`) | undefined;
+          readonly defaultValue: string;
+          readonly values: {
+            readonly id: string;
+            readonly label: string;
+            readonly description?: string | {
+              readonly text: string;
+              readonly color?: "primary" | "muted" | "warning" | undefined;
+            }[] | undefined;
+            readonly icon?: (`lucide:${string}` | `simple-icons:${string}`) | undefined;
+          }[];
+        };
+      };
+      outputFormat: "json";
+      status: 200;
+    } | {
+      input: {};
+      output: {
+        error: string;
+      };
+      outputFormat: "json";
+      status: 404;
+    };
+  };
+}, "/_agent"> & {
+  "*": {
+    $all: {
+      input: {};
+      output: {};
+      outputFormat: string;
+      status: hono_utils_http_status0.StatusCode;
+    };
+  };
+}), "/">;
+//#endregion
+//#region src/agent/tools.d.ts
+/**
+ * ToolWithContext is a tool that supports the "withContext" method.
+ *
+ * @param CONTEXT The context type.
+ * @param TOOL The tool type.
+ * @returns The tool with the given context.
+ */
+type ToolWithContext<CONTEXT, TOOL extends Tool> = TOOL & {
+  withContext(context: CONTEXT): TOOL;
+};
+/**
+ * ToolWithApproval is a tool that supports the "autoApprove" method.
+ *
+ * @param TOOL The tool type.
+ * @returns The tool with the given approval.
+ */
+type ToolWithApproval<INPUT, OUTPUT> = Tool<INPUT, OUTPUT> & {
+  /**
+   * autoApprove is a function that can be used to automatically approve
+   * an approval tool call based on the input.
+   *
+   * @param input The input to the tool.
+   * @returns Whether the tool call should be approved.
+   */
+  autoApprove?: (input: INPUT) => Promise<boolean> | boolean;
+};
+type ToolSetWithApproval<TOOLS extends ToolSet> = { [K in keyof TOOLS]: ToolWithApproval<InferToolInput<TOOLS[K]>, InferToolOutput<TOOLS[K]>> };
+/**
+ * toolWithApproval is a helper for inferring the execute and autoApprove
+ * arguments of a tool.
+ *
+ * @param tool The tool to wrap.
+ * @returns The wrapped tool.
+ */
+declare function toolWithApproval<INPUT, OUTPUT>(tool: ToolWithApproval<INPUT, OUTPUT>): ToolWithApproval<INPUT, OUTPUT>;
+/**
+ * Tools are helpers for managing tools.
+ */
+declare const tools: Readonly<{
+  /**
+   * withContext adds context to a set of tools that supports the "withContext" method.
+   *
+   * @param context
+   * @param tools
+   * @returns
+   */
+  withContext<const TOOLS extends ToolsWithContext>(tools: TOOLS, context: ContextFromTools<TOOLS>): { [K in keyof TOOLS]: Tool };
+  /**
+   * @internal
+   * @deprecated Use withContext instead - it's the same thing.
+   */
+  with<const TOOLS extends ToolsWithContext>(tools: TOOLS, context: ContextFromTools<TOOLS>): { [K in keyof TOOLS]: Tool };
+  /**
+   * withApproval ensures a set of tools need explicit user approval
+   * before they are executed.
+   *
+   * This works by replacing the execution of all provided tools with
+   * special output that interfaces must handle.
+   *
+   * On approval, the tool will be executed with the verbatim input.
+   *
+   * @returns Tools that should be sent in `streamText`.
+   */
+  withApproval<TOOLSET extends ToolSet, TOOLS extends ToolSetWithApproval<TOOLSET>, MESSAGE extends UIMessage>(options: {
+    messages: MESSAGE[];
+    tools: TOOLS;
+    abortSignal?: AbortSignal;
+  }): Promise<TOOLS>;
+  /**
+   * prefix adds a prefix to all the tools in a tool set.
+   *
+   * @param tools The tool set to prefix.
+   * @param prefix The prefix to add to the tools.
+   * @returns The prefixed tool set.
+   */
+  prefix(tools: ToolSet, prefix: string): ToolSet;
+}>;
+type ToolsWithContext = Record<string, Tool & {
+  withContext(context: unknown): Tool;
+}>;
+type ContextFromTools<TOOLS extends ToolsWithContext> = TOOLS[keyof TOOLS] extends {
+  withContext(context: infer C): any;
+} ? C : never;
+/**
+ * ToolApprovalOutput is the output of a tool that requires approval.
+ *
+ * This should be consumed by the UI to display an approval prompt.
+ */
+interface ToolApprovalOutput {
+  type: "tool-approval";
+  outcome: "pending" | "approved" | "rejected";
+  reason?: string;
+}
+/**
+ * isToolApprovalOutput checks if an output is a tool approval output.
+ */
+declare function isToolApprovalOutput(output: unknown): output is ToolApprovalOutput;
+//#endregion
+//#region src/agent/index.browser.d.ts
+type StreamResponseFormat = "ui-message" | "openai-chat" | "openai-response" | "anthropic" | "google" | "xai";
+/**
+ * StreamResponseFormatHeader indicates to a client the stream response
+ * format that the agent is using.
+ */
+declare const StreamResponseFormatHeader = "x-blink-stream-response-format";
+declare function withResponseFormat(response: Response, format: StreamResponseFormat): Response;
+//#endregion
+export { Agent, Chat, ChatBehavior, ChatContext, ChatEvent, ChatHandler, ChatResponse, Context, ContextFromTools, EnsuredChat, ErrorHandler, ExtractUIOptions, MessageOptions, RequestHandler, ServeOptions, StoreContext, StreamResponseFormat, StreamResponseFormatHeader, ToolApprovalOutput, ToolSetWithApproval, ToolWithApproval, ToolWithContext, UIEvent, UIHandler, UIOptionSelect, UIOptionSelectValue, UIOptions, UIOptionsSchema, WithUIOptions, agent, api, isToolApprovalOutput, lastUIOptions, toolWithApproval, tools, withResponseFormat };