@granular-software/sdk 0.3.4 → 0.4.2

package/dist/index.js

@@ -3939,6 +3939,9 @@ if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
   GlobalWebSocket = globalThis.WebSocket;
 }
 var READY_STATE_OPEN = 1;
+var TOKEN_REFRESH_LEEWAY_MS = 2 * 60 * 1e3;
+var TOKEN_REFRESH_RETRY_MS = 30 * 1e3;
+var MAX_TIMER_DELAY_MS = 2147483647;
 var WSClient = class {
   ws = null;
   url;
@@ -3952,6 +3955,7 @@ var WSClient = class {
   doc = Automerge__namespace.init();
   syncState = Automerge__namespace.initSyncState();
   reconnectTimer = null;
+  tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
   options;
   constructor(options) {
@@ -3960,12 +3964,109 @@ var WSClient = class {
     this.sessionId = options.sessionId;
     this.token = options.token;
   }
+  clearTokenRefreshTimer() {
+    if (this.tokenRefreshTimer) {
+      clearTimeout(this.tokenRefreshTimer);
+      this.tokenRefreshTimer = null;
+    }
+  }
+  decodeBase64Url(payload) {
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4 || 4)) % 4);
+    if (typeof atob === "function") {
+      return atob(padded);
+    }
+    const maybeBuffer = globalThis.Buffer;
+    if (maybeBuffer) {
+      return maybeBuffer.from(padded, "base64").toString("utf8");
+    }
+    throw new Error("No base64 decoder available");
+  }
+  getTokenExpiryMs(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+      return null;
+    }
+    try {
+      const payloadRaw = this.decodeBase64Url(parts[1]);
+      const payload = JSON.parse(payloadRaw);
+      if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+        return null;
+      }
+      return payload.exp * 1e3;
+    } catch {
+      return null;
+    }
+  }
+  scheduleTokenRefresh() {
+    this.clearTokenRefreshTimer();
+    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
+      return;
+    }
+    const expiresAt = this.getTokenExpiryMs(this.token);
+    if (!expiresAt) {
+      return;
+    }
+    const refreshInMs = Math.max(1e3, expiresAt - Date.now() - TOKEN_REFRESH_LEEWAY_MS);
+    const delay = Math.min(refreshInMs, MAX_TIMER_DELAY_MS);
+    this.tokenRefreshTimer = setTimeout(() => {
+      void this.refreshTokenInBackground();
+    }, delay);
+  }
+  async refreshTokenInBackground() {
+    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
+      return;
+    }
+    try {
+      const refreshedToken = await this.options.tokenProvider();
+      if (typeof refreshedToken !== "string" || refreshedToken.length === 0) {
+        throw new Error("Token provider returned no token");
+      }
+      this.token = refreshedToken;
+      this.scheduleTokenRefresh();
+    } catch (error) {
+      if (this.isExplicitlyDisconnected) {
+        return;
+      }
+      console.warn("[Granular] Token refresh failed, retrying soon:", error);
+      this.clearTokenRefreshTimer();
+      this.tokenRefreshTimer = setTimeout(() => {
+        void this.refreshTokenInBackground();
+      }, TOKEN_REFRESH_RETRY_MS);
+    }
+  }
+  async resolveTokenForConnect() {
+    if (!this.options.tokenProvider) {
+      return this.token;
+    }
+    const expiresAt = this.getTokenExpiryMs(this.token);
+    const shouldRefresh = expiresAt !== null && expiresAt - Date.now() <= TOKEN_REFRESH_LEEWAY_MS;
+    if (!shouldRefresh) {
+      return this.token;
+    }
+    try {
+      const refreshedToken = await this.options.tokenProvider();
+      if (typeof refreshedToken !== "string" || refreshedToken.length === 0) {
+        throw new Error("Token provider returned no token");
+      }
+      this.token = refreshedToken;
+      return refreshedToken;
+    } catch (error) {
+      if (expiresAt > Date.now()) {
+        console.warn("[Granular] Token refresh failed, using current token:", error);
+        return this.token;
+      }
+      throw error;
+    }
+  }
   /**
    * Connect to the WebSocket server
    * @returns {Promise<void>} Resolves when connection is open
    */
   async connect() {
+    const token = await this.resolveTokenForConnect();
     this.isExplicitlyDisconnected = false;
+    this.scheduleTokenRefresh();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -3985,7 +4086,7 @@ var WSClient = class {
       try {
         const wsUrl = new URL(this.url);
         wsUrl.searchParams.set("sessionId", this.sessionId);
-        wsUrl.searchParams.set("token", this.token);
+        wsUrl.searchParams.set("token", token);
         this.ws = new WebSocketClass(wsUrl.toString());
         if (!this.ws) throw new Error("Failed to create WebSocket");
         const socket = this.ws;
@@ -4190,10 +4291,10 @@ var WSClient = class {
       const snapshotMessage = message;
       try {
         const bytes = new Uint8Array(snapshotMessage.data);
-        console.log("[Granular DEBUG] Loading snapshot bytes:", bytes.length);
+        console.log("[Granular DEBUG] Loading Automerge session snapshot bytes:", bytes.length);
         this.doc = Automerge__namespace.load(bytes);
         this.emit("sync", this.doc);
-        console.log("[Granular DEBUG] Snapshot loaded. Doc:", JSON.stringify(Automerge__namespace.toJS(this.doc)));
+        console.log("[Granular DEBUG] Automerge session snapshot loaded. Doc:", JSON.stringify(Automerge__namespace.toJS(this.doc)));
       } catch (e) {
         console.warn("[Granular] Failed to load snapshot message", e);
       }
@@ -4356,6 +4457,7 @@ var WSClient = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    this.clearTokenRefreshTimer();
     if (this.ws) {
       this.ws.close(1e3, "Client disconnect");
       this.ws = null;
@@ -4386,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;
@@ -4424,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.
@@ -4586,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,
@@ -4625,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;
@@ -4673,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")) {
@@ -4789,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}
 
@@ -4807,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);
@@ -4842,6 +4852,13 @@ import { ${allImports} } from "./sandbox-tools";
    * Close the session and disconnect from the sandbox
    */
   async disconnect() {
+    try {
+      await this.client.call("client.goodbye", {
+        clientId: this.clientId,
+        timestamp: Date.now()
+      });
+    } catch (error) {
+    }
     this.client.disconnect();
   }
   // --- Event Handling ---
@@ -4867,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) {
@@ -4878,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,
@@ -4891,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,
@@ -4923,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 = [];
@@ -4942,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,
@@ -5052,6 +5079,50 @@ var JobImplementation = class {
   }
 };
 
+// src/endpoints.ts
+var LOCAL_API_URL = "ws://localhost:8787/granular";
+var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+function readEnv(name) {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env[name];
+}
+function normalizeMode(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "local") return "local";
+  if (normalized === "prod" || normalized === "production") return "production";
+  if (normalized === "auto") return "auto";
+  return void 0;
+}
+function isTruthy(value) {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function resolveEndpointMode(explicitMode) {
+  const explicit = normalizeMode(explicitMode);
+  if (explicit === "local" || explicit === "production") {
+    return explicit;
+  }
+  const envMode = normalizeMode(readEnv("GRANULAR_ENDPOINT_MODE") || readEnv("GRANULAR_ENV"));
+  if (envMode === "local" || envMode === "production") {
+    return envMode;
+  }
+  if (isTruthy(readEnv("GRANULAR_USE_LOCAL_ENDPOINTS")) || isTruthy(readEnv("GRANULAR_LOCAL"))) {
+    return "local";
+  }
+  if (isTruthy(readEnv("GRANULAR_USE_PRODUCTION_ENDPOINTS")) || isTruthy(readEnv("GRANULAR_PROD"))) {
+    return "production";
+  }
+  return readEnv("NODE_ENV") === "development" ? "local" : "production";
+}
+function resolveApiUrl(explicitApiUrl, mode) {
+  if (explicitApiUrl) {
+    return explicitApiUrl;
+  }
+  return resolveEndpointMode(mode) === "local" ? LOCAL_API_URL : PRODUCTION_API_URL;
+}
+
 // src/client.ts
 var STANDARD_MODULES_OPERATIONS = [
   { create: "entity", has: { id: { value: "auto-generated" }, createdAt: { value: void 0 } } },
@@ -5066,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;
@@ -5096,6 +5198,60 @@ var Environment = class _Environment extends Session {
   get apiEndpoint() {
     return this._apiEndpoint;
   }
+  getRuntimeBaseUrl() {
+    try {
+      const endpoint = new URL(this._apiEndpoint);
+      const graphqlSuffix = "/orchestrator/graphql";
+      if (endpoint.pathname.endsWith(graphqlSuffix)) {
+        endpoint.pathname = endpoint.pathname.slice(0, -graphqlSuffix.length);
+      } else if (endpoint.pathname.endsWith("/graphql")) {
+        endpoint.pathname = endpoint.pathname.slice(0, -"/graphql".length);
+      }
+      endpoint.search = "";
+      endpoint.hash = "";
+      return endpoint.toString().replace(/\/$/, "");
+    } catch {
+      return this._apiEndpoint.replace(/\/orchestrator\/graphql$/, "").replace(/\/$/, "");
+    }
+  }
+  /**
+   * 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.
+   */
+  async disconnect() {
+    let wsNotifiedRuntime = false;
+    try {
+      const goodbye = await this.rpc("client.goodbye", {
+        timestamp: Date.now()
+      });
+      wsNotifiedRuntime = Boolean(goodbye?.ok && goodbye?.via);
+    } catch {
+      wsNotifiedRuntime = false;
+    }
+    if (!wsNotifiedRuntime) {
+      try {
+        const runtimeBase = this.getRuntimeBaseUrl();
+        await fetch(
+          `${runtimeBase}/orchestrator/runtime/environments/${this.environmentId}/session-goodbye`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${this._apiKey}`
+            },
+            body: JSON.stringify({
+              reason: "sdk_disconnect_http_fallback"
+            })
+          }
+        );
+      } catch {
+      }
+    }
+    this.client.disconnect();
+  }
   // ==================== GRAPH CONTAINER READINESS ====================
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
@@ -5756,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();
@@ -5831,13 +5946,16 @@ var Granular = class {
   apiKey;
   apiUrl;
   httpUrl;
+  tokenProvider;
   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
@@ -5848,11 +5966,12 @@ var Granular = class {
       throw new Error("Granular client requires either apiKey or token. Set GRANULAR_API_KEY or GRANULAR_TOKEN, or pass one in options.");
     }
     this.apiKey = auth;
-    this.apiUrl = options.apiUrl || "wss://api.granular.dev/v2/ws";
+    this.apiUrl = resolveApiUrl(options.apiUrl, options.endpointMode);
+    this.tokenProvider = options.tokenProvider;
     this.WebSocketCtor = options.WebSocketCtor;
     this.onUnexpectedClose = options.onUnexpectedClose;
     this.onReconnectError = options.onReconnectError;
-    this.httpUrl = this.apiUrl.replace("wss://", "https://").replace("/ws", "");
+    this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
   /**
    * Records/upserts a user and prepares them for sandbox connections
@@ -5889,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
@@ -5907,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(`
@@ -5932,10 +6054,19 @@ 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,
       onReconnectError: this.onReconnectError
@@ -5943,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.
@@ -5993,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.
@@ -6030,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
@@ -6069,7 +6319,7 @@ var Granular = class {
     const created = await this.permissionProfiles.create(sandboxId, {
       name: profileName,
       rules: {
-        tools: { allow: ["*"] },
+        effects: { allow: ["*"] },
         resources: { allow: ["*"] }
       }
     });