@granular-software/sdk 0.3.4 → 0.4.1

package/README.md

@@ -27,6 +27,26 @@ bun add @granular-software/sdk
 npm install @granular-software/sdk
 ```
 
+## Endpoint Modes
+
+By default, the SDK resolves endpoints like this:
+
+- Local mode (`NODE_ENV=development`): `ws://localhost:8787/granular`
+- Production mode (default): `wss://api.granular.dev/v2/ws`
+
+Overrides:
+
+- SDK option: `endpointMode: 'local' | 'production'`
+- SDK option: `apiUrl: 'ws://... | wss://...'` (highest priority)
+- Env: `GRANULAR_ENDPOINT_MODE=local|production`
+- Env: `GRANULAR_API_URL=...` (highest priority)
+
+CLI overrides:
+
+- `granular --local <command>`
+- `granular --prod <command>`
+- `granular --env local|production <command>`
+
 ## Quick Start
 
 ```typescript

package/dist/adapters/anthropic.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D5B8WlF4.mjs';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.mjs';
 
 /**
  * Anthropic tool_use block from message response

package/dist/adapters/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D5B8WlF4.js';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.js';
 
 /**
  * Anthropic tool_use block from message response

package/dist/adapters/langchain.d.mts

@@ -1,5 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { T as ToolWithHandler } from '../types-D5B8WlF4.mjs';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.mjs';
 
 /**
  * Helper to convert LangChain tools to Granular tools.

package/dist/adapters/langchain.d.ts

@@ -1,5 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { T as ToolWithHandler } from '../types-D5B8WlF4.js';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.js';
 
 /**
  * Helper to convert LangChain tools to Granular tools.

package/dist/adapters/mastra.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { T as ToolWithHandler } from '../types-D5B8WlF4.mjs';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.mjs';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/mastra.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { T as ToolWithHandler } from '../types-D5B8WlF4.js';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.js';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/openai.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D5B8WlF4.mjs';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.mjs';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/adapters/openai.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D5B8WlF4.js';
+import { T as ToolWithHandler } from '../types-BOPsFZYi.js';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/cli/index.js

@@ -5384,6 +5384,57 @@ var {
 
 // src/cli/config.ts
 var import_dotenv = __toESM(require_main());
+
+// src/endpoints.ts
+var LOCAL_API_URL = "ws://localhost:8787/granular";
+var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+var LOCAL_AUTH_URL = "http://localhost:3000";
+var PRODUCTION_AUTH_URL = "https://app.granular.software";
+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) {
+  return resolveEndpointMode(mode) === "local" ? LOCAL_API_URL : PRODUCTION_API_URL;
+}
+function resolveAuthUrl(explicitAuthUrl, mode) {
+  if (explicitAuthUrl) {
+    return explicitAuthUrl;
+  }
+  return resolveEndpointMode(mode) === "local" ? LOCAL_AUTH_URL : PRODUCTION_AUTH_URL;
+}
+
+// src/cli/config.ts
 var MANIFEST_FILE = "granular.json";
 var RC_FILE = ".granularrc";
 var ENV_LOCAL_FILE = ".env.local";
@@ -5453,16 +5504,17 @@ function loadApiKey() {
   return void 0;
 }
 function loadApiUrl() {
+  if (process.env.GRANULAR_API_URL) return process.env.GRANULAR_API_URL;
+  const modeOverride = process.env.GRANULAR_ENDPOINT_MODE;
+  if (modeOverride === "local" || modeOverride === "production" || modeOverride === "prod") {
+    return resolveApiUrl(void 0, modeOverride === "prod" ? "production" : modeOverride);
+  }
   const rc = readRcFile();
   if (rc.apiUrl) return rc.apiUrl;
-  if (process.env.GRANULAR_API_URL) return process.env.GRANULAR_API_URL;
-  return "https://cf-api-gateway.arthur6084.workers.dev/granular";
+  return resolveApiUrl();
 }
 function loadAuthUrl() {
-  if (process.env.GRANULAR_AUTH_URL) {
-    return process.env.GRANULAR_AUTH_URL;
-  }
-  return "https://app.granular.software";
+  return resolveAuthUrl(process.env.GRANULAR_AUTH_URL);
 }
 function saveApiKey(apiKey) {
   const envLocalPath = getEnvLocalPath();
@@ -8623,6 +8675,28 @@ async function simulateCommand(sandboxIdArg) {
 var VERSION = "0.2.0";
 var program2 = new Command();
 program2.name("granular").description("Build and deploy AI sandboxes from code").version(VERSION, "-v, --version");
+program2.option("--local", "Use local endpoints (localhost)").option("--prod", "Use production endpoints").option("--env <target>", "Endpoint target: local|production");
+program2.hook("preAction", () => {
+  const opts = program2.opts();
+  const normalizedEnv = opts.env?.trim().toLowerCase();
+  if (opts.local && opts.prod) {
+    error("Cannot use --local and --prod at the same time.");
+    process.exit(1);
+  }
+  if (normalizedEnv && !["local", "production", "prod"].includes(normalizedEnv)) {
+    error('Invalid --env value. Use "local" or "production".');
+    process.exit(1);
+  }
+  let mode;
+  if (opts.local || normalizedEnv === "local") {
+    mode = "local";
+  } else if (opts.prod || normalizedEnv === "production" || normalizedEnv === "prod") {
+    mode = "production";
+  }
+  if (mode) {
+    process.env.GRANULAR_ENDPOINT_MODE = mode;
+  }
+});
 program2.command("init [project-name]").description("Initialize a new Granular project").option("--skip-build", "Skip the initial build step").action(async (projectName, opts) => {
   try {
     await initCommand(projectName, { skipBuild: opts.skipBuild });

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as Automerge from '@automerge/automerge';
-import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, b as ToolInfo, c as ToolsChangedEvent, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, d as GraphQLResult, e as DefineRelationshipOptions, f as RelationshipInfo, M as ModelRef, g as ManifestContent, h as RecordObjectOptions, i as RecordObjectResult, S as SandboxListResponse, j as Sandbox, k as CreateSandboxData, l as DeleteResponse, m as PermissionProfile, n as CreatePermissionProfileData, o as CreateEnvironmentData, p as Subject, A as AssignmentListResponse } from './types-D5B8WlF4.mjs';
-export { a4 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a2 as ManifestImport, x as ManifestListResponse, a1 as ManifestOperation, $ as ManifestPropertySpec, a0 as ManifestRelationshipDef, a3 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, Q as RPCRequest, Y as RPCRequestFromServer, V as RPCResponse, X as SyncMessage, Z as ToolInvokeParams, _ as ToolResultParams, q as ToolSchema, N as WSDisconnectInfo, O as WSReconnectErrorInfo } from './types-D5B8WlF4.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-BOPsFZYi.mjs';
+export { a6 as APIError, r as AccessTokenProvider, w as Assignment, H as Build, K as BuildListResponse, B as BuildPolicy, F as BuildStatus, s as EndpointMode, x as EnvironmentListResponse, t as GranularAuth, L as JobStatus, N as JobSubmitResult, y as Manifest, a4 as ManifestImport, z as ManifestListResponse, a3 as ManifestOperation, a1 as ManifestPropertySpec, a2 as ManifestRelationshipDef, a5 as ManifestVolume, v as PermissionProfileListResponse, u as PermissionRules, O as Prompt, X as RPCRequest, _ as RPCRequestFromServer, Y as RPCResponse, Z as SyncMessage, $ as ToolInvokeParams, a0 as ToolResultParams, q as ToolSchema, Q as WSDisconnectInfo, V as WSReconnectErrorInfo } from './types-BOPsFZYi.mjs';
 import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -16,9 +16,16 @@ declare class WSClient {
     doc: Automerge.Doc<Record<string, unknown>>;
     private syncState;
     private reconnectTimer;
+    private tokenRefreshTimer;
     private isExplicitlyDisconnected;
     private options;
     constructor(options: WSClientOptions);
+    private clearTokenRefreshTimer;
+    private decodeBase64Url;
+    private getTokenExpiryMs;
+    private scheduleTokenRefresh;
+    private refreshTokenInBackground;
+    private resolveTokenForConnect;
     /**
      * Connect to the WebSocket server
      * @returns {Promise<void>} Resolves when connection is open
@@ -325,6 +332,15 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    private getRuntimeBaseUrl;
+    /**
+     * Close the session and disconnect from the sandbox.
+     *
+     * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
+     * to the runtime goodbye endpoint if no definitive WS-side runtime notify
+     * acknowledgement was observed.
+     */
+    disconnect(): Promise<void>;
     /** The last known graph container status, updated by checkReadiness() or on heartbeat */
     graphContainerStatus: {
         lastKeepAliveAt: number;
@@ -640,6 +656,7 @@ declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private tokenProvider?;
     private WebSocketCtor?;
     private onUnexpectedClose?;
     private onReconnectError?;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as Automerge from '@automerge/automerge';
-import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, b as ToolInfo, c as ToolsChangedEvent, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, d as GraphQLResult, e as DefineRelationshipOptions, f as RelationshipInfo, M as ModelRef, g as ManifestContent, h as RecordObjectOptions, i as RecordObjectResult, S as SandboxListResponse, j as Sandbox, k as CreateSandboxData, l as DeleteResponse, m as PermissionProfile, n as CreatePermissionProfileData, o as CreateEnvironmentData, p as Subject, A as AssignmentListResponse } from './types-D5B8WlF4.js';
-export { a4 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a2 as ManifestImport, x as ManifestListResponse, a1 as ManifestOperation, $ as ManifestPropertySpec, a0 as ManifestRelationshipDef, a3 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, Q as RPCRequest, Y as RPCRequestFromServer, V as RPCResponse, X as SyncMessage, Z as ToolInvokeParams, _ as ToolResultParams, q as ToolSchema, N as WSDisconnectInfo, O as WSReconnectErrorInfo } from './types-D5B8WlF4.js';
+import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, 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-BOPsFZYi.js';
+export { a6 as APIError, r as AccessTokenProvider, w as Assignment, H as Build, K as BuildListResponse, B as BuildPolicy, F as BuildStatus, s as EndpointMode, x as EnvironmentListResponse, t as GranularAuth, L as JobStatus, N as JobSubmitResult, y as Manifest, a4 as ManifestImport, z as ManifestListResponse, a3 as ManifestOperation, a1 as ManifestPropertySpec, a2 as ManifestRelationshipDef, a5 as ManifestVolume, v as PermissionProfileListResponse, u as PermissionRules, O as Prompt, X as RPCRequest, _ as RPCRequestFromServer, Y as RPCResponse, Z as SyncMessage, $ as ToolInvokeParams, a0 as ToolResultParams, q as ToolSchema, Q as WSDisconnectInfo, V as WSReconnectErrorInfo } from './types-BOPsFZYi.js';
 import { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -16,9 +16,16 @@ declare class WSClient {
     doc: Automerge.Doc<Record<string, unknown>>;
     private syncState;
     private reconnectTimer;
+    private tokenRefreshTimer;
     private isExplicitlyDisconnected;
     private options;
     constructor(options: WSClientOptions);
+    private clearTokenRefreshTimer;
+    private decodeBase64Url;
+    private getTokenExpiryMs;
+    private scheduleTokenRefresh;
+    private refreshTokenInBackground;
+    private resolveTokenForConnect;
     /**
      * Connect to the WebSocket server
      * @returns {Promise<void>} Resolves when connection is open
@@ -325,6 +332,15 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    private getRuntimeBaseUrl;
+    /**
+     * Close the session and disconnect from the sandbox.
+     *
+     * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
+     * to the runtime goodbye endpoint if no definitive WS-side runtime notify
+     * acknowledgement was observed.
+     */
+    disconnect(): Promise<void>;
     /** The last known graph container status, updated by checkReadiness() or on heartbeat */
     graphContainerStatus: {
         lastKeepAliveAt: number;
@@ -640,6 +656,7 @@ declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private tokenProvider?;
     private WebSocketCtor?;
     private onUnexpectedClose?;
     private onReconnectError?;

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;
@@ -4842,6 +4944,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 ---
@@ -5052,6 +5161,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 } } },
@@ -5096,6 +5249,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;
@@ -5831,6 +6038,7 @@ var Granular = class {
   apiKey;
   apiUrl;
   httpUrl;
+  tokenProvider;
   WebSocketCtor;
   onUnexpectedClose;
   onReconnectError;
@@ -5848,11 +6056,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
@@ -5936,6 +6145,7 @@ var Granular = class {
       url: this.apiUrl,
       sessionId: envData.environmentId,
       token: this.apiKey,
+      tokenProvider: this.tokenProvider,
       WebSocketCtor: this.WebSocketCtor,
       onUnexpectedClose: this.onUnexpectedClose,
       onReconnectError: this.onReconnectError