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

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

@@ -0,0 +1,238 @@
+import type { SandboxClient } from "@agent-infra/sandbox";
+import type { PublicSandboxBusiness } from "./public-surface.js";
+import type { SandboxBindingRepository } from "./binding-repository.js";
+/** IGA Sandbox 控制面成功响应使用的可选信封。 */
+export interface SandboxControlPlaneEnvelope<T> {
+    code: string | number;
+    message?: string;
+    data?: T;
+}
+/** 控制面当前接受直接 payload，或 `{ code, message, data }` 信封。 */
+export type SandboxControlPlaneResponse<T> = T | SandboxControlPlaneEnvelope<T>;
+/** `pages/v1/api/sandbox-token` 的原始 payload。 */
+export interface SandboxTokenResponsePayload {
+    SandboxAppID?: string;
+    ApiKey?: string;
+    Url?: string;
+    TokenType?: string;
+    TokenHeader?: string;
+}
+/** `pages/v1/api/sandbox/create` 的原始 payload。 */
+export interface SandboxCreateResponsePayload {
+    SandboxId?: string;
+}
+/** `pages/v1/api/sandbox/destroy` 的原始 payload。 */
+export type SandboxDestroyResponsePayload = Record<string, never>;
+/** `sandbox/instance` 与 `sandbox/instance/update` 的原始 payload。 */
+export interface SandboxInstanceResponsePayload {
+    SandboxID?: string;
+    ExpireAt?: string;
+    CreatedAt?: string;
+    Status?: string;
+}
+export interface CreateSandboxOptions {
+    /** BytePlus IGA Pages 项目 ID（后端用它定位沙箱应用 / 实例池）。 */
+    projectId: string;
+    /**
+     * 会话 ID。同一 projectId+conversationId 复用同一沙箱实例；
+     * 换一个就拉新实例（缓存键按 [projectId, conversationId] 二元组编码）。
+     */
+    conversationId: string;
+    /**
+     * 后端 base URL。公共入口固定该值；仅内部工厂和测试可传。
+     */
+    apiBaseUrl?: string;
+    /**
+     * 控制面下发的项目 Token。公共入口从运行时 env 读取；仅内部工厂和测试可传。
+     * 每次请求将 Token 与毫秒级 timestamp 一起放入 HTTPS query。
+     */
+    apiToken?: string;
+    /**
+     * 自定义 API client（测试注入用）。传了就忽略 apiBaseUrl / apiToken。
+     * 调用方一般不传。
+     */
+    api?: SandboxApiClient;
+    /** Internal persistence adapter. The public runtime always provides it. */
+    bindingRepository?: SandboxBindingRepository;
+    /** 默认单请求超时（秒），传给官方 SandboxClient。 */
+    timeoutInSeconds?: number;
+}
+/**
+ * 独立实例模式的选项——`createSandbox()`（公共）用。
+ *
+ * 不绑定 conversation：每次调用创建一个新的沙箱实例，实例身份由调用方自己保存
+ * （`getInfo().sandboxId`），之后想再操作它就 `connectSandbox(sandboxId)` 接回来。
+ * SDK 不在 sandboxId → 实例之间维护任何映射。
+ */
+export interface CreateDetachedSandboxOptions {
+    /** 默认单请求超时（秒），传给官方 SandboxClient。 */
+    timeoutInSeconds?: number;
+}
+/**
+ * 接回已有实例模式的选项——`connectSandbox(sandboxId)`（公共）用。
+ *
+ * 不建新实例：getToken 换凭证后直接把数据面路由到目标 sandboxId。
+ */
+export interface AttachSandboxOptions {
+    /** 默认单请求超时（秒），传给官方 SandboxClient。 */
+    timeoutInSeconds?: number;
+}
+/**
+ * 后端 pages/v1/api/sandbox-token 的返回。
+ * 一次返回建 SandboxClient 所需的全部信息：
+ *   - url / apiKey / tokenHeader / tokenType：构造官方 SandboxClient 的鉴权头
+ *   - sandboxAppId：沙箱应用 ID（functionId）
+ */
+export interface SandboxTokenResult {
+    /** 沙箱应用 ID（functionId，用于 x-faas-instance-name 请求头）。 */
+    sandboxAppId?: string;
+    /** e2b_ 开头的沙箱数据面 token，作为 tokenType 头的值。 */
+    apiKey: string;
+    /** 沙箱实例的 HTTPS 域名（environment）。 */
+    url?: string;
+    /** token 类型，通常 "Bearer"。 */
+    tokenType?: string;
+    /** token 头名，通常 "Authorization"。 */
+    tokenHeader?: string;
+    /** 过期时间（ms epoch），后端可下发短期 token。undefined 表示长期有效。 */
+    expireAt?: number;
+}
+/** 后端 pages/v1/api/sandbox/create 的返回。 */
+export interface SandboxCreateResult {
+    /** 沙箱实例 ID，destroy / getInfo / extendTimeout 时回传给后端。 */
+    sandboxId: string;
+}
+/** 后端 pages/v1/api/sandbox/destroy 的返回。 */
+export interface SandboxDestroyResult {
+    ok: boolean;
+}
+/** 查询或续期后的实例信息（getInfo / extendTimeout）。 */
+export interface SandboxInstanceInfo {
+    /**
+     * 实例 ID。历史控制面可用显式空字符串表达不存在；缺失字段不作为销毁证据。
+     * 当前 BOE 的不存在业务错误还需通过精确实例路由确认。
+     */
+    sandboxId: string;
+    /** 过期时间（RFC3339 字符串）。 */
+    expireAt?: string;
+    /** 创建时间（RFC3339 字符串）。 */
+    createdAt?: string;
+    /**
+     * 实例状态（2026-08-21 契约新增）：
+     * `Starting`（启动中）/ `Ready`（可用）/ `Failed`（启动失败）/
+     * `Terminating`（终止中）。后端枚举直接透传。
+     */
+    status?: "Starting" | "Ready" | "Failed" | "Terminating";
+}
+/**
+ * Sandbox API client 抽象。调用方（含测试）都依赖这个接口，不感知具体实现。
+ */
+export interface SandboxApiClient {
+    getToken(opts?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxTokenResult>;
+    create(opts: SandboxApiCallOptions): Promise<SandboxCreateResult>;
+    destroy(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+    }): Promise<SandboxDestroyResult>;
+    /** 查询实例信息（对应 pages/v1/api/sandbox/instance）。 */
+    getInstance(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+    }): Promise<SandboxInstanceInfo>;
+    /**
+     * 定罪查询：实例确认已销毁时抛 内部实例丢失信号。
+     * 判定标准（详见 docs/backend-contracts/sandbox-lifecycle.md）：
+     *   - 实例接口 HTTP 404/410，或历史控制面显式返回空 SandboxID
+     *   - Status 为 Failed / Terminating
+     * HTTP 200 业务失败通过只读数据面查询确认，仅识别结构化 instance_not_found。
+     * ExpireAt 不是实例不存在的证据。其它错误表示无法确认，调用方不得据此重建。
+     */
+    confirmInstanceExists(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+    }): Promise<void>;
+    /** 延长实例超时时间（对应 pages/v1/api/sandbox/instance/update）。 */
+    updateInstanceTimeout(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+        timeoutInMinutes: number;
+    }): Promise<SandboxInstanceInfo>;
+}
+export interface SandboxApiCallOptions {
+    projectId: string;
+    conversationId: string;
+    signal?: AbortSignal;
+}
+/** Cancellation options for one Sandbox lifecycle operation. */
+export interface SandboxOperationOptions {
+    abortSignal?: AbortSignal;
+}
+/**
+ * 内部宿主句柄。内部工厂返回它——既是官方 SandboxClient（业务能力直接挂上），
+ * 又叠加管理能力。调用方零 getClient 样板代码：
+ *
+ *   const sandbox = createSandbox({ projectId, conversationId });
+ *
+ *   // 业务方法直接调，第一次访问自动触发懒加载
+ *   await sandbox.code.executeCode({ language: "python", code: "print(1)" });
+ *   await sandbox.shell.execCommand({ command: "ls" });
+ *   const ctx = await sandbox.sandbox.getContext();
+ *
+ *   // 管理方法
+ *   const info = await sandbox.getInfo();
+ *   await sandbox.extendTimeout(10);
+ *   await sandbox.destroy();
+ *   sandbox.projectId;
+ *
+ * 需要把原装 client 传给外部库时，getClient 还在：
+ *   const client = await sandbox.getClient();
+ *
+ * 实现要点：抄官方 SandboxClient 的 `??=` 懒加载模式，访问 sandbox.code 时构造
+ * 一个懒代理并缓存。代理上的方法被调用时自动 await ensureInstance，然后转发到 raw。
+ */
+export type SandboxInstance = SandboxClient & {
+    readonly projectId: string;
+    /**
+     * 会话 ID。绑定会话的实例才有；`createSandbox()`（独立实例）和
+     * `connectSandbox(sandboxId)`（接回）返回的句柄上没有。
+     */
+    readonly conversationId?: string;
+    /**
+     * 实例 ID。独立实例（createSandbox）和接回（connectSandbox(sandboxId)）的句柄上
+     * 同步可读（公共 createSandbox 在 await 返回前已初始化，内部独立工厂仍懒加载）；
+     * 绑定会话的实例要等首次懒加载后 `getInfo()` 才拿得到。
+     */
+    readonly sandboxId?: string;
+    /**
+     * 拿到底层官方 SandboxClient（原装）。
+     * 首次调用会触发懒加载，后续命中缓存。
+     *
+     * 调用方一般不需要显式调——业务方法（sandbox.code.executeCode 等）会自动触发。
+     * 这个方法给"我要把 client 传给外部库"的场景用：
+     *
+     *   const client = await sandbox.getClient();
+     *   externalLibrary.doSomething(client);
+     */
+    getClient(options?: SandboxOperationOptions): Promise<SandboxClient>;
+    /**
+     * 内部初始化方法，等待实例身份、凭证和客户端准备完成，不轮询远端 Ready 状态。
+     * 供公共 createSandbox 在返回前调用，不对 SDK 用户暴露。
+     */
+    ensureReady(options?: SandboxOperationOptions): Promise<void>;
+    /**
+     * 查询当前实例信息（过期时间 / 创建时间）。
+     * 触发懒加载：如果实例还没建过，会先建一个。
+     */
+    getInfo(options?: SandboxOperationOptions): Promise<SandboxInstanceInfo>;
+    /**
+     * 延长当前实例的超时时间。
+     * @param timeoutInMinutes 实例存活时长，单位分钟；原值透传后端 Time，由后端校验并更新 ExpireAt
+     * 触发懒加载：如果实例还没建过，会先建一个。
+     */
+    extendTimeout(timeoutInMinutes: number, options?: SandboxOperationOptions): Promise<SandboxInstanceInfo>;
+    /**
+     * 显式销毁实例。会调后端 destroy。
+     * destroy 后再调官方方法会重新走一遍懒加载。
+     */
+    destroy(options?: SandboxOperationOptions): Promise<void>;
+};
+/** Public server SDK handle: selected business modules and instance lifecycle. */
+export type Sandbox = PublicSandboxBusiness & Pick<SandboxInstance, "conversationId" | "sandboxId" | "getInfo" | "extendTimeout" | "destroy">;

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

@@ -0,0 +1,41 @@
+import { type JsonObject, type JsonValue } from "./json.js";
+/** 待追加的单条消息内容；批量追加时由外层统一指定 conversationId。 */
+export interface AppendMessageItemInput {
+    /**
+     * 当前项目内唯一的消息 ID，也是存活消息的幂等键；未传时由 SDK 生成 UUID。
+     * 自定义 ID 应为非空字符串，后续读取、更新和删除要求非空。
+     * 业务重试必须显式提供并复用原 ID、会话及内容；省略 ID 的再次调用会生成新 ID。
+     */
+    messageId?: string;
+    /**
+     * 消息角色，如 user、assistant、system、tool，也接受应用自定义字符串。
+     * @default null
+     */
+    role?: string | null;
+    /** 应用自定义的消息类型；省略时为 null，不从 payload 推断。 */
+    type?: string | null;
+    /**
+     * 必填的 JSON 消息内容，可为基础值、数组、普通对象或 null，不要求特定业务字段。
+     * 不接受 undefined、BigInt、函数、NaN、Infinity、循环引用、稀疏数组或类实例；
+     * 日期应先用 toISOString() 转成字符串。
+     */
+    payload: JsonValue;
+    /**
+     * 仅属于此消息的 JSON 元数据对象，不会写入会话 metadata；不能是数组或 null。
+     * 内容遵循与 payload 相同的 JSON 值约束。
+     * @default {}
+     */
+    metadata?: JsonObject;
+}
+export interface MaterializedAppendMessage {
+    messageId: string;
+    role: string | null;
+    type: string | null;
+    payload: JsonValue;
+    metadata: JsonObject;
+}
+/**
+ * 在任何网络请求前校验并克隆完整批次。
+ * 生成的 ID 在所有传输重试中保持稳定，使 append RPC 具备幂等性。
+ */
+export declare function materializeAppendMessages(messages: AppendMessageItemInput[], generateUuid?: () => string): MaterializedAppendMessage[];

package/dist/types/store/claude-repository.d.ts

@@ -0,0 +1,36 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { JsonObject } from "./json.js";
+import type { SupabaseStoreOperationResult, SupabaseStoreResult } from "./supabase-transport.js";
+export declare const CLAUDE_RPC_NAMES: {
+    readonly append: "claude_session_append";
+    readonly load: "claude_session_load";
+    readonly listSessions: "claude_session_list_sessions";
+    readonly delete: "claude_session_delete";
+    readonly listSubkeys: "claude_session_list_subkeys";
+};
+export interface ClaudeSessionKeyRecord {
+    projectKey: string;
+    sessionId: string;
+    subpath: string | null;
+}
+type RuntimeExecutor = <T>(options: {
+    operationName: string;
+    retryOnUnauthorized: boolean;
+    retryOnNetworkError?: boolean;
+    operation(client: SupabaseClient): PromiseLike<SupabaseStoreOperationResult<T>>;
+}) => Promise<SupabaseStoreResult<T>>;
+/** 包内 Claude RPC repository；project scope 只由 Store JWT 提供。 */
+export declare class ClaudeSessionRepository {
+    private readonly execute;
+    constructor(execute?: RuntimeExecutor);
+    append(key: ClaudeSessionKeyRecord, entries: JsonObject[]): Promise<void>;
+    load(key: ClaudeSessionKeyRecord): Promise<unknown>;
+    listSessions(projectKey: string): Promise<unknown>;
+    delete(key: ClaudeSessionKeyRecord): Promise<void>;
+    listSubkeys(input: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<unknown>;
+}
+export declare const claudeSessionRepository: ClaudeSessionRepository;
+export {};

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

@@ -0,0 +1,3 @@
+import type { SessionStore } from "@anthropic-ai/claude-agent-sdk";
+/** 创建绑定当前 IGA project Store 数据面的 Claude Agent SDK SessionStore。 */
+export declare function createSessionStore(): SessionStore;

package/dist/types/store/control-plane-request.d.ts

@@ -0,0 +1,2 @@
+export { postStoreToken } from "../_internal/data-plane/index.js";
+export type { ControlPlaneResponse, PostStoreTokenOptions, } from "../_internal/data-plane/index.js";

package/dist/types/store/credential-error.d.ts

@@ -0,0 +1,2 @@
+import { StoreError } from "./errors.js";
+export declare function toStoreCredentialError(error: unknown): StoreError;

package/dist/types/store/credential-provider.d.ts

@@ -0,0 +1,29 @@
+import { type JwtTiming } from "../_internal/data-plane/index.js";
+import type { StoreCredentials } from "./token-client.js";
+export type { JwtTiming };
+export interface StoreCredentialProviderOptions {
+    fetchCredentials(): Promise<StoreCredentials>;
+    now?: () => number;
+}
+export interface StoreCredentialScope {
+    environment: string;
+    projectId: string;
+}
+export interface StoreCredentialProviderCacheOptions {
+    createProvider(scope: Readonly<StoreCredentialScope>): StoreCredentialProvider;
+}
+export declare function readJwtTiming(jwt: string): JwtTiming;
+export declare class StoreCredentialProvider {
+    private readonly delegate;
+    constructor(options: StoreCredentialProviderOptions);
+    getValidCredentials(): Promise<StoreCredentials>;
+    getProjectId(): Promise<string>;
+    invalidate(jwt?: string): void;
+}
+export declare class StoreCredentialProviderCache {
+    private readonly providers;
+    private readonly createProvider;
+    constructor(options: StoreCredentialProviderCacheOptions);
+    get(scope: Readonly<StoreCredentialScope>): StoreCredentialProvider;
+    clear(scope?: Readonly<StoreCredentialScope>): void;
+}

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

@@ -0,0 +1,29 @@
+/** Supabase/PostgREST 原始错误字段；本地失败只提供可取得的字段。 */
+export interface StoreUpstreamError {
+    readonly code?: string;
+    readonly message: string;
+    readonly details?: string | null;
+    readonly hint?: string | null;
+}
+export interface StoreErrorInfo {
+    /** 数据面取自 error.message；控制面使用换证错误说明。 */
+    readonly message: string;
+    /** HTTP 错误分类，例如 Conflict；无 HTTP 响应时使用本地错误码。 */
+    readonly code: string;
+    readonly status?: number;
+    readonly error?: StoreUpstreamError;
+}
+export interface StoreErrorOptions {
+    status?: number;
+    /** null 表示控制面错误，不附带内层 error。 */
+    error?: StoreUpstreamError | null;
+}
+export declare class StoreError extends Error implements StoreErrorInfo {
+    readonly code: string;
+    readonly status?: number;
+    readonly error?: StoreUpstreamError;
+    constructor(code: string, message: string, options?: StoreErrorOptions);
+    toJSON(): StoreErrorInfo;
+}
+/** 外层只描述 HTTP 分类，不重写内层 SQLSTATE 或 PostgREST 错误。 */
+export declare function storeCodeForStatus(status: number): string;

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

@@ -0,0 +1,31 @@
+import type { createClient } from "@supabase/supabase-js";
+import { type StoreCredentialScope } from "./credential-provider.js";
+import { type Store, type StoreRpcNames } from "./store.js";
+import type { StoreCredentials } from "./token-client.js";
+export interface StoreScope {
+    projectId: string;
+}
+export interface StoreFactoryOptions {
+    environment: string;
+    fetchCredentials(scope: Readonly<StoreCredentialScope>): Promise<StoreCredentials>;
+    fetch?: typeof globalThis.fetch;
+    createClient?: typeof createClient;
+    now?: () => number;
+    generateUuid?: () => string;
+    rpcNames?: Partial<StoreRpcNames>;
+}
+/**
+ * 进程作用域的 Store 工厂。创建项目 Store 实例是同步且无网络副作用的；
+ * 首次调用 Store API 时才延迟获取凭证。
+ */
+export declare class StoreFactory {
+    private readonly options;
+    private readonly credentials;
+    private readonly transports;
+    constructor(options: StoreFactoryOptions);
+    create(scope: StoreScope): Store;
+    clear(scope?: {
+        projectId: string;
+    }): void;
+}
+export declare function createStoreFactory(options: StoreFactoryOptions): StoreFactory;

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

@@ -0,0 +1,5 @@
+export { createStoreFactory, StoreFactory, } from "./factory.js";
+export type { StoreFactoryOptions, StoreScope, } from "./factory.js";
+export { fetchStoreCredentials, validateStoreRootUrl, } from "./token-client.js";
+export type { FetchStoreCredentialsOptions, StoreCredentials, } from "./token-client.js";
+export type { StoreCredentialScope } from "./credential-provider.js";

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

@@ -0,0 +1,6 @@
+/** 面向 BytePlus IGA Pages Functions 和全栈服务端处理器的 Store SDK。 */
+export { store } from "./runtime-store.js";
+export { StoreError } from "./errors.js";
+export type { StoreErrorInfo, StoreUpstreamError, } from "./errors.js";
+export type { Store, AppendMessageInput, AppendMessagesInput, Conversation, CreateConversationInput, ListConversationsInput, ListMessagesInput, Message, Page, UpdateConversationInput, UpdateMessageInput, } from "./store.js";
+export type { AppendMessageItemInput } from "./append.js";

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

@@ -0,0 +1,7 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export declare function cloneJsonValue(value: unknown, field: string): JsonValue;
+export declare function cloneJsonObject(value: unknown, field: string): JsonObject;

package/dist/types/store/langgraph-repository.d.ts

@@ -0,0 +1,98 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { SupabaseStoreOperationResult, SupabaseStoreResult } from "./supabase-transport.js";
+export declare const LANGGRAPH_RPC_NAMES: {
+    readonly putCheckpoint: "langgraph_put_checkpoint";
+    readonly getCheckpoint: "langgraph_get_checkpoint";
+    readonly listCheckpoints: "langgraph_list_checkpoints";
+    readonly putWrites: "langgraph_put_writes";
+    readonly getDeltaHistory: "langgraph_get_delta_history";
+    readonly deleteThread: "langgraph_delete_thread";
+};
+export interface LangGraphBlobRow {
+    channel: string;
+    version: string;
+    type: string;
+    blob_base64: string | null;
+}
+export interface LangGraphWriteRow {
+    task_id: string;
+    idx: number;
+    channel: string;
+    type: string;
+    blob_base64: string;
+}
+export interface LangGraphCheckpointRow {
+    thread_id: string;
+    checkpoint_ns: string;
+    checkpoint_id: string;
+    parent_checkpoint_id: string | null;
+    checkpoint: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    blobs: LangGraphBlobRow[];
+    writes: LangGraphWriteRow[];
+    pending_sends?: LangGraphWriteRow[];
+}
+export interface LangGraphDeltaHistoryRow {
+    depth: number;
+    checkpoint_id: string;
+    parent_checkpoint_id: string | null;
+    blobs: LangGraphBlobRow[];
+    writes: LangGraphWriteRow[];
+}
+export interface PutCheckpointRecord {
+    threadId: string;
+    checkpointNamespace: string;
+    checkpointId: string;
+    parentCheckpointId: string | null;
+    checkpoint: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    blobs: LangGraphBlobRow[];
+}
+export interface ListCheckpointQuery {
+    threadId: string | null;
+    checkpointNamespace: string | null;
+    checkpointId: string | null;
+    metadata: Record<string, unknown> | null;
+    beforeCheckpointId: string | null;
+    limit: number | null;
+}
+export interface PutWritesRecord {
+    threadId: string;
+    checkpointNamespace: string;
+    checkpointId: string;
+    taskId: string;
+    writes: Array<{
+        idx: number;
+        channel: string;
+        type: string;
+        blob_base64: string;
+    }>;
+}
+type RuntimeExecutor = <T>(options: {
+    operationName: string;
+    retryOnUnauthorized: boolean;
+    retryOnNetworkError?: boolean;
+    operation(client: SupabaseClient): PromiseLike<SupabaseStoreOperationResult<T>>;
+}) => Promise<SupabaseStoreResult<T>>;
+/** 包内 RPC repository；输入在 saver 层物化后，所有写操作都可安全重放。 */
+export declare class LangGraphCheckpointRepository {
+    private readonly execute;
+    constructor(execute?: RuntimeExecutor);
+    putCheckpoint(record: PutCheckpointRecord): Promise<unknown>;
+    getCheckpoint(input: {
+        threadId: string;
+        checkpointNamespace: string;
+        checkpointId: string | null;
+    }): Promise<unknown>;
+    listCheckpoints(query: ListCheckpointQuery): Promise<unknown>;
+    putWrites(record: PutWritesRecord): Promise<unknown>;
+    getDeltaHistory(input: {
+        threadId: string;
+        checkpointNamespace: string;
+        checkpointId: string | null;
+        channels: string[];
+    }): Promise<unknown>;
+    deleteThread(threadId: string): Promise<unknown>;
+}
+export declare const langGraphCheckpointRepository: LangGraphCheckpointRepository;
+export {};

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

@@ -0,0 +1,43 @@
+import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointMetadata, type CheckpointPendingWrite, type DeltaChannelHistory, type PendingWrite, type SerializerProtocol } from "@langchain/langgraph-checkpoint";
+/**
+ * 只描述 saver 实际读取和返回的 config 字段，避免 LangChain 双模式包在
+ * CommonJS/ESM 消费者之间泄漏两份带 protected 成员的 RunnableConfig 类型。
+ */
+export interface LangGraphRunnableConfig {
+    configurable?: Record<string, any>;
+    [key: string]: any;
+}
+export interface IgaCheckpointTuple {
+    config: LangGraphRunnableConfig;
+    checkpoint: Checkpoint;
+    metadata?: CheckpointMetadata;
+    parentConfig?: LangGraphRunnableConfig;
+    pendingWrites?: CheckpointPendingWrite[];
+}
+export interface IgaCheckpointListOptions {
+    limit?: number;
+    before?: LangGraphRunnableConfig;
+    filter?: Record<string, any>;
+}
+/** IGA Store 数据面上的 LangGraph CheckpointSaver。 */
+export declare class IgaCheckpointSaver extends BaseCheckpointSaver<string> {
+    constructor(serde?: SerializerProtocol);
+    get(config: LangGraphRunnableConfig): Promise<Checkpoint | undefined>;
+    getTuple(config: LangGraphRunnableConfig): Promise<IgaCheckpointTuple | undefined>;
+    list(config: LangGraphRunnableConfig, options?: IgaCheckpointListOptions): AsyncGenerator<IgaCheckpointTuple>;
+    put(config: LangGraphRunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions: ChannelVersions): Promise<LangGraphRunnableConfig>;
+    putWrites(config: LangGraphRunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    getDeltaChannelHistory(options: {
+        config: LangGraphRunnableConfig;
+        channels: string[];
+    }): Promise<Record<string, DeltaChannelHistory>>;
+    getNextVersion(current: any): any;
+    private dumpMetadata;
+    private loadMetadata;
+    private dumpValue;
+    private loadValue;
+    private materializeTuple;
+}
+/** 创建轻量 saver；直到首次 saver 方法调用才访问 IGA Store runtime。 */
+export declare function createCheckpointer(serde?: SerializerProtocol): IgaCheckpointSaver;

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

@@ -0,0 +1,12 @@
+/**
+ * 在结构上等价于 OpenAI Agents SDK 的 Session 合同。
+ * 采用结构化适配，避免核心 Store SDK 依赖特定版本的 OpenAI Agents SDK。
+ */
+export interface OpenAISession<TItem = any> {
+    getSessionId(): Promise<string>;
+    getItems(limit?: number): Promise<TItem[]>;
+    addItems(items: TItem[]): Promise<void>;
+    popItem(): Promise<TItem | undefined>;
+    clearSession(): Promise<void>;
+}
+export declare function createSession<TItem = any>(conversationId: string): OpenAISession<TItem>;

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

@@ -0,0 +1,27 @@
+export declare const DEFAULT_STORE_PAGE_LIMIT = 50;
+export declare const MAX_STORE_PAGE_LIMIT = 100;
+interface ConversationCursorV1 {
+    version: 1;
+    kind: "conversations";
+    updatedAt: string;
+    conversationId: string;
+}
+interface MessageCursorV1 {
+    version: 1;
+    kind: "messages";
+    conversationId: string;
+    order: "asc" | "desc";
+    snapshotSeq: string;
+    lastSeq: string;
+}
+export type ConversationCursor = Omit<ConversationCursorV1, "version" | "kind">;
+export type MessageCursor = Omit<MessageCursorV1, "version" | "kind">;
+export declare function normalizeStorePageLimit(limit?: number): number;
+export declare function encodeConversationCursor(cursor: ConversationCursor): string;
+export declare function decodeConversationCursor(value: string): ConversationCursor;
+export declare function encodeMessageCursor(cursor: MessageCursor): string;
+export declare function decodeMessageCursor(value: string, expected: {
+    conversationId: string;
+    order: "asc" | "desc";
+}): MessageCursor;
+export {};

package/dist/types/store/runtime-data-plane.d.ts

@@ -0,0 +1,8 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { type Store } from "./store.js";
+import { type ExecuteSupabaseStoreOperationOptions, type SupabaseStoreResult } from "./supabase-transport.js";
+export declare function resolveRuntimeStore(): Promise<Store>;
+/** 包内数据面入口；只接受操作闭包，不向公共 API 暴露 client 或凭证。 */
+export declare function executeRuntimeStoreOperation<T>(options: ExecuteSupabaseStoreOperationOptions<T>): Promise<SupabaseStoreResult<T>>;
+/** 仅供包内类型检查，防止 operation 的 client 类型被意外扩宽。 */
+export type RuntimeStoreOperation<T> = (client: SupabaseClient) => ReturnType<ExecuteSupabaseStoreOperationOptions<T>["operation"]>;

package/dist/types/store/runtime-provider.d.ts

@@ -0,0 +1 @@
+export { store } from "./runtime-store.js";

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

@@ -0,0 +1,20 @@
+import type { Store } from "./store.js";
+/**
+ * 当前 BytePlus IGA Pages 项目的 Store 能力。仅在首次调用方法时读取运行时项目身份，
+ * 并在当前进程内复用创建出的 Store；业务代码不能传入项目身份或凭证。
+ * 在 Node.js 20+ 的 BytePlus IGA Pages 服务端使用；本地通过 `bp-iga pages link` 关联项目后运行
+ * `bp-iga pages dev`。应用负责终端用户身份和会话访问权限校验。
+ *
+ * @example
+ * ```ts
+ * import { store } from "@byteplus-iga-pages/agent/store";
+ *
+ * const { conversationId } = await store.createConversation({
+ *   metadata: { title: "新对话" },
+ * });
+ * await store.appendMessage({ conversationId, role: "user", payload: { text: "你好" } });
+ * const page = await store.listMessages({ conversationId, order: "desc", limit: 20 });
+ * // page.items 最新消息在前；page.nextCursor 为 null 时没有下一页。
+ * ```
+ */
+export declare const store: Store;