@byteplus-iga-pages/agent 0.0.0-stage → 1.0.3

package/dist/types/store/store.d.ts

@@ -0,0 +1,240 @@
+import { type AppendMessageItemInput } from "./append.js";
+import { type JsonObject, type JsonValue } from "./json.js";
+import { SupabaseStoreTransport } from "./supabase-transport.js";
+/** 会话信息；消息列表需通过 `store.listMessages()` 单独读取。 */
+export interface Conversation {
+    /** 会话的 ID，用于后续消息读写和会话操作；不是访问凭证。 */
+    conversationId: string;
+    /** 应用自定义的会话元数据，例如 `{ title: "新对话" }`；未设置时为 `{}`。 */
+    metadata: JsonObject;
+    /** 服务端创建时间字符串，可用 `new Date(createdAt)` 转换。 */
+    createdAt: string;
+    /** 服务端最近更新时间字符串，可用 `new Date(updatedAt)` 转换。 */
+    updatedAt: string;
+}
+/** 已保存的消息；ID、序号和时间由追加结果返回。 */
+export interface Message {
+    /** 当前项目内唯一的消息 ID，不限定为 UUID。 */
+    messageId: string;
+    /** 消息所属会话的 ID。 */
+    conversationId: string;
+    /**
+     * 会话内递增序号，以十进制字符串返回，避免大整数精度丢失。
+     * 删除后可能存在空缺；需要比较时使用 `BigInt(seq)`，不要按字符串排序。
+     */
+    seq: string;
+    /** 消息角色，如 user、assistant、system、tool 或自定义字符串；未设置时为 null。 */
+    role: string | null;
+    /** 应用自定义的消息类型；未设置时为 null。 */
+    type: string | null;
+    /** 原样保存的 JSON 消息内容；结构由应用定义，不要求包含 content、text 或 type。 */
+    payload: JsonValue;
+    /** 消息的附加信息，与会话 metadata 独立；未设置时为 `{}`。 */
+    metadata: JsonObject;
+    /** 服务端创建时间字符串，可用 `new Date(createdAt)` 转换。 */
+    createdAt: string;
+    /** 服务端最近更新时间字符串，可用 `new Date(updatedAt)` 转换。 */
+    updatedAt: string;
+}
+/** 一页查询结果；不是完整列表。 */
+export interface Page<T> {
+    /** 当前页的数据，顺序由对应列表方法决定；没有结果时为空数组。 */
+    items: T[];
+    /** 下一页游标；原样传给同一列表方法的 cursor。为 null 时没有下一页。 */
+    nextCursor: string | null;
+}
+/** 创建空会话的参数。 */
+export interface CreateConversationInput {
+    /** 会话 ID（非空字符串，UTF-8 最多 256 字节）；省略时由 SDK 生成。指定已存在的 ID 会产生 conflict。 */
+    conversationId?: string;
+    /**
+     * 初始会话元数据，必须是 JSON 对象，不能是数组或 null；对象中的 null 会作为值保存。
+     * 不支持 undefined、BigInt、函数、非有限数字、循环引用或类实例。
+     * @default {}
+     */
+    metadata?: JsonObject;
+}
+export interface ConversationRef {
+    /** 目标会话的 ID；可使用 createConversation() 返回的 conversationId。 */
+    conversationId: string;
+}
+/** 当前项目的会话分页参数；不支持用户归属或 metadata 筛选。 */
+export interface ListConversationsInput {
+    /** 上一页的 nextCursor；第一页不传，不要解析、构造或混用其他列表的游标。 */
+    cursor?: string;
+    /**
+     * 每页条数，必须是 1～100 的整数。
+     * @default 50
+     */
+    limit?: number;
+}
+/** 局部更新会话元数据；不修改会话中的消息。 */
+export interface UpdateConversationInput {
+    /** 待更新会话的 ID；会话不存在时产生 not_found。 */
+    conversationId: string;
+    /**
+     * 原子合并顶层字段，未传字段保留；顶层 null 删除对应键，例如 `{ title: null }`。
+     * 嵌套对象和数组整值替换，其中的 null 保留；不能用此方法将顶层键设为 null 值。
+     * `{}` 不修改数据或更新时间，但仍检查会话存在性；不接受 null 或非法 JSON 值。
+     */
+    metadata: JsonObject;
+}
+/** 向指定会话追加一条消息，内容字段继承自 AppendMessageItemInput。 */
+export interface AppendMessageInput extends AppendMessageItemInput {
+    /** 目标会话的 ID，必须显式提供；会话不存在时会随消息原子创建。 */
+    conversationId: string;
+}
+/** 向同一会话原子追加一批消息。 */
+export interface AppendMessagesInput {
+    /** 整批消息所属会话的 ID；会话不存在时会随消息原子创建。 */
+    conversationId: string;
+    /**
+     * 包含 1～100 条消息，批内 messageId 不能重复；结果按输入顺序返回。
+     * 整批 ID 均为新 ID 时追加；均已存在且内容和会话匹配时返回已有消息。
+     * 混合已有 ID 和新 ID，或已有消息内容不匹配时产生 conflict，整批不写入。
+     * 业务重试应显式提供并复用全部消息 ID 和内容；超过 100 条需拆成多个批次。
+     */
+    messages: AppendMessageItemInput[];
+}
+export interface MessageRef {
+    /** 当前项目内的非空消息 ID；使用追加结果的 messageId，无需同时提供会话 ID。 */
+    messageId: string;
+}
+/** 指定会话的消息分页参数。 */
+export interface ListMessagesInput {
+    /** 会话 ID（非空字符串，UTF-8 最多 256 字节）；会话不存在时返回空页。 */
+    conversationId: string;
+    /**
+     * 上一页的 nextCursor；第一页不传，后续页需保持相同的 conversationId 和 order。
+     * 游标固定本轮最大消息序号，新追加的消息需不带 cursor 重新查询。
+     */
+    cursor?: string;
+    /**
+     * 每页消息数量，必须是 1～100 的整数。
+     * @default 50
+     */
+    limit?: number;
+    /**
+     * 按消息序号排序：asc 最早在前，desc 最新在前。读取最近消息时使用 desc。
+     * @default "asc"
+     */
+    order?: "asc" | "desc";
+}
+/**
+ * 更新消息的可变字段；role、type、payload、metadata 至少提供一个。
+ * 无需修改的字段应省略，不要显式传 undefined；ID、会话、序号和时间不能修改。
+ */
+export interface UpdateMessageInput extends MessageRef {
+    /** 替换角色，接受自定义字符串；null 清空角色，省略则保留。 */
+    role?: string | null;
+    /** 替换消息类型；null 清空，省略则保留，不修改 payload.type。 */
+    type?: string | null;
+    /** 替换完整 JSON 内容，不合并对象；允许 null，省略则保留。 */
+    payload?: JsonValue;
+    /** 替换整个 JSON 元数据对象，不合并字段；`{}` 清空，省略则保留，不接受 null。 */
+    metadata?: JsonObject;
+}
+/**
+ * BytePlus IGA Pages 服务端的通用会话存储，通过 `@byteplus-iga-pages/agent/store` 导入 store 使用。
+ * 数据按当前运行时项目隔离；应用负责校验终端用户的会话访问权限。
+ * 初始化和异步调用的错误都应在 `try { await ... } catch { ... }` 中处理。
+ */
+export interface Store {
+    /**
+     * 创建空会话；省略整个参数或 conversationId 时由 SDK 生成 UUID。
+     * 已有同 ID 会话时产生 conflict，不会读取或更新它；不自动重试网络错误。
+     */
+    createConversation(input?: CreateConversationInput): Promise<Conversation>;
+    /** 读取指定 ID 的会话信息，不包含消息列表；不存在时返回 null。 */
+    getConversation(input: ConversationRef): Promise<Conversation | null>;
+    /**
+     * 分页查询当前项目的会话，默认每页 50 条。
+     * 按 updatedAt 降序，同时间按 conversationId 降序；不支持改排序或按用户筛选。
+     * 更新时间可能在分页期间变化，此列表不提供固定快照；无结果时返回空页。
+     */
+    listConversations(input?: ListConversationsInput): Promise<Page<Conversation>>;
+    /**
+     * 原子合并会话 metadata 的顶层字段，顶层 null 删除键；空对象不修改会话。
+     * 不存在时产生 not_found，不隐式创建；不自动重试网络错误。
+     */
+    updateConversation(input: UpdateConversationInput): Promise<Conversation>;
+    /**
+     * 物理删除会话及其全部通用消息；不存在或重复删除均成功。
+     * 不保留删除墓碑，旧追加请求重放可能重建会话；应等待删除结束后再复用 ID。
+     * 重建后需重新开始分页。
+     */
+    deleteConversation(input: ConversationRef): Promise<void>;
+    /**
+     * 追加一条消息；指定 ID 的会话不存在时原子创建空 metadata 的会话。
+     * 相同 messageId、会话及内容重复追加会返回仍存在的消息；内容不匹配时产生 conflict。
+     * SDK 内部重试复用消息 ID；业务重新调用时需显式提供原 ID，否则会生成新 ID。
+     */
+    appendMessage(input: AppendMessageInput): Promise<Message>;
+    /**
+     * 原子追加 1～100 条消息，必要时创建会话；返回结果与输入一一对应且顺序相同。
+     * 校验或冲突失败时整批不写入；混合已有 ID 和新 ID 会产生 conflict。
+     * 业务重试需显式复用整批消息 ID 和内容；原子性仅覆盖单次调用。
+     */
+    appendMessages(input: AppendMessagesInput): Promise<Message[]>;
+    /** 按当前项目内唯一的非空 messageId 读取消息；不存在时返回 null。 */
+    getMessage(input: MessageRef): Promise<Message | null>;
+    /**
+     * 分页读取会话消息，默认返回最早的 50 条；读取最近消息时传 order: "desc"。
+     * nextCursor 为 null 时没有下一页；会话不存在或没有消息时返回空页。
+     * 第一页固定最大消息序号，后续追加不混入本轮分页；内容更新和删除仍会影响结果。
+     */
+    listMessages(input: ListMessagesInput): Promise<Page<Message>>;
+    /**
+     * 替换传入的消息字段，未传字段保留；payload 和 metadata 均整体替换，不合并对象。
+     * 不存在时产生 not_found，没有可更新字段时产生 invalid_argument；不自动重试网络错误。
+     */
+    updateMessage(input: UpdateMessageInput): Promise<Message>;
+    /**
+     * 物理删除一条消息，保留会话，不回退计数或重排现存序号；不存在或重复删除均成功。
+     * 删除后不保留该消息的去重记录；等待删除完成后再复用 ID，追加时会分配新序号。
+     */
+    deleteMessage(input: MessageRef): Promise<void>;
+    /**
+     * 原子清空会话的全部通用消息，保留会话、metadata、创建时间和序号计数。
+     * 实际删除消息才更新会话的 updatedAt；空会话或不存在时成功，不创建会话。
+     * 网络重试会再次清空届时的消息，应等待清空结束再追加，并重新开始分页。
+     * 不清理框架专用存储。
+     */
+    clearMessages(input: ConversationRef): Promise<void>;
+}
+export interface StoreRpcNames {
+    appendMessages: string;
+    updateConversation: string;
+    deleteConversation: string;
+    deleteMessage: string;
+    clearMessages: string;
+}
+export declare const DEFAULT_STORE_RPC_NAMES: Readonly<StoreRpcNames>;
+export interface CreateStoreOptions {
+    projectId: string;
+    transport: SupabaseStoreTransport;
+    generateUuid?: () => string;
+    rpcNames?: Partial<StoreRpcNames>;
+}
+export declare class SupabaseStore implements Store {
+    private readonly projectId;
+    private readonly transport;
+    private readonly generateUuid;
+    private readonly rpcNames;
+    constructor(options: CreateStoreOptions);
+    createConversation(input?: CreateConversationInput): Promise<Conversation>;
+    getConversation(input: ConversationRef): Promise<Conversation | null>;
+    listConversations(input?: ListConversationsInput): Promise<Page<Conversation>>;
+    updateConversation(input: UpdateConversationInput): Promise<Conversation>;
+    deleteConversation(input: ConversationRef): Promise<void>;
+    appendMessage(input: AppendMessageInput): Promise<Message>;
+    appendMessages(input: AppendMessagesInput): Promise<Message[]>;
+    getMessage(input: MessageRef): Promise<Message | null>;
+    listMessages(input: ListMessagesInput): Promise<Page<Message>>;
+    updateMessage(input: UpdateMessageInput): Promise<Message>;
+    deleteMessage(input: MessageRef): Promise<void>;
+    clearMessages(input: ConversationRef): Promise<void>;
+    private readSnapshotSeq;
+    private execute;
+}
+export declare function createStore(options: CreateStoreOptions): Store;

package/dist/types/store/supabase-transport.d.ts

@@ -0,0 +1,43 @@
+import { type PostgrestSingleResponse, type SupabaseClient } from "@supabase/supabase-js";
+import { type CreateAuthenticatedSupabaseClientOptions } from "../_internal/data-plane/index.js";
+import { StoreCredentialProvider, type StoreCredentialProviderOptions } from "./credential-provider.js";
+/**
+ * Store 数据面请求经过当前锁定版本 supabase-js 包装后的完整响应。
+ *
+ * 成功：`{ success: true, data: T, error: null, count, status, statusText }`。
+ * 失败：`{ success: false, data: null, error: PostgrestError, count: null, status, statusText }`。
+ *
+ * 这是 SDK 内部 transport 合同，不是 PostgREST 服务的原始 HTTP body。
+ */
+export type SupabaseStoreOperationResult<T> = PostgrestSingleResponse<T>;
+export interface SupabaseStoreResult<T> {
+    data: T;
+    count: number | null;
+}
+export interface ExecuteSupabaseStoreOperationOptions<T> {
+    /** Stable public operation name used in structured errors. */
+    operationName: string;
+    /**
+     * 只为读取操作或有幂等保证的操作启用。
+     * transport 不会猜测重放写操作是否安全。
+     */
+    retryOnUnauthorized: boolean;
+    /** 只有调用方生成的所有幂等键都已固定后才能启用。 */
+    retryOnNetworkError?: boolean;
+    operation(client: SupabaseClient): PromiseLike<SupabaseStoreOperationResult<T>>;
+}
+export interface SupabaseStoreTransportOptions {
+    credentialProvider: StoreCredentialProvider;
+    fetch?: typeof globalThis.fetch;
+    createClient?: CreateAuthenticatedSupabaseClientOptions["createClient"];
+}
+export interface CreateSupabaseStoreTransportOptions extends Omit<SupabaseStoreTransportOptions, "credentialProvider">, StoreCredentialProviderOptions {
+}
+export declare class SupabaseStoreTransport {
+    private readonly credentialProvider;
+    private readonly fetch;
+    private readonly createClient;
+    constructor(options: SupabaseStoreTransportOptions);
+    execute<T>(options: ExecuteSupabaseStoreOperationOptions<T>): Promise<SupabaseStoreResult<T>>;
+}
+export declare function createSupabaseStoreTransport(options: CreateSupabaseStoreTransportOptions): SupabaseStoreTransport;

package/dist/types/store/token-client.d.ts

@@ -0,0 +1,7 @@
+import { type DataPlaneCredentials, type FetchDataPlaneCredentialsOptions } from "../_internal/data-plane/index.js";
+export interface StoreCredentials extends DataPlaneCredentials {
+}
+export interface FetchStoreCredentialsOptions extends FetchDataPlaneCredentialsOptions {
+}
+export declare function validateStoreRootUrl(value: string, isAllowedHostname: (hostname: string) => boolean): string;
+export declare function fetchStoreCredentials(options: FetchStoreCredentialsOptions): Promise<StoreCredentials>;

package/dist/types/tools/adapters.d.ts

@@ -0,0 +1,5 @@
+import type { BoundTool } from "./sandbox-tools.js";
+import type { ClaudeAgentSdkTool, OpenAIAgentsTool, OpenAISdkTool } from "./types.js";
+export declare function toClaudeAgentSdkTool(source: BoundTool): ClaudeAgentSdkTool;
+export declare function toOpenAISdkTool(source: BoundTool): OpenAISdkTool;
+export declare function toOpenAIAgentsTool(source: BoundTool): OpenAIAgentsTool;

package/dist/types/tools/claude.d.ts

@@ -0,0 +1,4 @@
+import type { Sandbox } from "../sandbox/index.js";
+import type { ClaudeAgentTools } from "./types.js";
+export type { ClaudeAgentTools, ClaudeAgentSdkTool, ClaudeMcpConfig, ClaudeMcpTool, ClaudeMcpToolResult, ClaudeMcpConfigOptions } from "./types.js";
+export declare function getTools(sandbox: Sandbox): ClaudeAgentTools;

package/dist/types/tools/index.d.ts

@@ -0,0 +1,2 @@
+export { getTools } from "./registry.js";
+export type { BrowserFetchInput, BrowserScreenshotInput, CodeRunInput, FilesFindInput, FilesListInput, FilesReadInput, FilesSearchInput, FilesWriteInput, ShellExecInput, ToolInputMap, ToolOutputMap, ShellConsoleEntry, ShellExecOutput, FilesReadOutput, FilesWriteOutput, FileListEntry, FilesListOutput, FileSearchMatch, FilesSearchOutput, FilesFindOutput, CodeRunOutput, BrowserFetchOutput, BrowserScreenshotOutput, JsonSchema, OpenAIToolDeclaration, ClaudeMcpConfig, ClaudeMcpConfigOptions, ClaudeMcpTool, ClaudeMcpToolResult, PortableTools, SandboxToolName, ToolDefinition, ToolDomain, ToolError, ToolExecuteOptions, ToolResult, ToolContent, Tools, } from "./types.js";

package/dist/types/tools/langchain.d.ts

@@ -0,0 +1,16 @@
+import type { StructuredToolInterface as CommonJsStructuredTool } from "@langchain/core/tools" with { "resolution-mode": "require" };
+import type { StructuredToolInterface as EsmStructuredTool } from "@langchain/core/tools" with { "resolution-mode": "import" };
+import type { Sandbox } from "../sandbox/index.js";
+import type { PortableTools, SandboxToolName } from "./types.js";
+/** Native tools compatible with both ESM and CommonJS framework consumers. */
+export type LangChainTool = CommonJsStructuredTool & EsmStructuredTool;
+export interface LangChainTools extends Omit<PortableTools, SandboxToolName | "all" | "get" | "files" | "shell" | "code" | "browser">, Record<SandboxToolName, LangChainTool> {
+    all(): LangChainTool[];
+    get(name: string): LangChainTool;
+    files(): LangChainTool[];
+    shell(): LangChainTool[];
+    code(): LangChainTool[];
+    browser(): LangChainTool[];
+}
+/** Shared by LangChain, LangGraph and DeepAgents. Requires @langchain/core. */
+export declare function getTools(sandbox: Sandbox): LangChainTools;

package/dist/types/tools/model-output.d.ts

@@ -0,0 +1,8 @@
+import type { BrowserScreenshotOutput, LangChainImageContent, OpenAIModelMessage, ToolResult } from "./types.js";
+export declare function isScreenshotResult(result: ToolResult): result is {
+    status: "success";
+    data: BrowserScreenshotOutput;
+};
+export declare function toImageUrlContent(result: ToolResult): LangChainImageContent[];
+/** Chat Completions tool messages are text-only; images go in a subsequent user message. */
+export declare function toOpenAIModelMessages(result: ToolResult, toolCallId: string): OpenAIModelMessage[];

package/dist/types/tools/openai-agents.d.ts

@@ -0,0 +1,4 @@
+import type { Sandbox } from "../sandbox/index.js";
+import type { OpenAIAgentsTools } from "./types.js";
+export type { OpenAIAgentsTools, OpenAIAgentsTool } from "./types.js";
+export declare function getTools(sandbox: Sandbox): OpenAIAgentsTools;

package/dist/types/tools/openai.d.ts

@@ -0,0 +1,5 @@
+import type { Sandbox } from "../sandbox/index.js";
+import type { OpenAISdkTools } from "./types.js";
+export type { OpenAISdkTools, OpenAISdkTool, OpenAIToolDeclaration } from "./types.js";
+export type { OpenAIModelMessage } from "./types.js";
+export declare function getTools(sandbox: Sandbox): OpenAISdkTools;

package/dist/types/tools/registry.d.ts

@@ -0,0 +1,16 @@
+import { type BoundTool } from "./sandbox-tools.js";
+import type { PortableTools, ToolDefinition } from "./types.js";
+import type { Sandbox } from "../sandbox/index.js";
+/** Framework-independent tools. Choose a subpath for a framework adapter. */
+export declare function getTools(sandbox: Sandbox): PortableTools;
+/** Shared collection implementation; the public subpath supplies its own adapter. */
+export declare function createToolRegistry<T, Extensions extends object = Record<never, never>>(sandbox: Sandbox, adapt: (sources: readonly BoundTool[]) => T[], extend?: (sources: readonly BoundTool[], adapted: readonly T[]) => Extensions): {
+    all: () => T[];
+    get: (name: string) => NonNullable<T>;
+    files: () => T[];
+    shell: () => T[];
+    code: () => T[];
+    browser: () => T[];
+    definitions: (names?: readonly string[]) => ToolDefinition<unknown, unknown>[];
+};
+export declare function selectSources(sources: readonly BoundTool[], names?: readonly string[]): BoundTool[];

package/dist/types/tools/result.d.ts

@@ -0,0 +1,17 @@
+import type { ToolError, ToolResult } from "./types.js";
+export declare function success(data: unknown, preserveScreenshot?: boolean): ToolResult;
+export declare function failure(tool: string, error: unknown): ToolResult;
+export declare function normalizeError(tool: string, error: unknown): ToolError;
+/** Convert an official Sandbox SDK APIResponse failure into the public contract. */
+export declare function sandboxResponseError(error: unknown): ToolExecutionError;
+declare class ToolExecutionError extends Error {
+    readonly info: Omit<ToolError, "tool">;
+    constructor(info: Omit<ToolError, "tool">);
+}
+/** Interpret only the documented result fields of the invoked Sandbox operation. */
+export declare function checkSandboxBusinessResult(body: unknown, operation: string, status?: number): void;
+export declare function sanitize(value: unknown, preserveScreenshot?: boolean): unknown;
+export declare function sanitizeMessage(message: string): string;
+/** Error details keep their original structure and full text, with credentials redacted. */
+export declare function redactErrorDetails(value: unknown, ancestors?: WeakSet<object>): unknown;
+export {};

package/dist/types/tools/sandbox-result-mappers.d.ts

@@ -0,0 +1,10 @@
+import type { BrowserFetchOutput, BrowserScreenshotOutput, CodeRunOutput, FilesFindOutput, FilesListOutput, FilesReadOutput, FilesSearchOutput, FilesWriteOutput, ShellExecOutput } from "./types.js";
+export declare function mapShellExecOutput(value: unknown): ShellExecOutput;
+export declare function mapFilesReadOutput(value: unknown): FilesReadOutput;
+export declare function mapFilesWriteOutput(value: unknown): FilesWriteOutput;
+export declare function mapFilesListOutput(value: unknown): FilesListOutput;
+export declare function mapFilesSearchOutput(value: unknown): FilesSearchOutput;
+export declare function mapFilesFindOutput(value: unknown): FilesFindOutput;
+export declare function mapCodeRunOutput(value: unknown): CodeRunOutput;
+export declare function mapBrowserFetchOutput(navigation: unknown, content: unknown): BrowserFetchOutput;
+export declare function mapBrowserScreenshotOutput(body: unknown): Promise<BrowserScreenshotOutput>;

package/dist/types/tools/sandbox-tools.d.ts

@@ -0,0 +1,17 @@
+import type { Sandbox } from "../sandbox/index.js";
+import { z, type ZodType } from "zod";
+import type { JsonSchema, ToolDefinition, ToolDomain, ToolExecuteOptions } from "./types.js";
+export interface SandboxToolSpec {
+    readonly name: string;
+    readonly domain: ToolDomain;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly validate: z.AnyZodObject;
+    readonly execute: (input: Record<string, unknown>, options?: ToolExecuteOptions) => Promise<unknown>;
+}
+export interface BoundTool {
+    readonly definition: ToolDefinition;
+    readonly schema: ZodType<unknown>;
+}
+export declare function createSandboxTools(sandbox: Sandbox): SandboxToolSpec[];
+export declare function bindSandboxTool(spec: SandboxToolSpec): BoundTool;