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

package/dist/types/_internal/data-plane/control-plane-request.d.ts

@@ -0,0 +1,12 @@
+export declare function getControlPlaneHeaders(): Readonly<Record<string, string>>;
+export interface ControlPlaneResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+export interface PostStoreTokenOptions {
+    endpoint: URL;
+    body: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function postStoreToken(options: PostStoreTokenOptions): Promise<ControlPlaneResponse>;

package/dist/types/_internal/data-plane/control-plane.d.ts

@@ -0,0 +1,3 @@
+export declare const CONTROL_PLANE_BASE_URL: string;
+export declare const ALLOWED_STORE_HOST_SUFFIX: string;
+export declare const CONTROL_PLANE_HEADERS: Readonly<Record<string, string>>;

package/dist/types/_internal/data-plane/credential-provider.d.ts

@@ -0,0 +1,25 @@
+import type { DataPlaneCredentials } from "./token-client.js";
+export interface JwtTiming {
+    issuedAtMs: number;
+    expiresAtMs: number;
+}
+export interface DataPlaneCredentialProviderOptions {
+    fetchCredentials(): Promise<DataPlaneCredentials>;
+    now?: () => number;
+}
+/** Reads the project identity; authorization is still enforced by the data plane. */
+export declare function readJwtProjectId(jwt: string): string;
+export declare function readJwtTiming(jwt: string): JwtTiming;
+export declare class DataPlaneCredentialProvider {
+    private readonly fetchCredentials;
+    private readonly now;
+    private current;
+    private refreshPromise;
+    private projectId;
+    constructor(options: DataPlaneCredentialProviderOptions);
+    getValidCredentials(signal?: AbortSignal): Promise<DataPlaneCredentials>;
+    getProjectId(signal?: AbortSignal): Promise<string>;
+    invalidate(jwt?: string): void;
+    private refresh;
+    private toPublic;
+}

package/dist/types/_internal/data-plane/errors.d.ts

@@ -0,0 +1,19 @@
+export declare const DATA_PLANE_ERROR_CODES: readonly ["invalid_argument", "not_found", "conflict", "unauthenticated", "permission_denied", "too_large", "rate_limited", "aborted", "unavailable", "unsupported", "execution_failed", "internal"];
+export type DataPlaneErrorCode = (typeof DATA_PLANE_ERROR_CODES)[number];
+export interface DataPlaneErrorOptions {
+    operation: string;
+    retryable?: boolean;
+    requestId?: string;
+    status?: number;
+    failureKind?: "authentication_failed" | "timeout";
+}
+/** Internal-only error. Domain packages must translate it before exporting. */
+export declare class DataPlaneError extends Error {
+    readonly code: DataPlaneErrorCode;
+    readonly operation: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly status?: number;
+    readonly failureKind?: "authentication_failed" | "timeout";
+    constructor(code: DataPlaneErrorCode, message: string, options: DataPlaneErrorOptions);
+}

package/dist/types/_internal/data-plane/index.d.ts

@@ -0,0 +1,11 @@
+export { CONTROL_PLANE_BASE_URL } from "./control-plane.js";
+export { ALLOWED_STORE_HOST_SUFFIX, STORE_TOKEN_ENDPOINT, fetchDataPlaneCredentials, fetchRuntimeDataPlaneCredentials, validateDataPlaneRootUrl, } from "./token-client.js";
+export type { DataPlaneCredentials, FetchDataPlaneCredentialsOptions, } from "./token-client.js";
+export { DataPlaneCredentialProvider, readJwtTiming, readJwtProjectId, } from "./credential-provider.js";
+export type { DataPlaneCredentialProviderOptions, JwtTiming, } from "./credential-provider.js";
+export { createAuthenticatedSupabaseClient } from "./supabase-client.js";
+export type { CreateAuthenticatedSupabaseClientOptions } from "./supabase-client.js";
+export { DataPlaneError } from "./errors.js";
+export type { DataPlaneErrorCode, DataPlaneErrorOptions } from "./errors.js";
+export { postStoreToken, getControlPlaneHeaders } from "./control-plane-request.js";
+export type { ControlPlaneResponse, PostStoreTokenOptions, } from "./control-plane-request.js";

package/dist/types/_internal/data-plane/supabase-client.d.ts

@@ -0,0 +1,12 @@
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
+import type { DataPlaneCredentials } from "./token-client.js";
+export interface CreateAuthenticatedSupabaseClientOptions {
+    credentials: DataPlaneCredentials;
+    requestId?: string;
+    fetch?: typeof globalThis.fetch;
+    createClient?: typeof createClient;
+    signal?: AbortSignal;
+    realtimeError(): Error;
+}
+/** Creates a request-scoped client bound to one already validated JWT version. */
+export declare function createAuthenticatedSupabaseClient(options: CreateAuthenticatedSupabaseClientOptions): SupabaseClient;

package/dist/types/_internal/data-plane/token-client.d.ts

@@ -0,0 +1,23 @@
+import { ALLOWED_STORE_HOST_SUFFIX } from "./control-plane.js";
+export declare const STORE_TOKEN_ENDPOINT: string;
+export { ALLOWED_STORE_HOST_SUFFIX };
+export interface DataPlaneCredentials {
+    url: string;
+    anonKey: string;
+    jwt: string;
+}
+export interface FetchDataPlaneCredentialsOptions {
+    endpoint: string;
+    token: string;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+    isAllowedTokenEndpoint(url: URL): boolean;
+    isAllowedHostname(hostname: string): boolean;
+}
+export declare function validateDataPlaneRootUrl(value: string, isAllowedHostname: (hostname: string) => boolean): string;
+export declare function fetchDataPlaneCredentials(options: FetchDataPlaneCredentialsOptions): Promise<DataPlaneCredentials>;
+export declare function fetchRuntimeDataPlaneCredentials(options: {
+    token: string;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+}): Promise<DataPlaneCredentials>;

package/dist/types/sandbox/api-client.d.ts

@@ -0,0 +1,37 @@
+import type { SandboxApiCallOptions, SandboxApiClient, SandboxCreateResult, SandboxDestroyResult, SandboxInstanceInfo, SandboxTokenResult } from "./types.js";
+export interface CreateSandboxApiClientOptions {
+    /** 后端 base URL（不含路径，如 https://api.iga.example.com）。 */
+    apiBaseUrl?: string;
+    /** 控制面下发的项目 Token；只允许内部 SDK 代码传入。 */
+    apiToken?: string;
+}
+export declare function createSandboxApi(opts: CreateSandboxApiClientOptions): SandboxApiClient;
+export declare class SandboxApi implements SandboxApiClient {
+    private readonly baseUrl?;
+    private readonly token?;
+    private readonly now;
+    private readonly http;
+    constructor(baseUrl?: string | undefined, token?: string | undefined, now?: () => number);
+    private resolveBaseUrl;
+    getToken(opts?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxTokenResult>;
+    create(opts: SandboxApiCallOptions): Promise<SandboxCreateResult>;
+    destroy(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+    }): Promise<SandboxDestroyResult>;
+    getInstance(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+    }): Promise<SandboxInstanceInfo>;
+    confirmInstanceExists(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+    }): Promise<void>;
+    private confirmMissingViaDataPlane;
+    updateInstanceTimeout(opts: SandboxApiCallOptions & {
+        sandboxId: string;
+        timeoutInMinutes: number;
+    }): Promise<SandboxInstanceInfo>;
+    private postJson;
+}
+/** Exact routing failure observed from veFaaS; a generic HTTP 404 is insufficient. */
+export declare function isConfirmedMissingInstanceResponse(value: unknown): boolean;

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

@@ -0,0 +1,81 @@
+import type { SandboxApi as UpstreamSandboxApi } from "@agent-infra/sandbox";
+/**
+ * Named API types for the allowed code, shell, file and browserPage methods.
+ * Keep this positive export list explicit: upstream additions are reviewed before
+ * becoming public. Aliases preserve upstream field definitions without copying them.
+ * Includes the nested data types referenced by these methods' requests/responses.
+ */
+export type BashCommandStatus = UpstreamSandboxApi.BashCommandStatus;
+export type BrowserPageGetHtmlRequest = UpstreamSandboxApi.BrowserPageGetHtmlRequest;
+export type BrowserPageScreenshotRequest = UpstreamSandboxApi.BrowserPageScreenshotRequest;
+export type CheckRequest = UpstreamSandboxApi.CheckRequest;
+export type ClickRequest = UpstreamSandboxApi.ClickRequest;
+export type CodeExecuteRequest = UpstreamSandboxApi.CodeExecuteRequest;
+export type CodeExecuteResponse = UpstreamSandboxApi.CodeExecuteResponse;
+export type ConsoleRecord = UpstreamSandboxApi.ConsoleRecord;
+export type FileContentEncoding = UpstreamSandboxApi.FileContentEncoding;
+export type FileFindRequest = UpstreamSandboxApi.FileFindRequest;
+export type FileFindResult = UpstreamSandboxApi.FileFindResult;
+export type FileGrepRequest = UpstreamSandboxApi.FileGrepRequest;
+export type FileGrepResult = UpstreamSandboxApi.FileGrepResult;
+export type FileInfo = UpstreamSandboxApi.FileInfo;
+export type FileListRequest = UpstreamSandboxApi.FileListRequest;
+export type FileListResult = UpstreamSandboxApi.FileListResult;
+export type FileOperationError = UpstreamSandboxApi.FileOperationError;
+export type FileReadRequest = UpstreamSandboxApi.FileReadRequest;
+export type FileReadResult = UpstreamSandboxApi.FileReadResult;
+export type FileReplaceRequest = UpstreamSandboxApi.FileReplaceRequest;
+export type FileReplaceResult = UpstreamSandboxApi.FileReplaceResult;
+export type FileSearchRequest = UpstreamSandboxApi.FileSearchRequest;
+export type FileSearchResult = UpstreamSandboxApi.FileSearchResult;
+export type FileWriteRequest = UpstreamSandboxApi.FileWriteRequest;
+export type FileWriteResult = UpstreamSandboxApi.FileWriteResult;
+export type FillRequest = UpstreamSandboxApi.FillRequest;
+export type GrepMatch = UpstreamSandboxApi.GrepMatch;
+export type HotKeyRequest = UpstreamSandboxApi.HotKeyRequest;
+export type HoverRequest = UpstreamSandboxApi.HoverRequest;
+export type HttpValidationError = UpstreamSandboxApi.HttpValidationError;
+export type KeyRequest = UpstreamSandboxApi.KeyRequest;
+export type Language = UpstreamSandboxApi.Language;
+export type NavigateRequest = UpstreamSandboxApi.NavigateRequest;
+export type NavigateRequestWaitUntil = UpstreamSandboxApi.NavigateRequestWaitUntil;
+export type Response = UpstreamSandboxApi.Response;
+export type ResponseCodeExecuteResponse = UpstreamSandboxApi.ResponseCodeExecuteResponse;
+export type ResponseDict = UpstreamSandboxApi.ResponseDict;
+export type ResponseShellCommandResult = UpstreamSandboxApi.ResponseShellCommandResult;
+export type ResponseShellKillResult = UpstreamSandboxApi.ResponseShellKillResult;
+export type ResponseShellViewResult = UpstreamSandboxApi.ResponseShellViewResult;
+export type ResponseShellWaitResult = UpstreamSandboxApi.ResponseShellWaitResult;
+export type ResponseStr = UpstreamSandboxApi.ResponseStr;
+export type ResponseUnionFileFindResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileFindResultFileOperationError;
+export type ResponseUnionFileFindResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileFindResultFileOperationErrorData;
+export type ResponseUnionFileGrepResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileGrepResultFileOperationError;
+export type ResponseUnionFileGrepResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileGrepResultFileOperationErrorData;
+export type ResponseUnionFileListResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileListResultFileOperationError;
+export type ResponseUnionFileListResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileListResultFileOperationErrorData;
+export type ResponseUnionFileReadResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileReadResultFileOperationError;
+export type ResponseUnionFileReadResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileReadResultFileOperationErrorData;
+export type ResponseUnionFileReplaceResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileReplaceResultFileOperationError;
+export type ResponseUnionFileReplaceResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileReplaceResultFileOperationErrorData;
+export type ResponseUnionFileSearchResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileSearchResultFileOperationError;
+export type ResponseUnionFileSearchResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileSearchResultFileOperationErrorData;
+export type ResponseUnionFileWriteResultFileOperationError = UpstreamSandboxApi.ResponseUnionFileWriteResultFileOperationError;
+export type ResponseUnionFileWriteResultFileOperationErrorData = UpstreamSandboxApi.ResponseUnionFileWriteResultFileOperationErrorData;
+export type ScrollRequest = UpstreamSandboxApi.ScrollRequest;
+export type ScrollToElementRequest = UpstreamSandboxApi.ScrollToElementRequest;
+export type ScrollToRequest = UpstreamSandboxApi.ScrollToRequest;
+export type SelectOptionRequest = UpstreamSandboxApi.SelectOptionRequest;
+export type ShellCommandResult = UpstreamSandboxApi.ShellCommandResult;
+export type ShellExecRequest = UpstreamSandboxApi.ShellExecRequest;
+export type ShellKillProcessRequest = UpstreamSandboxApi.ShellKillProcessRequest;
+export type ShellKillResult = UpstreamSandboxApi.ShellKillResult;
+export type ShellViewRequest = UpstreamSandboxApi.ShellViewRequest;
+export type ShellViewResult = UpstreamSandboxApi.ShellViewResult;
+export type ShellWaitRequest = UpstreamSandboxApi.ShellWaitRequest;
+export type ShellWaitResult = UpstreamSandboxApi.ShellWaitResult;
+export type Type = UpstreamSandboxApi.Type;
+export type TypeTextRequest = UpstreamSandboxApi.TypeTextRequest;
+export type UploadFileRequest = UpstreamSandboxApi.UploadFileRequest;
+export type ValidationError = UpstreamSandboxApi.ValidationError;
+export type ValidationErrorLocItem = UpstreamSandboxApi.ValidationErrorLocItem;
+export type WaitRequest = UpstreamSandboxApi.WaitRequest;

package/dist/types/sandbox/binding-repository.d.ts

@@ -0,0 +1,62 @@
+import { DataPlaneCredentialProvider, type CreateAuthenticatedSupabaseClientOptions } from "../_internal/data-plane/index.js";
+export type SandboxBindingAcquireResult = {
+    action: "attach";
+    generation: number;
+    sandboxId: string;
+} | {
+    action: "create";
+    generation: number;
+    leaseExpiresAt: string;
+} | {
+    action: "wait";
+    generation: number;
+    leaseExpiresAt: string;
+};
+export type SandboxBindingDestroyResult = {
+    action: "none";
+} | {
+    action: "wait";
+    leaseExpiresAt: string;
+} | {
+    action: "destroy";
+    generation: number;
+    sandboxId: string;
+};
+export interface SandboxBindingRepository {
+    acquire(conversationId: string, leaseToken: string, signal?: AbortSignal): Promise<SandboxBindingAcquireResult>;
+    publish(conversationId: string, generation: number, leaseToken: string, sandboxId: string, signal?: AbortSignal): Promise<boolean>;
+    release(conversationId: string, generation: number, leaseToken: string, signal?: AbortSignal): Promise<void>;
+    invalidate(conversationId: string, generation: number, sandboxId: string, signal?: AbortSignal): Promise<boolean>;
+    beginDestroy(conversationId: string, leaseToken: string, signal?: AbortSignal): Promise<SandboxBindingDestroyResult>;
+    finishDestroy(conversationId: string, generation: number, leaseToken: string, signal?: AbortSignal): Promise<void>;
+    restore(conversationId: string, generation: number, leaseToken: string, signal?: AbortSignal): Promise<void>;
+}
+export interface SupabaseSandboxBindingRepositoryOptions {
+    credentialProvider: DataPlaneCredentialProvider;
+    fetch?: typeof globalThis.fetch;
+    createClient?: CreateAuthenticatedSupabaseClientOptions["createClient"];
+    generateUuid?: () => string;
+    leaseSeconds?: number;
+}
+export declare class SupabaseSandboxBindingRepository implements SandboxBindingRepository {
+    private readonly credentialProvider;
+    private readonly fetch?;
+    private readonly createClient?;
+    private readonly generateUuid;
+    private readonly leaseSeconds;
+    constructor(options: SupabaseSandboxBindingRepositoryOptions);
+    acquire(conversationId: string, leaseToken: string, signal?: AbortSignal): Promise<SandboxBindingAcquireResult>;
+    publish(conversationId: string, generation: number, leaseToken: string, sandboxId: string, signal?: AbortSignal): Promise<boolean>;
+    release(conversationId: string, generation: number, leaseToken: string, signal?: AbortSignal): Promise<void>;
+    invalidate(conversationId: string, generation: number, sandboxId: string, signal?: AbortSignal): Promise<boolean>;
+    beginDestroy(conversationId: string, leaseToken: string, signal?: AbortSignal): Promise<SandboxBindingDestroyResult>;
+    finishDestroy(conversationId: string, generation: number, leaseToken: string, signal?: AbortSignal): Promise<void>;
+    restore(conversationId: string, generation: number, leaseToken: string, signal?: AbortSignal): Promise<void>;
+    private booleanRpc;
+    private rpc;
+}
+export declare function createRuntimeSandboxBindingRepository(options: {
+    token: string;
+    fetch?: typeof globalThis.fetch;
+    createClient?: CreateAuthenticatedSupabaseClientOptions["createClient"];
+}): SandboxBindingRepository;

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

@@ -0,0 +1,22 @@
+export interface IgaErrorInfo {
+    readonly code: string;
+    readonly status?: number;
+    readonly message: string;
+}
+export interface IgaErrorOptions {
+    status?: number;
+}
+/** A safe error for Sandbox lifecycle and control-plane failures. */
+export declare class SandboxError extends Error implements IgaErrorInfo {
+    readonly code: string;
+    readonly status?: number;
+    constructor(message: string, options?: IgaErrorOptions);
+    toJSON(): IgaErrorInfo;
+}
+/** Internal lifecycle signals; neither class is exported by the public entry. */
+export declare class SandboxAbortError extends SandboxError {
+}
+export declare class SandboxInstanceGoneError extends SandboxError {
+}
+/** Recognize cancellation from both the IGA wrapper and the official SDK. */
+export declare function isAbortError(error: unknown): boolean;

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

@@ -0,0 +1,11 @@
+/**
+ * 把后端返回的 expireAt 解析成 ms epoch，解析不了就返回 undefined。
+ *
+ * 后端是 Go 服务，时间格式是 `2026-08-26 17:52:15 +0800 CST`。这种带
+ * 时区缩写的形式 V8 解析不了：`CST` 在 JS 里按美国中部时区（UTC-6）算，
+ * 实际会差出 14 个小时。这里先把显式数字偏移（+0800）换成 `+08:00` 再把
+ * 时区缩写丢掉，让 Date.parse 只认数字偏移。
+ *
+ * 兼容 RFC3339（`2026-08-26T17:52:15+08:00` / `Z` 结尾）——老格式直接过。
+ */
+export declare function parseExpireAtMs(value: string | undefined): number | undefined;

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

@@ -0,0 +1,6 @@
+export { createSandbox, createDetachedSandbox, attachSandbox, IgaSandbox, isInstanceGoneResponse, __clearSandboxCacheForTests, __getEntryForTests, } from "./iga-sandbox.js";
+export type { IgaSandboxConstructorOptions, IgaDetachedSandboxOptions, IgaAttachSandboxOptions, } from "./iga-sandbox.js";
+export { createSandboxApi, SandboxApi, type CreateSandboxApiClientOptions, } from "./api-client.js";
+export { SupabaseSandboxBindingRepository, createRuntimeSandboxBindingRepository, } from "./binding-repository.js";
+export type { SandboxBindingAcquireResult, SandboxBindingDestroyResult, SandboxBindingRepository, SupabaseSandboxBindingRepositoryOptions, } from "./binding-repository.js";
+export type { CreateSandboxOptions, CreateDetachedSandboxOptions, AttachSandboxOptions, SandboxControlPlaneEnvelope, SandboxControlPlaneResponse, SandboxCreateResponsePayload, SandboxDestroyResponsePayload, SandboxOperationOptions, SandboxInstance, SandboxApiClient, SandboxApiCallOptions, SandboxTokenResult, SandboxCreateResult, SandboxDestroyResult, SandboxInstanceInfo, SandboxInstanceResponsePayload, SandboxTokenResponsePayload, } from "./types.js";

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

@@ -0,0 +1,208 @@
+import { SandboxClient } from "@agent-infra/sandbox";
+import type { SandboxApiClient, CreateSandboxOptions, CreateDetachedSandboxOptions, AttachSandboxOptions, SandboxInstance, SandboxInstanceInfo, SandboxOperationOptions } from "./types.js";
+/**
+ * 清空整个缓存。主要给测试用——避免跨用例污染。
+ * 调用方一般不需要调。
+ */
+export declare function __clearSandboxCacheForTests(): void;
+/**
+ * 读缓存 entry 的内部状态（测试用）。公开 Proxy 白名单不暴露 entry，
+ * 单测要用它改暂存的过期时间、模拟"实例快过期"。
+ */
+export declare function __getEntryForTests(projectId: string, conversationId: string): {
+    generation: number;
+    instanceExpireAt?: number;
+    sandboxId?: string;
+} | undefined;
+/**
+ * 数据面初筛：官方业务调用的返回是否"疑似"实例已销毁。
+ * 官方 SDK 失败不抛异常，返回 { ok:false, error: { content: Fetcher.Error } }（探针实测）。
+ *
+ * 只看状态码 404/410，不匹配文案——上游错误响应 body 无稳定契约，文案变了只是
+ * 举报灵敏度下降（少触发初筛），不影响正确性。真正的定罪在控制面
+ * （confirmInstanceExists），这里宁可漏报不可误报。
+ */
+export declare function isInstanceGoneResponse(result: unknown): boolean;
+export interface IgaSandboxOptions extends CreateSandboxOptions {
+}
+/**
+ * 独立实例模式的构造参数（内部用）。公共 `createSandbox()` 从运行时 env 固定
+ * 项目作用域后转成这份配置。
+ */
+export interface IgaDetachedSandboxOptions extends CreateDetachedSandboxOptions {
+    projectId: string;
+    apiBaseUrl?: string;
+    apiToken?: string;
+    api?: SandboxApiClient;
+}
+/**
+ * 接回已有实例模式的构造参数（内部用）。公共 `connectSandbox(sandboxId)` 用。
+ */
+export interface IgaAttachSandboxOptions extends AttachSandboxOptions {
+    projectId: string;
+    sandboxId: string;
+    apiBaseUrl?: string;
+    apiToken?: string;
+    api?: SandboxApiClient;
+}
+/** IgaSandbox 构造参数：判别字段 mode 区分三种实例来源。 */
+export type IgaSandboxConstructorOptions = IgaSandboxOptions | (IgaDetachedSandboxOptions & {
+    mode: "detached";
+}) | (IgaAttachSandboxOptions & {
+    mode: "attach";
+});
+export declare class IgaSandbox {
+    readonly projectId: string;
+    /** 绑定会话的实例才有；detached / attach 模式下是 undefined。 */
+    readonly conversationId?: string;
+    /**
+     * 实例 ID。attach 模式同步可读（调用方传进来的）；
+     * detached 模式懒加载建好后可读；conversation 模式是 undefined（要等 getInfo）。
+     */
+    readonly sandboxId?: string;
+    /** 后端 API。 */
+    private readonly api;
+    /** 实例状态——绑定会话的实例共享 conversation 键下的同一份；其余模式独占。 */
+    private readonly entry;
+    /** 实例来源模式。 */
+    private readonly mode;
+    /** 默认单请求超时（秒）。 */
+    private readonly timeoutInSeconds?;
+    /** 当前 Sandbox 对象的 client；request signal 只通过单次 RequestOptions 传入。 */
+    private raw?;
+    private rawGeneration;
+    /** 懒加载的子模块代理缓存（抄官方 SandboxClient 的 ??= 模式）。
+     *  key 是子模块名（"code"/"shell"/...），value 是 Proxy 子对象。 */
+    private readonly submoduleCache;
+    constructor(options: IgaSandboxConstructorOptions);
+    /**
+     * 给实例挂上所有官方子模块的 getter——访问时返回懒代理。
+     * 用 Object.defineProperty 反射挂载，不硬编码 key 名单。
+     * SDK 升级加新 getter（比如未来 sandbox.ai）自动跟进。
+     */
+    private installLazyGetters;
+    /**
+     * 拿到一个子模块的懒代理——抄官方 SandboxClient 的 ??= 缓存模式。
+     * 第一次访问构造，后续直接返回缓存（保证 sandbox.code === sandbox.code）。
+     *
+     * 代理行为：
+     *   - 访问 sandbox.code 时同步返回代理（不发请求）
+     *   - 调 sandbox.code.executeCode(...) 时 await ensureInstance()，然后转发到 raw.code.executeCode(...)
+     *   - 调用方完全不感知 ensureInstance 的存在
+     */
+    private getLazySubmodule;
+    /**
+     * 实例预期外销毁的自动恢复入口。两段式，防止误重建：
+     *
+     *   1. 初筛：业务调用返回疑似销毁响应（数据面 404/410）
+     *   2. 定罪：问一次控制面 confirmInstanceExists——只有它明确说"没了"
+     *      （not_found）才重建；控制面自己失败（网络抖动/500）一律不重建
+     *
+     * 定罪后：清缓存 + best-effort destroy + 重建 + 原调用重试一次。
+     * 重试结果直接返回，不递归。generation 变了（别的 Sandbox 对象已处理）就不再动。
+     *
+     * 只对绑定会话的实例生效。detached / attach 模式不自动重建：
+     *   - detached：静默换新实例后，调用方保存的 sandboxId 就指向死实例了，
+     *     后续 connectSandbox(sandboxId) 接不回来，状态对不上
+     *   - attach：调用方点名要这个实例，换一个等于偷换对象
+     */
+    private callWithRecreate;
+    /**
+     * 控制面定罪：实例确认已销毁返回 true；无法确认（含控制面自身故障）返回 false。
+     * singleflight：并发初筛命中只验证一次。
+     */
+    private confirmDestroyed;
+    /**
+     * 定罪后的恢复：清 entry 状态 + best-effort 清理旧实例（可能已不存在，失败静默），
+     * 下次 ensureInstance 懒加载重建。不做后台重建——恢复链里 invoke() 会触发。
+     */
+    private recreateInstance;
+    private performRecreation;
+    /**
+     * 拿到底层官方 SandboxClient（原装）。
+     * 首次调用会触发懒加载（getToken + create + new 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>;
+    private ensureInstance;
+    /**
+     * 真正干活的初始化方法：getToken → create → 顺路查一次实例过期时间 → 构造官方 SandboxClient。
+     * 成功后写入共享的实例身份、凭证元数据；request-scoped client 由 createClient 构造。
+     */
+    private startInitialization;
+    private waitForInitialization;
+    private initializeEntry;
+    private queryUsableInstance;
+    private initializePersistentConversation;
+    private commitInitializedEntry;
+    /**
+     * attach 模式的初始化：getToken 换凭证 → 前置检查实例状态 → header 指向目标 sandboxId。
+     * 不调 create——实例已经存在，我们只是接上它。
+     *
+     * 前置检查（attach 特有，conversation 模式没有——它自己 create 的实例一定存在）：
+     *   1. 查一次 sandbox/instance。空 SandboxID / Failed / Terminating → 直接抛
+     *      not_found，调用方在接回时就能知道实例没了，不用等第一次业务调用撞 404
+     *   2. 已过期（ExpireAt 已过）→ 自动调 updateInstanceTimeout 续 30 分钟，
+     *      调用方无感继续用；续期失败按"实例状态未知"抛 not_found，宁可失败也不
+     *      让调用方拿一个马上要死的实例去跑业务
+     */
+    private initializeAttach;
+    /** 管理 API（instance / instance/update / destroy）共用的调用参数。 */
+    private managementCallOpts;
+    private createClient;
+    getInfo(options?: SandboxOperationOptions): Promise<SandboxInstanceInfo>;
+    extendTimeout(timeoutInMinutes: number, options?: SandboxOperationOptions): Promise<SandboxInstanceInfo>;
+    /**
+     * 管理方法的销毁恢复：控制面抛 not_found（后端 404）本身就是定罪——
+     * 管理接口就在控制面上，不需要二次验证。其它错误原样抛。
+     *
+     * detached / attach 模式不重建（理由同 callWithRecreate）——not_found
+     * 原样抛给调用方，由调用方决定下一步。
+     */
+    private managementCallWithRecreate;
+    destroy(options?: SandboxOperationOptions): Promise<void>;
+    private performDestroy;
+    private destroyStandalone;
+    private destroyPersistentBinding;
+}
+/**
+ * 创建一个 IgaSandbox 实例——既是官方 SandboxClient（业务能力自动懒加载），
+ * 又叠加管理能力（getInfo / extendTimeout / destroy）。
+ *
+ * 工厂本身不发任何网络请求。业务方法直接调用即可，第一次访问触发懒加载：
+ *
+ *   const sandbox = createSandbox({...});
+ *   await sandbox.code.executeCode({...});   // ← 第一次调用自动触发懒加载
+ *   await sandbox.destroy();
+ *
+ * 同一 projectId:conversationId 多次调用会共享实例身份和凭证缓存；请求取消只通过
+ * 单次 operation 的 abortSignal 传入，不会固化进 Sandbox 对象或共享 client。
+ */
+export declare function createSandbox(options: CreateSandboxOptions): SandboxInstance;
+/**
+ * 独立实例：不绑定 conversation，不进缓存。首次懒加载时建全新实例，
+ * sandboxId 挂到 Sandbox 对象上（`sandbox.sandboxId`），调用方自己保存。
+ * 之后再操作它用 `connectSandbox(sandboxId)`（公共入口）接回来。
+ *
+ * 工厂本身不发网络请求。
+ */
+export declare function createDetachedSandbox(options: IgaDetachedSandboxOptions): SandboxInstance;
+/**
+ * 接回已有实例：不建新实例。首次懒加载时 getToken 换凭证 + 前置检查，数据面路由
+ * 指向传入的 sandboxId。sandboxId 在 Sandbox 对象上同步可读。
+ *
+ * 前置检查（fail-fast）：查一次 sandbox/instance——实例不存在 / Failed /
+ * Terminating 直接抛 `内部实例丢失信号`；已过期自动续期 30 分钟，
+ * 续不上也抛错。控制面查询自身失败原样抛，不误判 not_found。
+ */
+export declare function attachSandbox(options: IgaAttachSandboxOptions): SandboxInstance;

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

@@ -0,0 +1,8 @@
+/** Server-only Sandbox SDK for BytePlus IGA Pages Functions and full-stack handlers. */
+export { connectSandbox, createSandbox, getConversationSandbox, } from "./runtime-sandbox.js";
+export { SandboxError, isAbortError } from "./error.js";
+export type { IgaErrorInfo } from "./error.js";
+export type { Sandbox, SandboxOperationOptions, SandboxInstanceInfo, } from "./types.js";
+export type { BaseRequestOptions } from "@agent-infra/sandbox";
+/** Named request, response-body and data types for the public business modules. */
+export type * as SandboxApi from "./api-types.js";

package/dist/types/sandbox/public-surface.d.ts

@@ -0,0 +1,19 @@
+import type { SandboxClient } from "@agent-infra/sandbox";
+/** Explicit business-method allowlist. Upstream additions stay internal. */
+export declare const PUBLIC_SANDBOX_METHODS: {
+    readonly code: readonly ["executeCode"];
+    readonly shell: readonly ["execCommand", "view", "waitForProcess", "killProcess"];
+    readonly file: readonly ["readFile", "writeFile", "replaceInFile", "searchInFile", "findFiles", "grepFiles", "listPath"];
+    readonly browserPage: readonly ["navigate", "back", "forward", "reload", "click", "fill", "typeText", "pressKey", "hotKey", "hover", "selectOption", "check", "uncheck", "uploadFile", "scroll", "scrollTo", "scrollToElement", "screenshot", "getHtml", "getText", "wait"];
+};
+export type PublicSandboxModule = keyof typeof PUBLIC_SANDBOX_METHODS;
+export declare const PUBLIC_SANDBOX_MODULES: PublicSandboxModule[];
+type PublicSandboxMethod<T> = T extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : never;
+export type PublicSandboxBusiness = {
+    [M in PublicSandboxModule]: {
+        [K in Extract<(typeof PUBLIC_SANDBOX_METHODS)[M][number], keyof SandboxClient[M]>]: PublicSandboxMethod<SandboxClient[M][K]>;
+    };
+};
+/** Plain frozen facades prevent access through descriptors or prototypes too. */
+export declare function createPublicModules(invoke: (module: PublicSandboxModule, method: string, args: unknown[]) => unknown): PublicSandboxBusiness;
+export {};

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

@@ -0,0 +1,32 @@
+import type { Sandbox } from "./types.js";
+/**
+ * 返回某个会话对应的逻辑沙箱；conversationId 为非空字符串，UTF-8 最多 256 字节。
+ *
+ * 同一 projectId:conversationId 始终定位同一逻辑沙箱，实例身份与首次初始化
+ * 跨请求复用；返回轻量的 Sandbox 对象，不发网络请求，首次访问官方能力才触发懒加载。
+ */
+export declare function getConversationSandbox(conversationId: string): Sandbox;
+/**
+ * 创建一个独立沙箱实例，不绑定任何会话。
+ *
+ * SDK 不在 sandboxId 与实例之间维护映射——调用方 await 返回后直接读取
+ * `sandbox.sandboxId` 并自己保存；之后再操作
+ * 这个实例用 `connectSandbox(sandboxId)` 接回来。
+ *
+ * 等待凭证获取、远端实例创建和客户端初始化完成后返回；初始化失败时 reject。
+ */
+export declare function createSandbox(): Promise<Sandbox & {
+    readonly sandboxId: string;
+}>;
+/**
+ * 通过 sandboxId 接回一个已存在的沙箱实例。
+ *
+ * 不建新实例：懒加载时只换凭证，数据面路由直接指向传入的 sandboxId。
+ * SDK 不维护 sandboxId 映射。
+ *
+ * 懒加载时做前置检查（fail-fast）：
+ *   - 实例不存在（或状态为 Failed / Terminating）→ 抛 `内部实例丢失信号`，
+ *     不用等第一次业务调用撞 404 才发现
+ *   - 实例已过期 → 自动续期 30 分钟后接回；续不上就抛错
+ */
+export declare function connectSandbox(sandboxId: string): Sandbox;