@granular-software/sdk 0.2.0 → 0.3.1

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as Automerge from '@automerge/automerge';
-import { Doc } from '@automerge/automerge';
-import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, b as GraphQLResult, c as DefineRelationshipOptions, d as RelationshipInfo, M as ModelRef, e as ManifestContent, f as RecordObjectOptions, g as RecordObjectResult, S as SandboxListResponse, h as Sandbox, i as CreateSandboxData, j as DeleteResponse, k as PermissionProfile, l as CreatePermissionProfileData, m as CreateEnvironmentData, n as Subject, A as AssignmentListResponse } from './types-D46q5WTh.mjs';
-export { $ as APIError, r as Assignment, w as Build, x as BuildListResponse, B as BuildPolicy, v as BuildStatus, s as EnvironmentListResponse, y as JobStatus, z as JobSubmitResult, t as Manifest, Z as ManifestImport, u as ManifestListResponse, Y as ManifestOperation, V as ManifestPropertySpec, X as ManifestRelationshipDef, _ as ManifestVolume, q as PermissionProfileListResponse, p as PermissionRules, F as Prompt, H as RPCRequest, N as RPCRequestFromServer, K as RPCResponse, L as SyncMessage, O as ToolInvokeParams, Q as ToolResultParams, o as ToolSchema } from './types-D46q5WTh.mjs';
+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-CnX4jXYQ.mjs';
+export { a2 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, a0 as ManifestImport, x as ManifestListResponse, $ as ManifestOperation, Z as ManifestPropertySpec, _ as ManifestRelationshipDef, a1 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, N as RPCRequest, V as RPCRequestFromServer, O as RPCResponse, Q as SyncMessage, X as ToolInvokeParams, Y as ToolResultParams, q as ToolSchema } from './types-CnX4jXYQ.mjs';
+import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
     private ws;
@@ -17,6 +17,7 @@ declare class WSClient {
     private syncState;
     private reconnectTimer;
     private isExplicitlyDisconnected;
+    private options;
     constructor(options: WSClientOptions);
     /**
      * Connect to the WebSocket server
@@ -73,6 +74,10 @@ declare class Session {
     /** Tracks which tools are instance methods (className set, not static) */
     private instanceTools;
     private currentDomainRevision;
+    /** Local effect registry: name → full ToolWithHandler */
+    private effects;
+    /** Last known tools for diffing */
+    private lastKnownTools;
     constructor(client: WSClient, clientId?: string);
     get document(): Doc<Record<string, unknown>>;
     get domainRevision(): string | null;
@@ -102,6 +107,10 @@ declare class Session {
         ok: boolean;
         environmentId?: string;
         docId?: string;
+        graphContainerStatus?: {
+            lastKeepAliveAt: number;
+            status: 'warming' | 'hot' | 'unknown';
+        };
     }>;
     /**
      * Publish tools to the sandbox and register handlers for reverse-RPC.
@@ -140,6 +149,64 @@ declare class Session {
      * ```
      */
     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.
      *
@@ -166,26 +233,35 @@ declare class Session {
      * Respond to a prompt request from the sandbox
      */
     answerPrompt(promptId: string, answer: unknown): Promise<void>;
+    /**
+     * Get the current list of available tools.
+     * Consolidates tools from all connected clients.
+     */
+    getTools(): ToolInfo[];
+    /**
+     * Subscribe to tool changes (added, removed, updated).
+     * @param callback - Function called with change events
+     * @returns Unsubscribe function
+     */
+    onToolsChanged(callback: (event: ToolsChangedEvent) => void): () => void;
     /**
      * Get the current domain state and available tools
      */
     getDomain(): Promise<DomainState>;
     /**
-     * Get auto-generated TypeScript class declarations for the current domain.
-     *
-     * Returns typed declarations including:
-     * - Classes with readonly properties (from manifest)
-     * - `static find(query: { id: string })` for each class
-     * - Instance methods with typed input/output (from `publishTools` with `className`)
-     * - Static methods (from `publishTools` with `className` + `static: true`)
-     * - Relationship accessors (`get_books()`, `get_author()`, etc.)
-     * - Global tool functions (from `publishTools` without `className`)
-     *
-     * Pass this documentation to LLMs so they can write correct typed code
-     * that imports from `./sandbox-tools`.
-     *
-     * Falls back to generating markdown docs from the domain summary if
-     * the synthesis server is unavailable.
+     * Fetch a domain package part from the backend (no fallback).
+     */
+    private fetchDomainPart;
+    /**
+     * Get TypeScript class declarations for the current domain (for LLM/code gen).
+     */
+    getDomainTypes(): Promise<string>;
+    /**
+     * Get Markdown documentation for the current domain (human-readable).
+     */
+    getDomainDocs(): Promise<string>;
+    /**
+     * Get domain documentation for LLMs. Returns types (preferred) or fallback.
      */
     getDomainDocumentation(): Promise<string>;
     /**
@@ -207,7 +283,11 @@ declare class Session {
     off(event: string, handler: (data: unknown) => void): void;
     private setupToolInvokeHandler;
     private setupEventHandlers;
-    private emit;
+    protected emit(event: string, data: unknown): void;
+    /**
+     * Check for changes in the tool catalog and emit 'tools:changed' if needed
+     */
+    private checkForToolChanges;
 }
 
 /**
@@ -219,6 +299,7 @@ declare class Session {
  * 3. Publish tools via `publishTools()` (instance methods, static methods, global tools — with typed I/O)
  * 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()`
  *
  * Tool calls from the sandbox automatically invoke your handlers via reverse-RPC.
  *
@@ -241,6 +322,39 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+    graphContainerStatus: {
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    } | null;
+    /**
+     * Check if the graph container is ready and warm.
+     *
+     * Sends a lightweight heartbeat RPC to the Session DO which internally
+     * pings the FalkorDB container. The response includes `graphContainerStatus`,
+     * which is stored locally and emitted as a `readiness` event.
+     *
+     * Use this method to proactively warm the graph container before any
+     * GraphQL query that requires it, or to poll the container's state in
+     * the background.
+     *
+     * @returns The current graph container status object
+     *
+     * @example
+     * ```typescript
+     * const status = await env.checkReadiness();
+     * console.log(status.status); // 'hot' | 'warming' | 'unknown'
+     *
+     * // Or listen for live updates
+     * env.on('readiness', (status) => {
+     *   console.log('Graph is now:', status.status);
+     * });
+     * ```
+     */
+    checkReadiness(): Promise<{
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    }>;
     /**
      * Convert a class name + real-world ID into a unique graph path.
      *
@@ -485,11 +599,49 @@ declare class Environment extends Session {
      * ```
      */
     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' }),
+     * });
+     * ```
+     */
+    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.
+     */
+    publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
+    /**
+     * Remove an effect by name and re-publish the remaining catalog.
+     */
+    unpublishEffect(name: string): Promise<PublishToolsResult>;
+    /**
+     * Remove all effects and publish an empty catalog.
+     */
+    unpublishAllEffects(): Promise<PublishToolsResult>;
 }
 declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private WebSocketCtor?;
+    /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
+    private sandboxEffects;
+    /** Active environments tracker: sandboxId → Environment[] */
+    private activeEnvironments;
     /**
      * Create a new Granular client
      * @param options - Client configuration
@@ -547,6 +699,34 @@ declare class Granular {
      * ```
      */
     connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * 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
+     */
+    registerEffect(sandboxNameOrId: string, effect: ToolWithHandler): Promise<void>;
+    /**
+     * Register multiple effects (tools) for a specific sandbox.
+     *
+     * batch version of `registerEffect`.
+     */
+    registerEffects(sandboxNameOrId: string, effects: ToolWithHandler[]): Promise<void>;
+    /**
+     * Unregister an effect from a sandbox.
+     *
+     * Removes it from the local registry and unpublishes it from
+     * all active environments.
+     */
+    unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * Unregister all effects for a sandbox.
+     */
+    unregisterAllEffects(sandboxNameOrId: string): Promise<void>;
     /**
      * Find a sandbox by name or create it if it doesn't exist
      */
@@ -613,4 +793,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, ToolWithHandler, User, WSClient, WSClientOptions };
+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 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as Automerge from '@automerge/automerge';
-import { Doc } from '@automerge/automerge';
-import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, b as GraphQLResult, c as DefineRelationshipOptions, d as RelationshipInfo, M as ModelRef, e as ManifestContent, f as RecordObjectOptions, g as RecordObjectResult, S as SandboxListResponse, h as Sandbox, i as CreateSandboxData, j as DeleteResponse, k as PermissionProfile, l as CreatePermissionProfileData, m as CreateEnvironmentData, n as Subject, A as AssignmentListResponse } from './types-D46q5WTh.js';
-export { $ as APIError, r as Assignment, w as Build, x as BuildListResponse, B as BuildPolicy, v as BuildStatus, s as EnvironmentListResponse, y as JobStatus, z as JobSubmitResult, t as Manifest, Z as ManifestImport, u as ManifestListResponse, Y as ManifestOperation, V as ManifestPropertySpec, X as ManifestRelationshipDef, _ as ManifestVolume, q as PermissionProfileListResponse, p as PermissionRules, F as Prompt, H as RPCRequest, N as RPCRequestFromServer, K as RPCResponse, L as SyncMessage, O as ToolInvokeParams, Q as ToolResultParams, o as ToolSchema } from './types-D46q5WTh.js';
+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-CnX4jXYQ.js';
+export { a2 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, a0 as ManifestImport, x as ManifestListResponse, $ as ManifestOperation, Z as ManifestPropertySpec, _ as ManifestRelationshipDef, a1 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, N as RPCRequest, V as RPCRequestFromServer, O as RPCResponse, Q as SyncMessage, X as ToolInvokeParams, Y as ToolResultParams, q as ToolSchema } from './types-CnX4jXYQ.js';
+import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
     private ws;
@@ -17,6 +17,7 @@ declare class WSClient {
     private syncState;
     private reconnectTimer;
     private isExplicitlyDisconnected;
+    private options;
     constructor(options: WSClientOptions);
     /**
      * Connect to the WebSocket server
@@ -73,6 +74,10 @@ declare class Session {
     /** Tracks which tools are instance methods (className set, not static) */
     private instanceTools;
     private currentDomainRevision;
+    /** Local effect registry: name → full ToolWithHandler */
+    private effects;
+    /** Last known tools for diffing */
+    private lastKnownTools;
     constructor(client: WSClient, clientId?: string);
     get document(): Doc<Record<string, unknown>>;
     get domainRevision(): string | null;
@@ -102,6 +107,10 @@ declare class Session {
         ok: boolean;
         environmentId?: string;
         docId?: string;
+        graphContainerStatus?: {
+            lastKeepAliveAt: number;
+            status: 'warming' | 'hot' | 'unknown';
+        };
     }>;
     /**
      * Publish tools to the sandbox and register handlers for reverse-RPC.
@@ -140,6 +149,64 @@ declare class Session {
      * ```
      */
     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.
      *
@@ -166,26 +233,35 @@ declare class Session {
      * Respond to a prompt request from the sandbox
      */
     answerPrompt(promptId: string, answer: unknown): Promise<void>;
+    /**
+     * Get the current list of available tools.
+     * Consolidates tools from all connected clients.
+     */
+    getTools(): ToolInfo[];
+    /**
+     * Subscribe to tool changes (added, removed, updated).
+     * @param callback - Function called with change events
+     * @returns Unsubscribe function
+     */
+    onToolsChanged(callback: (event: ToolsChangedEvent) => void): () => void;
     /**
      * Get the current domain state and available tools
      */
     getDomain(): Promise<DomainState>;
     /**
-     * Get auto-generated TypeScript class declarations for the current domain.
-     *
-     * Returns typed declarations including:
-     * - Classes with readonly properties (from manifest)
-     * - `static find(query: { id: string })` for each class
-     * - Instance methods with typed input/output (from `publishTools` with `className`)
-     * - Static methods (from `publishTools` with `className` + `static: true`)
-     * - Relationship accessors (`get_books()`, `get_author()`, etc.)
-     * - Global tool functions (from `publishTools` without `className`)
-     *
-     * Pass this documentation to LLMs so they can write correct typed code
-     * that imports from `./sandbox-tools`.
-     *
-     * Falls back to generating markdown docs from the domain summary if
-     * the synthesis server is unavailable.
+     * Fetch a domain package part from the backend (no fallback).
+     */
+    private fetchDomainPart;
+    /**
+     * Get TypeScript class declarations for the current domain (for LLM/code gen).
+     */
+    getDomainTypes(): Promise<string>;
+    /**
+     * Get Markdown documentation for the current domain (human-readable).
+     */
+    getDomainDocs(): Promise<string>;
+    /**
+     * Get domain documentation for LLMs. Returns types (preferred) or fallback.
      */
     getDomainDocumentation(): Promise<string>;
     /**
@@ -207,7 +283,11 @@ declare class Session {
     off(event: string, handler: (data: unknown) => void): void;
     private setupToolInvokeHandler;
     private setupEventHandlers;
-    private emit;
+    protected emit(event: string, data: unknown): void;
+    /**
+     * Check for changes in the tool catalog and emit 'tools:changed' if needed
+     */
+    private checkForToolChanges;
 }
 
 /**
@@ -219,6 +299,7 @@ declare class Session {
  * 3. Publish tools via `publishTools()` (instance methods, static methods, global tools — with typed I/O)
  * 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()`
  *
  * Tool calls from the sandbox automatically invoke your handlers via reverse-RPC.
  *
@@ -241,6 +322,39 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+    graphContainerStatus: {
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    } | null;
+    /**
+     * Check if the graph container is ready and warm.
+     *
+     * Sends a lightweight heartbeat RPC to the Session DO which internally
+     * pings the FalkorDB container. The response includes `graphContainerStatus`,
+     * which is stored locally and emitted as a `readiness` event.
+     *
+     * Use this method to proactively warm the graph container before any
+     * GraphQL query that requires it, or to poll the container's state in
+     * the background.
+     *
+     * @returns The current graph container status object
+     *
+     * @example
+     * ```typescript
+     * const status = await env.checkReadiness();
+     * console.log(status.status); // 'hot' | 'warming' | 'unknown'
+     *
+     * // Or listen for live updates
+     * env.on('readiness', (status) => {
+     *   console.log('Graph is now:', status.status);
+     * });
+     * ```
+     */
+    checkReadiness(): Promise<{
+        lastKeepAliveAt: number;
+        status: 'warming' | 'hot' | 'unknown';
+    }>;
     /**
      * Convert a class name + real-world ID into a unique graph path.
      *
@@ -485,11 +599,49 @@ declare class Environment extends Session {
      * ```
      */
     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' }),
+     * });
+     * ```
+     */
+    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.
+     */
+    publishEffects(effects: ToolWithHandler[]): Promise<PublishToolsResult>;
+    /**
+     * Remove an effect by name and re-publish the remaining catalog.
+     */
+    unpublishEffect(name: string): Promise<PublishToolsResult>;
+    /**
+     * Remove all effects and publish an empty catalog.
+     */
+    unpublishAllEffects(): Promise<PublishToolsResult>;
 }
 declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private WebSocketCtor?;
+    /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
+    private sandboxEffects;
+    /** Active environments tracker: sandboxId → Environment[] */
+    private activeEnvironments;
     /**
      * Create a new Granular client
      * @param options - Client configuration
@@ -547,6 +699,34 @@ declare class Granular {
      * ```
      */
     connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * 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
+     */
+    registerEffect(sandboxNameOrId: string, effect: ToolWithHandler): Promise<void>;
+    /**
+     * Register multiple effects (tools) for a specific sandbox.
+     *
+     * batch version of `registerEffect`.
+     */
+    registerEffects(sandboxNameOrId: string, effects: ToolWithHandler[]): Promise<void>;
+    /**
+     * Unregister an effect from a sandbox.
+     *
+     * Removes it from the local registry and unpublishes it from
+     * all active environments.
+     */
+    unregisterEffect(sandboxNameOrId: string, name: string): Promise<void>;
+    /**
+     * Unregister all effects for a sandbox.
+     */
+    unregisterAllEffects(sandboxNameOrId: string): Promise<void>;
     /**
      * Find a sandbox by name or create it if it doesn't exist
      */
@@ -613,4 +793,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, ToolWithHandler, User, WSClient, WSClientOptions };
+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 };