@granular-software/sdk 0.3.4 → 0.4.2

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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, b as ToolInfo, c as ToolsChangedEvent, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, d as GraphQLResult, e as DefineRelationshipOptions, f as RelationshipInfo, M as ModelRef, g as ManifestContent, h as RecordObjectOptions, i as RecordObjectResult, S as SandboxListResponse, j as Sandbox, k as CreateSandboxData, l as DeleteResponse, m as PermissionProfile, n as CreatePermissionProfileData, o as CreateEnvironmentData, p as Subject, A as AssignmentListResponse } from './types-D5B8WlF4.js';
-export { a4 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a2 as ManifestImport, x as ManifestListResponse, a1 as ManifestOperation, $ as ManifestPropertySpec, a0 as ManifestRelationshipDef, a3 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, Q as RPCRequest, Y as RPCRequestFromServer, V as RPCResponse, X as SyncMessage, Z as ToolInvokeParams, _ as ToolResultParams, q as ToolSchema, N as WSDisconnectInfo, O as WSReconnectErrorInfo } from './types-D5B8WlF4.js';
+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.js';
+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.js';
 import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -16,9 +16,16 @@ declare class WSClient {
     doc: Automerge.Doc<Record<string, unknown>>;
     private syncState;
     private reconnectTimer;
+    private tokenRefreshTimer;
     private isExplicitlyDisconnected;
     private options;
     constructor(options: WSClientOptions);
+    private clearTokenRefreshTimer;
+    private decodeBase64Url;
+    private getTokenExpiryMs;
+    private scheduleTokenRefresh;
+    private refreshTokenInBackground;
+    private resolveTokenForConnect;
     /**
      * Connect to the WebSocket server
      * @returns {Promise<void>} Resolves when connection is open
@@ -82,6 +89,7 @@ declare class Session {
     /** Last known tools for diffing */
     private lastKnownTools;
     constructor(client: WSClient, clientId?: string);
+    private buildLegacyEffectContext;
     get document(): Doc<Record<string, unknown>>;
     get domainRevision(): string | null;
     /**
@@ -115,101 +123,11 @@ declare class Session {
             status: 'warming' | 'hot' | 'unknown';
         };
     }>;
-    /**
-     * Publish tools to the sandbox and register handlers for reverse-RPC.
-     *
-     * Tools can be:
-     * - **Instance methods**: set `className` (handler receives `(objectId, params)`)
-     * - **Static methods**: set `className` + `static: true` (handler receives `(params)`)
-     * - **Global tools**: omit `className` (handler receives `(params)`)
-     *
-     * Both `inputSchema` and `outputSchema` accept JSON Schema objects. The
-     * `outputSchema` drives the return type in the auto-generated TypeScript
-     * class declarations that sandbox code imports from `./sandbox-tools`.
-     *
-     * This method:
-     * 1. Extracts tool schemas (including `outputSchema`) from the provided tools
-     * 2. Publishes them via `client.publishRawToolCatalog` RPC
-     * 3. Registers handlers locally for `tool.invoke` RPC calls
-     * 4. Returns the `domainRevision` needed for job submission
-     *
-     * @param tools - Array of tools with handlers
-     * @param revision - Optional revision string (default: "1.0.0")
-     * @returns PublishToolsResult with domainRevision
-     *
-     * @example
-     * ```typescript
-     * await env.publishTools([
-     *   {
-     *     name: 'get_bio',
-     *     description: 'Get biography of an author',
-     *     className: 'author',
-     *     inputSchema:  { type: 'object', properties: { detailed: { type: 'boolean' } } },
-     *     outputSchema: { type: 'object', properties: { bio: { type: 'string' } }, required: ['bio'] },
-     *     handler: async (id, params) => ({ bio: `Bio of ${id}` }),
-     *   },
-     * ]);
-     * ```
-     */
     publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
-    /**
-     * Publish a single effect (tool) to the sandbox.
-     *
-     * Adds the effect to the local registry and re-publishes the
-     * full tool catalog to the server. If an effect with the same
-     * name already exists, it is replaced.
-     *
-     * @param effect - The effect (tool) to publish
-     * @returns PublishToolsResult with domainRevision
-     *
-     * @example
-     * ```typescript
-     * await env.publishEffect({
-     *   name: 'get_bio',
-     *   description: 'Get biography of an author',
-     *   className: 'author',
-     *   inputSchema: { type: 'object', properties: { detailed: { type: 'boolean' } } },
-     *   handler: async (id, params) => ({ bio: `Bio of ${id}` }),
-     * });
-     * ```
-     */
     publishEffect(effect: ToolWithHandler): Promise<PublishToolsResult>;
-    /**
-     * Publish multiple effects (tools) at once.
-     *
-     * Adds all effects to the local registry and re-publishes the
-     * full tool catalog in a single RPC call.
-     *
-     * @param effects - Array of effects to publish
-     * @returns PublishToolsResult with domainRevision
-     *
-     * @example
-     * ```typescript
-     * await env.publishEffects([
-     *   { name: 'get_bio', description: '...', inputSchema: {}, handler: async (id) => ({}) },
-     *   { name: 'search', description: '...', inputSchema: {}, handler: async (params) => ({}) },
-     * ]);
-     * ```
-     */
     publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
-    /**
-     * Remove an effect by name and re-publish the remaining catalog.
-     *
-     * @param name - The name of the effect to remove
-     * @returns PublishToolsResult with domainRevision
-     */
     unpublishEffect(name: string): Promise<PublishToolsResult>;
-    /**
-     * Remove all effects and publish an empty catalog.
-     *
-     * @returns PublishToolsResult with domainRevision
-     */
     unpublishAllEffects(): Promise<PublishToolsResult>;
-    /**
-     * Internal: re-publish the full effect catalog to the server.
-     * Called after any mutation to the effects Map.
-     */
-    private _syncEffects;
     /**
      * Submit a job to execute code in the sandbox.
      *
@@ -222,8 +140,8 @@ declare class Session {
      * const books = await tolkien.get_books();
      * ```
      *
-     * Tool calls (instance methods, static methods, global functions) trigger
-     * `tool.invoke` RPC back to this client, where the registered handlers
+     * Effect calls (instance methods, static methods, global functions) trigger
+     * `effect.invoke` RPC back to the sandbox effect host, where the registered handlers
      * execute locally and return the result to the sandbox.
      */
     submitJob(code: string, domainRevision?: string): Promise<Job>;
@@ -237,15 +155,23 @@ declare class Session {
      */
     answerPrompt(promptId: string, answer: unknown): Promise<void>;
     /**
-     * Get the current list of available tools.
-     * Consolidates tools from all connected clients.
+     * Get the current list of available effects.
+     * Consolidates effect declarations and live availability for the session.
+     */
+    getEffects(): EffectInfo[];
+    /**
+     * Backwards-compatible alias for `getEffects()`.
      */
     getTools(): ToolInfo[];
     /**
-     * Subscribe to tool changes (added, removed, updated).
+     * Subscribe to effect changes (added, removed, updated).
      * @param callback - Function called with change events
      * @returns Unsubscribe function
      */
+    onEffectsChanged(callback: (event: EffectsChangedEvent) => void): () => void;
+    /**
+     * Backwards-compatible alias for `onEffectsChanged()`.
+     */
     onToolsChanged(callback: (event: ToolsChangedEvent) => void): () => void;
     /**
      * Get the current domain state and available tools
@@ -288,7 +214,7 @@ declare class Session {
     private setupEventHandlers;
     protected emit(event: string, data: unknown): void;
     /**
-     * Check for changes in the tool catalog and emit 'tools:changed' if needed
+     * Check for changes in the effect catalog and emit change events if needed.
      */
     private checkForToolChanges;
 }
@@ -299,10 +225,10 @@ declare class Session {
  * After connecting, you can:
  * 1. Define your domain ontology via `applyManifest()` (classes, properties, relationships)
  * 2. Record object instances via `recordObject()` (with fields and relationship attachments)
- * 3. Publish tools via `publishTools()` (instance methods, static methods, global tools — with typed I/O)
+ * 3. Register sandbox-scoped effects via `granular.registerEffect()` / `granular.registerEffects()`
  * 4. Submit jobs via `submitJob()` that import auto-generated typed classes from `./sandbox-tools`
  * 5. Execute GraphQL queries via `graphql()` (authenticated automatically)
- * 6. List available tools via `getTools()` and listen for updates via `onToolsChanged()`
+ * 6. List available effects via `getEffects()` and listen for updates via `onEffectsChanged()`
  *
  * Tool calls from the sandbox automatically invoke your handlers via reverse-RPC.
  *
@@ -325,6 +251,15 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    private getRuntimeBaseUrl;
+    /**
+     * Close the session and disconnect from the sandbox.
+     *
+     * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
+     * to the runtime goodbye endpoint if no definitive WS-side runtime notify
+     * acknowledgement was observed.
+     */
+    disconnect(): Promise<void>;
     /** The last known graph container status, updated by checkReadiness() or on heartbeat */
     graphContainerStatus: {
         lastKeepAliveAt: number;
@@ -575,64 +510,23 @@ declare class Environment extends Session {
      */
     recordObject(options: RecordObjectOptions): Promise<RecordObjectResult>;
     /**
-     * Convenience method: publish tools and get back wrapped result.
-     * This is the main entry point for setting up tools.
-     *
-     * @example
-     * ```typescript
-     * const tools = [
-     *   {
-     *     name: 'get_weather',
-     *     description: 'Get weather for a city',
-     *     inputSchema: { type: 'object', properties: { city: { type: 'string' } } },
-     *     handler: async ({ city }) => ({ temp: 22 }),
-     *   },
-     * ];
-     *
-     * const { domainRevision } = await environment.publishTools(tools);
-     *
-     * // Now submit jobs that use those tools
-     * const job = await environment.submitJob(`
-     *   import { Author } from './sandbox-tools';
-     *   const weather = await Author.get_weather({ city: 'Paris' });
-     *   return weather;
-     * `);
-     *
-     * const result = await job.result;
-     * ```
+     * Removed: environment-scoped effect publication is no longer supported.
      */
     publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
     /**
-     * Publish a single effect (tool) incrementally.
-     *
-     * Adds the effect to the local registry and re-publishes the
-     * full tool catalog to the server. If an effect with the same
-     * name already exists, it is replaced.
-     *
-     * @example
-     * ```typescript
-     * await env.publishEffect({
-     *   name: 'get_bio',
-     *   description: 'Get biography',
-     *   inputSchema: { type: 'object', properties: { detailed: { type: 'boolean' } } },
-     *   handler: async (params) => ({ bio: 'Hello' }),
-     * });
-     * ```
+     * Removed: environment-scoped effect publication is no longer supported.
      */
     publishEffect(effect: ToolWithHandler): Promise<PublishToolsResult>;
     /**
-     * Publish multiple effects (tools) at once.
-     *
-     * Adds all effects to the local registry and re-publishes the
-     * full tool catalog in a single RPC call.
+     * Removed: environment-scoped effect publication is no longer supported.
      */
     publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
     /**
-     * Remove an effect by name and re-publish the remaining catalog.
+     * Removed: environment-scoped effect publication is no longer supported.
      */
     unpublishEffect(name: string): Promise<PublishToolsResult>;
     /**
-     * Remove all effects and publish an empty catalog.
+     * Removed: environment-scoped effect publication is no longer supported.
      */
     unpublishAllEffects(): Promise<PublishToolsResult>;
 }
@@ -640,13 +534,16 @@ declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private tokenProvider?;
     private WebSocketCtor?;
     private onUnexpectedClose?;
     private onReconnectError?;
-    /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
+    /** Sandbox-level effect registry: sandboxId → (effectKey → ToolWithHandler) */
     private sandboxEffects;
-    /** Active environments tracker: sandboxId → Environment[] */
-    private activeEnvironments;
+    /** Live sandbox-scoped effect hosts keyed by sandboxId */
+    private sandboxEffectHosts;
+    /** In-flight host connection promises to avoid duplicate concurrent connects */
+    private sandboxEffectHostPromises;
     /**
      * Create a new Granular client
      * @param options - Client configuration
@@ -671,8 +568,9 @@ declare class Granular {
     /**
      * Connect to a sandbox and establish a real-time environment session.
      *
-     * After connecting, use `environment.publishTools()` to register tools,
-     * then `environment.submitJob()` to execute code that uses those tools.
+     * Effects are registered at the sandbox level via `granular.registerEffect()`
+     * or `granular.registerEffects()`. Sessions pick up live availability from
+     * the sandbox registry automatically.
      *
      * @param options - Connection options
      * @returns An active environment session
@@ -689,10 +587,12 @@ declare class Granular {
      *   user,
      * });
      *
-     * // Publish tools
-     * await environment.publishTools([
-     *   { name: 'greet', description: 'Say hello', inputSchema: {}, handler: async () => 'Hello!' },
-     * ]);
+     * await granular.registerEffect('my-sandbox', {
+     *   name: 'greet',
+     *   description: 'Say hello',
+     *   inputSchema: { type: 'object', properties: {} },
+     *   handler: async () => 'Hello!',
+     * });
      *
      * // Submit job
      * const job = await environment.submitJob(`
@@ -704,13 +604,19 @@ declare class Granular {
      * ```
      */
     connect(options: ConnectOptions): Promise<Environment>;
+    private activateEnvironment;
+    private getSandboxEffectMap;
+    private serializeEffect;
+    private publishSandboxEffectCatalog;
+    private syncSandboxEffectCatalog;
+    private startEffectHostHeartbeat;
+    private stopEffectHostHeartbeat;
+    private synchronizeEffectHost;
+    private ensureSandboxEffectHost;
+    private disconnectSandboxEffectHost;
     /**
      * Register an effect (tool) for a specific sandbox.
      *
-     * The effect will be automatically published to:
-     * 1. Any currently active environments for this sandbox
-     * 2. Any new environments created/connected for this sandbox
-     *
      * @param sandboxNameOrId - The name or ID of the sandbox
      * @param effect - The tool definition and handler
      */
@@ -724,8 +630,8 @@ declare class Granular {
     /**
      * Unregister an effect from a sandbox.
      *
-     * Removes it from the local registry and unpublishes it from
-     * all active environments.
+     * Removes it from the local sandbox registry and updates the
+     * sandbox-scoped live catalog.
      */
     unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
     /**
@@ -798,4 +704,4 @@ declare class Granular {
     private request;
 }
 
-export { AssignmentListResponse, ConnectOptions, CreateEnvironmentData, CreatePermissionProfileData, CreateSandboxData, DefineRelationshipOptions, DeleteResponse, DomainState, 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 { 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 };