@granular-software/sdk 0.4.3 → 0.4.5

package/dist/index.d.mts

@@ -1,8 +1,777 @@
 import * as Automerge from '@automerge/automerge';
-import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, E as EffectInfo, b as ToolInfo, c as EffectsChangedEvent, d as ToolsChangedEvent, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, e as EnvironmentData, f as GraphQLResult, g as DefineRelationshipOptions, h as RelationshipInfo, M as ModelRef, i as ManifestContent, j as RecordObjectOptions, k as RecordObjectResult, S as SandboxListResponse, l as Sandbox, m as CreateSandboxData, n as DeleteResponse, o as PermissionProfile, p as CreatePermissionProfileData, q as CreateEnvironmentData, r as Subject, A as AssignmentListResponse } from './types-C0AVRsVR.mjs';
-export { ag as APIError, t as AccessTokenProvider, y as Assignment, L as Build, N as BuildListResponse, B as BuildPolicy, K as BuildStatus, Y as EffectHandler, O as EffectHandlerContext, Q as EffectSchema, V as EffectWithHandler, u as EndpointMode, z as EnvironmentListResponse, v as GranularAuth, Z as InstanceEffectHandler, _ as JobStatus, $ as JobSubmitResult, F as Manifest, ac as ManifestEffectDeclaration, ab as ManifestEffectSchema, ae as ManifestImport, H as ManifestListResponse, ad as ManifestOperation, a9 as ManifestPropertySpec, aa as ManifestRelationshipDef, af as ManifestVolume, x as PermissionProfileListResponse, w as PermissionRules, a0 as Prompt, X as PublishEffectsResult, a3 as RPCRequest, a6 as RPCRequestFromServer, a4 as RPCResponse, a5 as SyncMessage, a7 as ToolInvokeParams, a8 as ToolResultParams, s as ToolSchema, a1 as WSDisconnectInfo, a2 as WSReconnectErrorInfo } from './types-C0AVRsVR.mjs';
 import { Doc } from '@automerge/automerge/slim';
 
+/**
+ * @module @granular-software/sdk/types
+ * Type definitions for the Granular SDK
+ */
+/**
+ * Configuration for the Granular client
+ */
+type AccessTokenProvider = () => Promise<string | null | undefined> | string | null | undefined;
+type EndpointMode = 'auto' | 'local' | 'production';
+interface GranularOptions {
+    /** Your Granular API key (for service/CLI auth; use with GRANULAR_API_KEY) */
+    apiKey?: string;
+    /** Application/session JWT (for user-context auth; use from simulator or getAccessToken) */
+    token?: string;
+    /** Optional provider used to refresh JWT before WebSocket (re)connect attempts */
+    tokenProvider?: AccessTokenProvider;
+    /** Optional API URL (for on-prem or testing) */
+    apiUrl?: string;
+    /** Optional endpoint mode when apiUrl is not explicitly provided */
+    endpointMode?: EndpointMode;
+    /** Optional WebSocket constructor (for Node.js environments) */
+    WebSocketCtor?: any;
+    /**
+     * Optional callback invoked when a connected WebSocket closes unexpectedly.
+     * Useful for forwarding close diagnostics to monitoring (e.g., Sentry).
+     */
+    onUnexpectedClose?: (info: WSDisconnectInfo) => void;
+    /**
+     * Optional callback invoked when automatic reconnect fails.
+     * Useful to capture auth or gateway rejection causes.
+     */
+    onReconnectError?: (info: WSReconnectErrorInfo) => void;
+}
+/** Resolved auth credential: either apiKey or token must be provided */
+type GranularAuth = string;
+/**
+ * A user/subject object returned from recordUser()
+ */
+interface User {
+    /** Internal subject ID */
+    subjectId: string;
+    /** External identity ID (e.g. Auth0 ID) */
+    identityId: string;
+    /** User's display name */
+    name?: string;
+    /** User's email */
+    email?: string;
+    /** Permission profile IDs to be assigned when connecting */
+    permissions: string[];
+}
+/**
+ * Options for recording a user
+ */
+interface RecordUserOptions {
+    /** External user/identity ID (e.g. your Auth0 or database user ID) */
+    userId: string;
+    /** User's display name */
+    name?: string;
+    /** User's email */
+    email?: string;
+    /** Permission profile IDs to assign when connecting to sandboxes */
+    permissions?: string[];
+}
+/**
+ * Subject as returned from the API
+ */
+interface Subject {
+    subjectId: string;
+    tenantId: string;
+    identityId: string;
+    email?: string | null;
+    name?: string | null;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Options for connecting to a sandbox
+ */
+interface ConnectOptions {
+    /** The sandbox name or ID to connect to */
+    sandbox: string;
+    /** The user to connect as (from recordUser()) */
+    user: User;
+    /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
+     *  value for long-lived effect hosts so tool catalogs don't accumulate. */
+    clientId?: string;
+    /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
+    initialHeap?: Array<{
+        className: string;
+        id: string;
+    }>;
+}
+/**
+ * A sandbox container
+ */
+interface Sandbox {
+    sandboxId: string;
+    tenantId: string;
+    name: string;
+    description?: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating a new sandbox
+ */
+interface CreateSandboxData {
+    name: string;
+    description?: string;
+}
+/**
+ * List response for sandboxes
+ */
+interface SandboxListResponse {
+    items: Sandbox[];
+}
+/**
+ * Rules defining what effects and resources are allowed or denied.
+ */
+interface PermissionRules {
+    /** Effect access rules */
+    effects?: {
+        /** Patterns for allowed effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        allow?: string[];
+        /** Patterns for denied effects */
+        deny?: string[];
+    };
+    /** Legacy alias accepted by the backend while migrating to `effects`. */
+    tools?: {
+        /** Patterns for allowed effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        allow?: string[];
+        /** Patterns for denied effects */
+        deny?: string[];
+    };
+    /** Resource access rules */
+    resources?: {
+        /** Patterns for allowed resources */
+        allow?: string[];
+        /** Patterns for denied resources */
+        deny?: string[];
+    };
+}
+/**
+ * A permission profile defines access controls for an environment
+ */
+interface PermissionProfile {
+    permissionProfileId: string;
+    sandboxId: string;
+    name: string;
+    rules: PermissionRules;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating a new permission profile
+ */
+interface CreatePermissionProfileData {
+    name: string;
+    rules: PermissionRules;
+}
+/**
+ * List response for permission profiles
+ */
+interface PermissionProfileListResponse {
+    items: PermissionProfile[];
+}
+/**
+ * An assignment links a subject to a sandbox with a permission profile
+ */
+interface Assignment {
+    assignmentId: string;
+    tenantId: string;
+    subjectId: string;
+    sandboxId: string;
+    permissionProfileId: string;
+    createdAt: number;
+    createdBy?: string | null;
+}
+/**
+ * List response for assignments
+ */
+interface AssignmentListResponse {
+    items: Assignment[];
+}
+/**
+ * Build policy for environments
+ */
+interface BuildPolicy {
+    mode: 'current' | 'pinned';
+    buildId?: string;
+}
+/**
+ * An environment links a user (subject) to a sandbox with specific permissions
+ */
+interface EnvironmentData {
+    environmentId: string;
+    sandboxId: string;
+    buildId: string;
+    subjectId: string;
+    permissionProfileId: string;
+    buildPolicy: BuildPolicy;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating a new environment
+ */
+interface CreateEnvironmentData {
+    /** The user/subject ID to create the environment for */
+    subjectId: string;
+    /** The permission profile to apply (optional - uses assignment if not specified) */
+    permissionProfileId?: string | null;
+    /** Build policy (defaults to current build) */
+    buildPolicy?: BuildPolicy;
+}
+/**
+ * List response for environments
+ */
+interface EnvironmentListResponse {
+    items: EnvironmentData[];
+}
+/**
+ * A manifest describes the structure and behavior of a sandbox
+ */
+interface Manifest {
+    manifestId: string;
+    sandboxId: string;
+    version: string;
+    digest: string;
+    content?: Record<string, unknown>;
+    createdAt: number;
+    locked?: boolean;
+}
+/**
+ * List response for manifests
+ */
+interface ManifestListResponse {
+    items: Manifest[];
+}
+type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
+/**
+ * A build represents a compiled version of a manifest
+ */
+interface Build {
+    buildId: string;
+    sandboxId: string;
+    manifestId: string;
+    status: BuildStatus;
+    graphBinaryId?: string | null;
+    logsUri?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    isCurrent?: boolean;
+}
+/**
+ * List response for builds
+ */
+interface BuildListResponse {
+    items: Build[];
+}
+/**
+ * Effect handler for static/global effects: receives (input, context)
+ */
+interface EffectHandlerContext {
+    effectClientId: string;
+    sandboxId: string;
+    environmentId: string;
+    sessionId: string;
+    tenantId?: string;
+    principalId?: string;
+    permissionProfileId?: string;
+    user: {
+        subjectId: string;
+        identityId?: string;
+        principalId?: string;
+    };
+}
+type ToolHandler = (input: any, context: EffectHandlerContext) => Promise<unknown>;
+/**
+ * Effect handler for instance methods: receives (objectId, input, context)
+ */
+type InstanceToolHandler = (id: string, input: any, context: EffectHandlerContext) => Promise<unknown>;
+/**
+ * Effect schema for declaring or registering an effect.
+ *
+ * Effects come in three flavours:
+ *
+ * 1. **Instance methods** — set `className`, omit `static`.
+ *    In the sandbox: `tolkien.get_bio({ detailed: true })`
+ *    Handler signature: `(objectId: string, params: any) => any`
+ *
+ * 2. **Static methods** — set `className` + `static: true`.
+ *    In the sandbox: `Author.search({ query: 'tolkien' })`
+ *    Handler signature: `(params: any) => any`
+ *
+ * 3. **Global effects** — omit `className`.
+ *    In the sandbox: `global_search({ query: 'rings' })`
+ *    Handler signature: `(params: any) => any`
+ *
+ * Both `inputSchema` and `outputSchema` accept JSON Schema objects.
+ * The `outputSchema` drives the return type in the auto-generated
+ * TypeScript declarations that sandbox code imports from `./sandbox-tools`.
+ */
+interface ToolSchema {
+    effectKey?: string;
+    name: string;
+    description: string;
+    /** JSON Schema for the effect input parameters */
+    inputSchema: Record<string, unknown>;
+    /**
+     * JSON Schema for the tool's return value.
+     * Used to generate typed return types in the sandbox TypeScript declarations.
+     *
+     * @example
+     * ```typescript
+     * outputSchema: {
+     *   type: 'object',
+     *   properties: {
+     *     bio: { type: 'string', description: 'The biography text' },
+     *     source: { type: 'string', description: 'Source of the bio' },
+     *   },
+     *   required: ['bio'],
+     * }
+     * // Generates: Promise<{ bio: string; source?: string }>
+     * ```
+     */
+    outputSchema?: Record<string, unknown>;
+    stability?: 'stable' | 'experimental' | 'deprecated';
+    provenance?: {
+        source: 'mcp' | 'custom';
+    };
+    tags?: string[];
+    /**
+     * The class this effect belongs to (e.g., `'author'`, `'book'`).
+     * When set, the effect becomes a method on the auto-generated class.
+     * Omit for global effects (standalone exported functions).
+     */
+    className?: string;
+    /**
+     * If `true`, this is a static/class-level method (no object ID required).
+     * If `false` or omitted and `className` is set, this is an instance method
+     * that operates on a specific object (the object's real-world ID is
+     * passed as the first argument to the handler).
+     */
+    static?: boolean;
+}
+type EffectSchema = ToolSchema;
+/**
+ * Effect with handler — what users provide to `registerEffect()`.
+ *
+ * - **Instance methods** (`className` set, `static` omitted):
+ *   handler receives `(objectId: string, params: any)`
+ * - **Static methods** (`className` set, `static: true`):
+ *   handler receives `(params: any)`
+ * - **Global tools** (no `className`):
+ *   handler receives `(params: any)`
+ */
+interface ToolWithHandler extends ToolSchema {
+    handler: ToolHandler | InstanceToolHandler;
+}
+type EffectWithHandler = ToolWithHandler;
+/**
+ * Result from publishing or synchronizing effects
+ */
+interface PublishToolsResult {
+    accepted: boolean;
+    domainRevision: string;
+    rejected?: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+type PublishEffectsResult = PublishToolsResult;
+/**
+ * Domain state response
+ */
+interface DomainState {
+    activeDomainRevision?: string;
+    tools?: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * Information about a live or declared effect
+ */
+interface ToolInfo {
+    effectKey?: string;
+    /** Unique name of the effect */
+    name: string;
+    /** Description of what the effect does */
+    description?: string;
+    /** JSON Schema for effect input */
+    inputSchema?: Record<string, unknown>;
+    /** JSON Schema for effect output */
+    outputSchema?: Record<string, unknown>;
+    /** Client ID that published this effect (absent for domain-only entries) */
+    clientId?: string;
+    /** Whether the effect is ready for use (has a registered handler) */
+    ready: boolean;
+    /** Timestamp when the effect was published */
+    publishedAt?: number;
+    /** Class this effect belongs to (instance/static method) */
+    className?: string;
+    /** Whether this is a static method */
+    static?: boolean;
+}
+interface EffectInfo extends ToolInfo {
+}
+/**
+ * Event data when the list of available effects changes
+ */
+interface ToolsChangedEvent {
+    /** The current list of all available effects */
+    tools: ToolInfo[];
+    /** Names of effects that were added or updated */
+    added: string[];
+    /** Names of effects that were removed */
+    removed: string[];
+}
+interface EffectsChangedEvent extends ToolsChangedEvent {
+    /** The current list of all available effects */
+    effects: EffectInfo[];
+}
+type EffectHandler = ToolHandler;
+type InstanceEffectHandler = InstanceToolHandler;
+type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+/**
+ * Result from submitting a job
+ */
+interface JobSubmitResult {
+    jobId: string;
+}
+/**
+ * Represents a job executed in the sandbox
+ */
+interface Job {
+    /** Unique Job ID */
+    id: string;
+    /** Current status of the job */
+    status: JobStatus;
+    /** Promise that resolves with the job result */
+    result: Promise<unknown>;
+    /** Subscribe to job events */
+    on(event: string, handler: (data: unknown) => void): void;
+}
+interface Prompt {
+    id: string;
+    type: 'confirm' | 'choice' | 'input';
+    title: string;
+    message: string;
+    options?: string[];
+    defaultValue?: unknown;
+}
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+interface SessionHeapFieldValue {
+    name: string;
+    type: SessionHeapFieldType;
+    value: string | number | boolean | null;
+}
+interface SessionHeapEntry {
+    path: string;
+    className: string;
+    id: string;
+    label?: string | null;
+    description?: string | null;
+    prototypes: string[];
+    fields: SessionHeapFieldValue[];
+    relatedJobIds: string[];
+    source: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionHeapList {
+    name: string;
+    className: string;
+    paths: string[];
+    relatedJobIds: string[];
+    updatedAt: number;
+}
+interface SessionHeapVariable {
+    name: string;
+    kind: 'entry' | 'list' | 'scalar';
+    entryPath?: string;
+    listName?: string;
+    value?: string | number | boolean | null;
+    className?: string;
+    updatedAt: number;
+}
+interface SessionHeapSnapshot {
+    entriesByPath: Record<string, SessionHeapEntry>;
+    listsByName: Record<string, SessionHeapList>;
+    variablesByName: Record<string, SessionHeapVariable>;
+    updatedAt: number;
+}
+interface WSDisconnectInfo {
+    code?: number;
+    reason?: string;
+    wasClean?: boolean;
+    unexpected: boolean;
+    timestamp: number;
+    reconnectScheduled: boolean;
+    reconnectDelayMs?: number;
+}
+interface WSReconnectErrorInfo {
+    sessionId: string;
+    error: string;
+    timestamp: number;
+}
+interface WSClientOptions {
+    url: string;
+    sessionId: string;
+    token: string;
+    tokenProvider?: AccessTokenProvider;
+    WebSocketCtor?: any;
+    onUnexpectedClose?: (info: WSDisconnectInfo) => void;
+    onReconnectError?: (info: WSReconnectErrorInfo) => void;
+}
+interface RPCRequest {
+    type: 'rpc';
+    method: string;
+    params: unknown;
+    id: string;
+}
+interface RPCResponse {
+    type: 'rpc_result' | 'rpc_error';
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface SyncMessage {
+    type: 'sync';
+    message?: string | number[] | Uint8Array;
+    data?: number[];
+}
+interface RPCRequestFromServer {
+    type: 'rpc';
+    method: string;
+    params: unknown;
+    id: string;
+}
+interface ToolInvokeParams {
+    callId: string;
+    toolName: string;
+    input: unknown;
+}
+interface ToolResultParams {
+    callId: string;
+    result?: unknown;
+    error?: string | {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * A model reference as returned from relationship queries
+ */
+interface ModelRef {
+    path: string;
+    label?: string;
+}
+/**
+ * Relationship info as returned from the GraphQL API.
+ * Represents a typed, bidirectional relationship between two model types,
+ * seen from one model's perspective.
+ */
+interface RelationshipInfo {
+    /** Unique name of this relationship definition */
+    name: string;
+    /** The submodel on this model that holds the relationship */
+    local_submodel: ModelRef;
+    /** Whether this side is a "many" collection */
+    local_is_many: boolean;
+    /** The submodel on the foreign model */
+    foreign_submodel: ModelRef;
+    /** Whether the foreign side is a "many" collection */
+    foreign_is_many: boolean;
+    /** The foreign model type */
+    foreign_model: ModelRef;
+    /** Computed relationship kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" */
+    relationship_kind: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
+}
+/**
+ * Options for defining a relationship between two model types
+ */
+interface DefineRelationshipOptions {
+    /** The model to define the relationship on (the "left" / "local" type) */
+    model: string;
+    /** The submodel name on the local model (e.g., "books") */
+    localSubmodel: string;
+    /** Whether the local side is "many" */
+    localIsMany: boolean;
+    /** The foreign model type (e.g., "book") */
+    foreignModel: string;
+    /** The submodel name on the foreign model (e.g., "author") */
+    foreignSubmodel: string;
+    /** Whether the foreign side is "many" */
+    foreignIsMany: boolean;
+    /** Optional relationship name (auto-generated if omitted) */
+    name?: string;
+}
+/**
+ * Options for creating or updating a class instance in the graph.
+ *
+ * `recordObject` uses the graph's `instantiate` (find-or-create) semantics:
+ * if an instance with the given `id` already exists under the class, its
+ * fields are updated in place; otherwise a new instance is created.
+ */
+interface RecordObjectOptions {
+    /** The class to instantiate (e.g., "author") */
+    className: string;
+    /**
+     * Real-world object ID. Unique within its class, but two objects of
+     * different classes may share the same ID.  Internally the SDK derives
+     * a unique graph path as `{className}__{id}`.
+     */
+    id: string;
+    /** Optional display label (defaults to `id`) */
+    label?: string;
+    /** Scalar field values to set on the instance */
+    fields?: Record<string, string | number | boolean | null>;
+    /**
+     * Relationship attachments.
+     * Keys are relationship submodel names.  Values are real-world IDs
+     * (not graph paths) — the SDK resolves them using the foreign class
+     * derived from the relationship definition.
+     * - For a "one" side: pass a single target ID (string)
+     * - For a "many" side: pass an array of target IDs
+     */
+    relationships?: Record<string, string | string[]>;
+}
+/**
+ * Return value from `recordObject()`
+ */
+interface RecordObjectResult {
+    /** The internal graph path (e.g., "author__tolkien") */
+    path: string;
+    /** The real-world object ID as provided by the caller (e.g., "tolkien") */
+    id: string;
+    /** Whether the instance was newly created (false = updated) */
+    created: boolean;
+}
+/**
+ * Property specification in a manifest operation
+ */
+interface ManifestPropertySpec {
+    value?: string | number | boolean;
+    ref?: string;
+    instanceOf?: string;
+    create?: string;
+    has?: Record<string, ManifestPropertySpec>;
+    type?: string;
+    description?: string;
+    required?: boolean;
+}
+/**
+ * Relationship definition between two classes
+ */
+interface ManifestRelationshipDef {
+    /** Optional name (auto-generated from left_right if omitted) */
+    name?: string;
+    /** Left model path */
+    left: string;
+    /** Right model path */
+    right: string;
+    /** Submodel name on the left model */
+    leftSubmodel: string;
+    /** Submodel name on the right model */
+    rightSubmodel: string;
+    /** Whether the left side is a collection */
+    leftIsMany: boolean;
+    /** Whether the right side is a collection */
+    rightIsMany: boolean;
+}
+interface ManifestEffectSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+    description?: string;
+    [key: string]: unknown;
+}
+interface ManifestEffectDeclaration {
+    name: string;
+    description?: string;
+    attachedClass?: string;
+    isStatic?: boolean;
+    inputSchema: ManifestEffectSchema;
+    outputSchema?: ManifestEffectSchema;
+    stability?: 'stable' | 'experimental' | 'deprecated';
+    tags?: string[];
+}
+/**
+ * A single operation in a manifest volume
+ */
+interface ManifestOperation {
+    /** Create a new model/class */
+    create?: string;
+    /** Target an existing model for modification */
+    on?: string;
+    /** Extend from a parent class */
+    extends?: string;
+    /** Instantiate a type */
+    instanceOf?: string;
+    /** Define submodels/fields */
+    has?: Record<string, ManifestPropertySpec>;
+    /** Define a relationship between two classes */
+    defineRelationship?: ManifestRelationshipDef;
+    /** Declare a build-owned effect */
+    withEffect?: ManifestEffectDeclaration;
+}
+/**
+ * A volume in a manifest
+ */
+/**
+ * Import descriptor for referencing modules
+ */
+interface ManifestImport {
+    /** Alias prefix used in operations (e.g., "@std") */
+    alias: string;
+    /** Module name (e.g., "standard_modules") */
+    name: string;
+    /** Version label (e.g., "prod", "v1.2.3") */
+    label?: string;
+}
+interface ManifestVolume {
+    name: string;
+    scope: 'sandbox' | 'build' | 'user';
+    imports?: ManifestImport[];
+    operations: ManifestOperation[];
+}
+/**
+ * A manifest defines the structure of a sandbox's data model
+ */
+interface ManifestContent {
+    schemaVersion: 2;
+    name: string;
+    description?: string;
+    volumes: ManifestVolume[];
+}
+/**
+ * Result from a GraphQL query execution
+ */
+interface GraphQLResult<T = any> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        locations?: Array<{
+            line: number;
+            column: number;
+        }>;
+        path?: Array<string | number>;
+        extensions?: Record<string, any>;
+    }>;
+}
+interface APIError {
+    error: string;
+    message?: string;
+}
+interface DeleteResponse {
+    deleted: boolean;
+}
+
 declare class WSClient {
     private ws;
     private url;
@@ -251,6 +1020,13 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /**
+     * Return a plain JS snapshot of the synced session heap.
+     *
+     * The heap lives in the Automerge document, so this method does not perform
+     * any extra network roundtrip.
+     */
+    getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
     /**
      * Close the session and disconnect from the sandbox.
@@ -704,4 +1480,4 @@ declare class Granular {
     private request;
 }
 
-export { AssignmentListResponse, ConnectOptions, CreateEnvironmentData, CreatePermissionProfileData, CreateSandboxData, DefineRelationshipOptions, DeleteResponse, DomainState, EffectInfo, EffectsChangedEvent, Environment, EnvironmentData, Granular, GranularOptions, GraphQLResult, InstanceToolHandler, Job, ManifestContent, ModelRef, PermissionProfile, PublishToolsResult, RecordObjectOptions, RecordObjectResult, RecordUserOptions, RelationshipInfo, Sandbox, SandboxListResponse, Session, Subject, ToolHandler, ToolInfo, ToolWithHandler, ToolsChangedEvent, User, WSClient, WSClientOptions };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };