@granular-software/sdk 0.4.1 → 0.4.2

package/dist/index.js

@@ -4488,6 +4488,17 @@ var Session = class {
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
   }
+  buildLegacyEffectContext() {
+    return {
+      effectClientId: this.clientId,
+      sandboxId: "",
+      environmentId: "",
+      sessionId: "",
+      user: {
+        subjectId: ""
+      }
+    };
+  }
   // --- Public API ---
   get document() {
     return this.client.doc;
@@ -4526,155 +4537,30 @@ var Session = class {
     });
     return result;
   }
-  /**
-   * 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}` }),
-   *   },
-   * ]);
-   * ```
-   */
   async publishTools(tools, revision = "1.0.0") {
-    const schemas = tools.map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      inputSchema: tool.inputSchema,
-      outputSchema: tool.outputSchema,
-      stability: tool.stability || "stable",
-      provenance: tool.provenance || { source: "mcp" },
-      tags: tool.tags,
-      className: tool.className,
-      static: tool.static
-    }));
-    const result = await this.client.call("client.publishRawToolCatalog", {
-      clientId: this.clientId,
-      revision,
-      tools: schemas
-    });
-    if (!result.accepted || !result.domainRevision) {
-      throw new Error(`Failed to publish tools: ${JSON.stringify(result.rejected)}`);
-    }
-    for (const tool of tools) {
-      this.toolHandlers.set(tool.name, tool.handler);
-      if (tool.className && !tool.static) {
-        this.instanceTools.add(tool.name);
-      } else {
-        this.instanceTools.delete(tool.name);
-      }
-    }
-    this.currentDomainRevision = result.domainRevision;
-    return {
-      accepted: result.accepted,
-      domainRevision: result.domainRevision,
-      rejected: result.rejected
-    };
+    throw new Error(
+      "Environment-scoped effect publication was removed. Declare effects in the manifest and register live handlers with granular.registerEffects(environment.sandboxId, effects)."
+    );
   }
-  /**
-   * 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}` }),
-   * });
-   * ```
-   */
   async publishEffect(effect) {
-    this.effects.set(effect.name, effect);
-    return this._syncEffects();
+    throw new Error(
+      "Environment-scoped effect publication was removed. Use granular.registerEffect(environment.sandboxId, effect)."
+    );
   }
-  /**
-   * 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) => ({}) },
-   * ]);
-   * ```
-   */
   async publishEffects(effects) {
-    for (const effect of effects) {
-      this.effects.set(effect.name, effect);
-    }
-    return this._syncEffects();
+    throw new Error(
+      "Environment-scoped effect publication was removed. Use granular.registerEffects(environment.sandboxId, effects)."
+    );
   }
-  /**
-   * Remove an effect by name and re-publish the remaining catalog.
-   *
-   * @param name - The name of the effect to remove
-   * @returns PublishToolsResult with domainRevision
-   */
   async unpublishEffect(name) {
-    this.effects.delete(name);
-    this.toolHandlers.delete(name);
-    this.instanceTools.delete(name);
-    return this._syncEffects();
+    throw new Error(
+      "Environment-scoped effect publication was removed. Use granular.unregisterEffect(environment.sandboxId, effectName)."
+    );
   }
-  /**
-   * Remove all effects and publish an empty catalog.
-   *
-   * @returns PublishToolsResult with domainRevision
-   */
   async unpublishAllEffects() {
-    this.effects.clear();
-    this.toolHandlers.clear();
-    this.instanceTools.clear();
-    return this._syncEffects();
-  }
-  /**
-   * Internal: re-publish the full effect catalog to the server.
-   * Called after any mutation to the effects Map.
-   */
-  async _syncEffects() {
-    const allEffects = Array.from(this.effects.values());
-    return this.publishTools(allEffects);
+    throw new Error(
+      "Environment-scoped effect publication was removed. Use granular.unregisterAllEffects(environment.sandboxId)."
+    );
   }
   /**
    * Submit a job to execute code in the sandbox.
@@ -4688,14 +4574,14 @@ var Session = class {
    * 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.
    */
   async submitJob(code, domainRevision) {
     const revision = domainRevision || this.currentDomainRevision || this.client.doc?.domain?.active || void 0;
     if (!revision) {
-      throw new Error("No domain revision available. Call publishTools() or ensure schema is activated.");
+      throw new Error("No domain revision available. Register live effects or ensure the build schema is activated.");
     }
     const result = await this.client.call("job.submit", {
       domainRevision: revision,
@@ -4727,10 +4613,10 @@ var Session = class {
     await this.client.call("prompt.answer", { promptId, value: answer });
   }
   /**
-   * 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.
    */
-  getTools() {
+  getEffects() {
     const doc = this.client.doc;
     const toolMap = /* @__PURE__ */ new Map();
     const domainPkg = doc.domain?.packages?.domain;
@@ -4775,10 +4661,32 @@ var Session = class {
     return Array.from(toolMap.values());
   }
   /**
-   * Subscribe to tool changes (added, removed, updated).
+   * Backwards-compatible alias for `getEffects()`.
+   */
+  getTools() {
+    return this.getEffects();
+  }
+  /**
+   * Subscribe to effect changes (added, removed, updated).
    * @param callback - Function called with change events
    * @returns Unsubscribe function
    */
+  onEffectsChanged(callback) {
+    const handler = (data) => callback(data);
+    if (!this.eventListeners.has("effects:changed")) {
+      this.eventListeners.set("effects:changed", []);
+    }
+    this.eventListeners.get("effects:changed").push(handler);
+    return () => {
+      const listeners = this.eventListeners.get("effects:changed");
+      if (listeners) {
+        this.eventListeners.set("effects:changed", listeners.filter((h) => h !== handler));
+      }
+    };
+  }
+  /**
+   * Backwards-compatible alias for `onEffectsChanged()`.
+   */
   onToolsChanged(callback) {
     const handler = (data) => callback(data);
     if (!this.eventListeners.has("tools:changed")) {
@@ -4891,7 +4799,7 @@ import { ${allImports} } from "./sandbox-tools";
         }
       }
       if (globalTools && globalTools.length > 0) {
-        docs2 += "## Global Tools\n\n";
+        docs2 += "## Global Effects\n\n";
         for (const tool of globalTools) {
           docs2 += `### ${tool.name}
 
@@ -4909,10 +4817,10 @@ import { ${allImports} } from "./sandbox-tools";
       return docs2;
     }
     if (!tools || tools.length === 0) {
-      return "No tools available in this domain.";
+      return "No effects available in this domain.";
     }
-    let docs = "# Available Tools\n\n";
-    docs += "Import tools from `./sandbox-tools` and call them with await:\n\n";
+    let docs = "# Available Effects\n\n";
+    docs += "Import effects from `./sandbox-tools` and call them with await:\n\n";
     docs += '```typescript\nimport { tools } from "./sandbox-tools";\n\n';
     docs += "// Example:\n";
     docs += `const result = await tools.${tools[0]?.name || "example"}(input);
@@ -4976,6 +4884,7 @@ import { ${allImports} } from "./sandbox-tools";
   setupToolInvokeHandler() {
     this.client.registerRpcHandler("tool.invoke", async (params) => {
       const { callId, toolName, input } = params;
+      this.emit("effect:invoke", { callId, effectKey: toolName, toolName, input });
       this.emit("tool:invoke", { callId, toolName, input });
       const handler = this.toolHandlers.get(toolName);
       if (!handler) {
@@ -4987,12 +4896,14 @@ import { ${allImports} } from "./sandbox-tools";
       }
       try {
         let result;
+        const invocationContext = this.buildLegacyEffectContext();
         if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
           const { _objectId, ...restParams } = input;
-          result = await handler(_objectId, restParams);
+          result = await handler(_objectId, restParams, invocationContext);
         } else {
-          result = await handler(input);
+          result = await handler(input, invocationContext);
         }
+        this.emit("effect:result", { callId, effectKey: toolName, result });
         this.emit("tool:result", { callId, result });
         await this.client.call("tool.result", {
           callId,
@@ -5000,6 +4911,7 @@ import { ${allImports} } from "./sandbox-tools";
         });
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        this.emit("effect:result", { callId, effectKey: toolName, error: errorMessage });
         this.emit("tool:result", { callId, error: errorMessage });
         await this.client.call("tool.result", {
           callId,
@@ -5032,10 +4944,10 @@ import { ${allImports} } from "./sandbox-tools";
     }
   }
   /**
-   * 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.
    */
   checkForToolChanges() {
-    const currentTools = this.getTools();
+    const currentTools = this.getEffects();
     const currentMap = new Map(currentTools.map((t) => [t.name, t]));
     const added = [];
     const removed = [];
@@ -5051,6 +4963,12 @@ import { ${allImports} } from "./sandbox-tools";
     }
     if (added.length > 0 || removed.length > 0) {
       this.lastKnownTools = currentMap;
+      this.emit("effects:changed", {
+        effects: currentTools,
+        tools: currentTools,
+        added,
+        removed
+      });
       this.emit("tools:changed", {
         tools: currentTools,
         added,
@@ -5219,6 +5137,37 @@ var STANDARD_MODULES_OPERATIONS = [
 var BUILTIN_MODULES = {
   "standard_modules": STANDARD_MODULES_OPERATIONS
 };
+function computeEffectKey(effect) {
+  const attachedClass = effect.className?.trim();
+  if (!attachedClass) {
+    return `global:${effect.name}`;
+  }
+  return effect.static ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}`;
+}
+function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
+  const url = new URL(apiUrl);
+  if (url.pathname.endsWith("/granular/ws/connect")) {
+    url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
+  } else if (url.pathname.endsWith("/granular")) {
+    url.pathname = `${url.pathname.replace(/\/$/, "")}/effects/connect`;
+  } else if (url.pathname.endsWith("/v2/ws/connect")) {
+    url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
+  } else if (url.pathname.endsWith("/v2/ws")) {
+    url.pathname = url.pathname.replace(/\/ws$/, "/effects/connect");
+  } else if (url.pathname.endsWith("/ws/connect")) {
+    url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
+  } else if (url.pathname.endsWith("/ws")) {
+    url.pathname = url.pathname.replace(/\/ws$/, "/effects/connect");
+  } else {
+    url.pathname = "/granular/effects/connect";
+  }
+  url.search = "";
+  url.hash = "";
+  url.searchParams.set("sandboxId", sandboxId);
+  url.searchParams.set("effectClientId", effectClientId);
+  url.searchParams.set("clientId", clientId);
+  return url.toString();
+}
 var Environment = class _Environment extends Session {
   envData;
   _apiKey;
@@ -5963,72 +5912,31 @@ var Environment = class _Environment extends Session {
   }
   // ==================== PUBLISH TOOLS ====================
   /**
-   * 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.
    */
   async publishTools(tools, revision = "1.0.0") {
     return super.publishTools(tools, revision);
   }
   /**
-   * 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.
    */
   async publishEffect(effect) {
     return super.publishEffect(effect);
   }
   /**
-   * 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.
    */
   async publishEffects(effects) {
     return super.publishEffects(effects);
   }
   /**
-   * Remove an effect by name and re-publish the remaining catalog.
+   * Removed: environment-scoped effect publication is no longer supported.
    */
   async unpublishEffect(name) {
     return super.unpublishEffect(name);
   }
   /**
-   * Remove all effects and publish an empty catalog.
+   * Removed: environment-scoped effect publication is no longer supported.
    */
   async unpublishAllEffects() {
     return super.unpublishAllEffects();
@@ -6042,10 +5950,12 @@ var Granular = class {
   WebSocketCtor;
   onUnexpectedClose;
   onReconnectError;
-  /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
+  /** Sandbox-level effect registry: sandboxId → (effectKey → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
-  /** Active environments tracker: sandboxId → Environment[] */
-  activeEnvironments = /* @__PURE__ */ new Map();
+  /** Live sandbox-scoped effect hosts keyed by sandboxId */
+  sandboxEffectHosts = /* @__PURE__ */ new Map();
+  /** In-flight host connection promises to avoid duplicate concurrent connects */
+  sandboxEffectHostPromises = /* @__PURE__ */ new Map();
   /**
    * Create a new Granular client
    * @param options - Client configuration
@@ -6098,8 +6008,9 @@ var Granular = class {
   /**
    * 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
@@ -6116,10 +6027,12 @@ var Granular = class {
    *   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(`
@@ -6141,10 +6054,18 @@ var Granular = class {
       subjectId: options.user.subjectId,
       permissionProfileId: null
     });
+    await this.activateEnvironment(envData.environmentId);
+    const session = await this.request("/ws/sessions", {
+      method: "POST",
+      body: JSON.stringify({
+        environmentId: envData.environmentId,
+        clientId
+      })
+    });
     const client = new WSClient({
-      url: this.apiUrl,
-      sessionId: envData.environmentId,
-      token: this.apiKey,
+      url: session.wsUrl,
+      sessionId: session.sessionId,
+      token: session.token,
       tokenProvider: this.tokenProvider,
       WebSocketCtor: this.WebSocketCtor,
       onUnexpectedClose: this.onUnexpectedClose,
@@ -6153,47 +6074,165 @@ var Granular = class {
     await client.connect();
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
     const environment = new Environment(client, envData, clientId, this.apiKey, graphqlEndpoint);
-    if (!this.activeEnvironments.has(sandbox.sandboxId)) {
-      this.activeEnvironments.set(sandbox.sandboxId, []);
-    }
-    this.activeEnvironments.get(sandbox.sandboxId).push(environment);
-    environment.on("disconnect", () => {
-      const list = this.activeEnvironments.get(sandbox.sandboxId);
-      if (list) {
-        this.activeEnvironments.set(sandbox.sandboxId, list.filter((e) => e !== environment));
-      }
-    });
     await environment.hello();
-    const effects = this.sandboxEffects.get(sandbox.sandboxId);
-    if (effects && effects.size > 0) {
-      const effectsList = Array.from(effects.values());
-      console.log(`[Granular] Auto-publishing ${effectsList.length} effects for sandbox ${sandbox.sandboxId}`);
-      await environment.publishEffects(effectsList);
-    }
     return environment;
   }
+  async activateEnvironment(environmentId) {
+    await this.request(`/orchestrator/runtime/environments/${environmentId}/activate`, {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+  }
   // ── Sandbox-Level Effects ──
+  getSandboxEffectMap(sandboxId) {
+    let effects = this.sandboxEffects.get(sandboxId);
+    if (!effects) {
+      effects = /* @__PURE__ */ new Map();
+      this.sandboxEffects.set(sandboxId, effects);
+    }
+    return effects;
+  }
+  serializeEffect(effect) {
+    return {
+      effectKey: computeEffectKey(effect),
+      name: effect.name,
+      description: effect.description,
+      inputSchema: effect.inputSchema,
+      outputSchema: effect.outputSchema,
+      stability: effect.stability || "stable",
+      provenance: effect.provenance || { source: "custom" },
+      tags: effect.tags,
+      className: effect.className,
+      static: effect.static
+    };
+  }
+  async publishSandboxEffectCatalog(host) {
+    const effects = Array.from(this.getSandboxEffectMap(host.sandboxId).values()).map(
+      (effect) => this.serializeEffect(effect)
+    );
+    await host.wsClient.call("effects.publishCatalog", { effects });
+  }
+  async syncSandboxEffectCatalog(sandboxId) {
+    const host = await this.ensureSandboxEffectHost(sandboxId);
+    await this.publishSandboxEffectCatalog(host);
+  }
+  startEffectHostHeartbeat(host) {
+    if (host.heartbeatTimer) {
+      clearInterval(host.heartbeatTimer);
+    }
+    host.wsClient.call("client.heartbeat", {}).catch((error) => {
+      console.warn(
+        `[Granular] Initial effect host heartbeat failed for sandbox ${host.sandboxId}:`,
+        error
+      );
+    });
+    host.heartbeatTimer = setInterval(() => {
+      host.wsClient.call("client.heartbeat", {}).catch((error) => {
+        console.warn(
+          `[Granular] Effect host heartbeat failed for sandbox ${host.sandboxId}:`,
+          error
+        );
+      });
+    }, 1e4);
+  }
+  stopEffectHostHeartbeat(host) {
+    if (!host?.heartbeatTimer) {
+      return;
+    }
+    clearInterval(host.heartbeatTimer);
+    host.heartbeatTimer = null;
+  }
+  async synchronizeEffectHost(host) {
+    await host.wsClient.call("client.hello", {
+      clientId: host.clientId,
+      protocolVersion: "2.0"
+    });
+    this.startEffectHostHeartbeat(host);
+    await this.publishSandboxEffectCatalog(host);
+  }
+  async ensureSandboxEffectHost(sandboxId) {
+    const existing = this.sandboxEffectHosts.get(sandboxId);
+    if (existing) {
+      return existing;
+    }
+    const inflight = this.sandboxEffectHostPromises.get(sandboxId);
+    if (inflight) {
+      return inflight;
+    }
+    const connectPromise = (async () => {
+      const effectClientId = crypto.randomUUID();
+      const clientId = `effect-host:${sandboxId}:${effectClientId}`;
+      const wsClient = new WSClient({
+        url: buildEffectHostUrl(this.apiUrl, sandboxId, effectClientId, clientId),
+        sessionId: `effect-host:${effectClientId}`,
+        token: this.apiKey,
+        tokenProvider: this.tokenProvider,
+        WebSocketCtor: this.WebSocketCtor,
+        onUnexpectedClose: this.onUnexpectedClose,
+        onReconnectError: this.onReconnectError
+      });
+      const host = {
+        sandboxId,
+        effectClientId,
+        clientId,
+        wsClient,
+        heartbeatTimer: null
+      };
+      wsClient.registerRpcHandler("effect.invoke", async (params) => {
+        const request = params;
+        const effect = this.getSandboxEffectMap(sandboxId).get(request.effectKey);
+        if (!effect) {
+          throw new Error(`Effect handler not found: ${request.effectKey}`);
+        }
+        if (effect.className && !effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
+          const { _objectId, ...rest } = request.input;
+          return effect.handler(_objectId, rest, request.context);
+        }
+        return effect.handler(request.input, request.context);
+      });
+      wsClient.on("open", () => {
+        void this.synchronizeEffectHost(host).catch((error) => {
+          console.error(
+            `[Granular] Failed to re-sync effect host for sandbox ${sandboxId}:`,
+            error
+          );
+        });
+      });
+      wsClient.on("disconnect", () => {
+        this.stopEffectHostHeartbeat(host);
+      });
+      await wsClient.connect();
+      await this.synchronizeEffectHost(host);
+      this.sandboxEffectHosts.set(sandboxId, host);
+      return host;
+    })();
+    this.sandboxEffectHostPromises.set(sandboxId, connectPromise);
+    try {
+      return await connectPromise;
+    } finally {
+      this.sandboxEffectHostPromises.delete(sandboxId);
+    }
+  }
+  disconnectSandboxEffectHost(sandboxId) {
+    const host = this.sandboxEffectHosts.get(sandboxId);
+    if (!host) {
+      return;
+    }
+    this.stopEffectHostHeartbeat(host);
+    host.wsClient.disconnect();
+    this.sandboxEffectHosts.delete(sandboxId);
+  }
   /**
    * 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
    */
   async registerEffect(sandboxNameOrId, effect) {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
-    if (!this.sandboxEffects.has(sandboxId)) {
-      this.sandboxEffects.set(sandboxId, /* @__PURE__ */ new Map());
-    }
-    this.sandboxEffects.get(sandboxId).set(effect.name, effect);
-    const activeEnvs = this.activeEnvironments.get(sandboxId) || [];
-    for (const env of activeEnvs) {
-      await env.publishEffect(effect);
-    }
+    this.getSandboxEffectMap(sandboxId).set(computeEffectKey(effect), effect);
+    await this.syncSandboxEffectCatalog(sandboxId);
   }
   /**
    * Register multiple effects (tools) for a specific sandbox.
@@ -6203,35 +6242,39 @@ var Granular = class {
   async registerEffects(sandboxNameOrId, effects) {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
-    if (!this.sandboxEffects.has(sandboxId)) {
-      this.sandboxEffects.set(sandboxId, /* @__PURE__ */ new Map());
-    }
-    const map = this.sandboxEffects.get(sandboxId);
+    const map = this.getSandboxEffectMap(sandboxId);
     for (const effect of effects) {
-      map.set(effect.name, effect);
-    }
-    const activeEnvs = this.activeEnvironments.get(sandboxId) || [];
-    for (const env of activeEnvs) {
-      await env.publishEffects(effects);
+      map.set(computeEffectKey(effect), effect);
     }
+    await this.syncSandboxEffectCatalog(sandboxId);
   }
   /**
    * 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.
    */
   async unregisterEffect(sandboxNameOrId, name) {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
-    const map = this.sandboxEffects.get(sandboxId);
-    if (map) {
-      map.delete(name);
+    const currentMap = this.sandboxEffects.get(sandboxId);
+    if (!currentMap) {
+      return;
     }
-    const activeEnvs = this.activeEnvironments.get(sandboxId) || [];
-    for (const env of activeEnvs) {
-      await env.unpublishEffect(name);
+    const nextEntries = Array.from(currentMap.entries()).filter(
+      ([effectKey, effect]) => effectKey !== name && effect.name !== name
+    );
+    if (nextEntries.length === currentMap.size) {
+      return;
+    }
+    const nextMap = new Map(nextEntries);
+    this.sandboxEffects.set(sandboxId, nextMap);
+    if (nextMap.size === 0) {
+      this.disconnectSandboxEffectHost(sandboxId);
+      this.sandboxEffects.delete(sandboxId);
+      return;
     }
+    await this.syncSandboxEffectCatalog(sandboxId);
   }
   /**
    * Unregister all effects for a sandbox.
@@ -6240,10 +6283,7 @@ var Granular = class {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
     this.sandboxEffects.delete(sandboxId);
-    const activeEnvs = this.activeEnvironments.get(sandboxId) || [];
-    for (const env of activeEnvs) {
-      await env.unpublishAllEffects();
-    }
+    this.disconnectSandboxEffectHost(sandboxId);
   }
   /**
    * Find a sandbox by name or create it if it doesn't exist
@@ -6279,7 +6319,7 @@ var Granular = class {
     const created = await this.permissionProfiles.create(sandboxId, {
       name: profileName,
       rules: {
-        tools: { allow: ["*"] },
+        effects: { allow: ["*"] },
         resources: { allow: ["*"] }
       }
     });