run402-mcp/dist/sandbox-proxy.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

/**
 * The chain proxy: how a `run` snippet reaches the SDK without the SDK ever
 * running inside the sandbox.
 *
 * Inside the sandbox, `r` is a recorder. A property access appends a `get`
 * segment and a call appends a `call` segment with its arguments; nothing
 * happens until the chain is awaited (its `then`, `catch`, or `finally` is
 * read), at which point the chain crosses to the host as JSON. The host
 * ({@link ChainHost}) replays it against the real client, built with
 * `surface: "sandbox"`, awaiting every intermediate that is a promise:
 *
 *     r.project("prj_1").functions.list()
 *       → get project → call ("prj_1") → get functions → get list → call ()
 *
 * The terminal value crosses back as JSON when it is JSON data. Anything else
 * (a `ScopedRun402` from `await r.project()`, a deploy operation) crosses as an
 * opaque handle that the recorder wraps again, so the snippet keeps chaining
 * from it; handles die with the run.
 *
 * Arguments cross into the host only when they are structured-cloneable data
 * (JSON values, `undefined`, `Date`, bytes, `Map`, `Set`, `BigInt`) or a handle.
 * A function, a symbol, a class instance, a cyclic structure, or an un-awaited
 * `r` chain is refused in the sandbox before anything is sent
 * (`RUN_ARGUMENT_NOT_CLONEABLE`), which is also why a filesystem source such as
 * a `LocalDirRef` cannot be expressed: `dir()` does not exist inside.
 *
 * The replay walks only the SDK's public surface. A property the SDK declares
 * `private` or `protected` (read from the SDK's own declaration files), a name
 * that starts with `_`, `constructor` / `prototype` / `__proto__`, and anything
 * that resolves on a JavaScript intrinsic (`Object.prototype`,
 * `Function.prototype`, `Array.prototype`, …) is refused, so a chain can reach
 * neither the host's `Function` constructor nor the kernel client and its
 * credential provider. Plain data returned by a call is navigable by its own
 * properties only.
 *
 * Every dispatched chain is one entry in `calls[]` with its dotted path, its
 * duration, and its outcome. An SDK error thrown during the replay crosses
 * back with its own `code`, `message`, and `next_actions`, plus an
 * `error_ref` that lets the `run` tool report the original error unchanged.
 */
import type { SandboxExtension } from "./sandbox.js";
/** `calls[]` entries retained per run. */
export declare const CHAIN_MAX_CALLS = 200;
/** The largest intermediate value one chain may carry back into the sandbox. */
export declare const CHAIN_MAX_TRANSFER_BYTES: number;
export interface ChainCall {
    /** The dotted SDK path the chain replayed, e.g. `project.functions.list`. */
    path: string;
    duration_ms: number;
    ok: boolean;
    /** The error code when the call failed. */
    code?: string;
    /** The payment-attempt journal id, when the failure carried one. */
    payment_attempt_id?: string;
}
/**
 * Every `private` / `protected` member name the SDK declares, by class name,
 * read once from the SDK's declaration files (TypeScript's `private` is not
 * enforced at runtime, so the declaration is the only record of it).
 */
export declare function sdkPrivateMembers(): Map<string, Set<string>>;
/**
 * A member the SDK object does not have. Carries the closest public members,
 * so the run's error can say "did you mean" instead of "is not a function".
 */
export declare class UnknownMember extends TypeError {
    readonly path: string;
    readonly suggestions: string[];
    readonly members: string[];
    readonly code = "RUN_UNKNOWN_MEMBER";
    /**
     * @param path        the missing member as a snippet writes it, e.g. `r.project(…).sql`
     * @param suggestions full paths, as a snippet writes them, that do exist
     * @param members     the parent's public members
     */
    constructor(path: string, suggestions: string[], members: string[]);
}
/** The members closest to `key`: case-insensitive match first, then small edit distance, then containment. At most three. */
export declare function closestMembers(key: string, members: string[]): string[];
/**
 * Replays recorded chains against `root` (the real SDK client) for one run.
 * Holds that run's handles, its `calls[]` trace, and the original errors, and
 * forgets all of them at {@link dispose}.
 */
export declare class ChainHost {
    #private;
    readonly calls: ChainCall[];
    callsDropped: number;
    constructor(root: unknown);
    /** The sandbox extension that installs `r` and routes its chains here. */
    extension(): SandboxExtension;
    /** The original error behind an `error_ref` the sandbox reported, if it came from a replay. */
    errorFor(ref: string | undefined): unknown;
    /** How many chains are replaying right now. */
    get inflight(): number;
    dispose(): void;
    dispatch(raw: string): Promise<string>;
}
//# sourceMappingURL=sandbox-proxy.d.ts.map