@granular-software/sdk 0.3.3 → 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-CnX4jXYQ.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-CnX4jXYQ.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-CnX4jXYQ.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-CnX4jXYQ.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-CnX4jXYQ.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-CnX4jXYQ.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-CnX4jXYQ.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-CnX4jXYQ.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();
@@ -5741,23 +5793,203 @@ function normalizeAuthBaseUrl(input) {
   }
   return url;
 }
-function renderHtmlPage(title, message) {
+function escapeHtml(input) {
+  return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function generateSquirclePath(size = 128, radius = 56, exp = 4, steps = 72) {
+  const center = size / 2;
+  const points = [];
+  for (let i = 0; i <= steps; i++) {
+    const angle = i / steps * 2 * Math.PI;
+    const cosA = Math.cos(angle);
+    const sinA = Math.sin(angle);
+    const r = 1 / Math.pow(
+      Math.pow(Math.abs(cosA), exp) + Math.pow(Math.abs(sinA), exp),
+      1 / exp
+    );
+    const x = center + r * cosA * radius;
+    const y = center + r * sinA * radius;
+    points.push(`${x.toFixed(3)} ${y.toFixed(3)}`);
+  }
+  return `M ${points.join(" L ")} Z`;
+}
+function generateHilbertPath(order = 4, size = 128, radius = 51) {
+  const n = 1 << order;
+  const center = size / 2;
+  const squircleExp = 4;
+  const points = [];
+  function squareToSquircle(u, v) {
+    if (Math.abs(u) < 1e-3 && Math.abs(v) < 1e-3) return [u, v];
+    const angle = Math.atan2(v, u);
+    const cosA = Math.cos(angle);
+    const sinA = Math.sin(angle);
+    const squircleR = 1 / Math.pow(
+      Math.pow(Math.abs(cosA), squircleExp) + Math.pow(Math.abs(sinA), squircleExp),
+      1 / squircleExp
+    );
+    const squareDist = Math.max(Math.abs(u), Math.abs(v));
+    const newDist = squareDist * squircleR;
+    return [newDist * cosA, newDist * sinA];
+  }
+  function d2xy(d) {
+    let x = 0;
+    let y = 0;
+    let t = d;
+    for (let s = 1; s < n; s *= 2) {
+      const rx = 1 & Math.floor(t) / 2;
+      const ry = 1 & (Math.floor(t) ^ rx);
+      if (ry === 0) {
+        if (rx === 1) {
+          x = s - 1 - x;
+          y = s - 1 - y;
+        }
+        [x, y] = [y, x];
+      }
+      x += s * rx;
+      y += s * ry;
+      t = Math.floor(t) / 4;
+    }
+    return [x, y];
+  }
+  for (let i = 0; i < n * n; i++) {
+    const [x, y] = d2xy(i);
+    const normX = x / (n - 1) * 2 - 1;
+    const normY = y / (n - 1) * 2 - 1;
+    const [sqX, sqY] = squareToSquircle(normX, normY);
+    points.push([center + sqX * radius, center + sqY * radius]);
+  }
+  return points.map(([x, y], i) => `${i === 0 ? "M" : "L"} ${x.toFixed(3)} ${y.toFixed(3)}`).join(" ");
+}
+function renderLogoSvg() {
+  const squirclePath = generateSquirclePath();
+  const hilbertPath = generateHilbertPath();
+  return `<svg class="logo" viewBox="0 0 128 128" role="img" aria-label="Granular logo" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="granular-logo-gradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#ff8a54" />
+      <stop offset="55%" stop-color="#ff6b35" />
+      <stop offset="100%" stop-color="#e34b1f" />
+    </linearGradient>
+    <filter id="granular-logo-glow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="1.6" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+  </defs>
+  <path d="${squirclePath}" fill="rgba(255,255,255,0.05)" stroke="rgba(255,255,255,0.25)" stroke-width="1.2" />
+  <path d="${hilbertPath}" fill="none" stroke="url(#granular-logo-gradient)" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round" filter="url(#granular-logo-glow)" />
+</svg>`;
+}
+function renderHtmlPage(title, message, variant) {
+  const safeTitle = escapeHtml(title);
+  const safeMessage = escapeHtml(message);
+  const accent = variant === "success" ? "#ff6b35" : "#ff5c6b";
+  const badge = variant === "success" ? "Success" : "Auth Error";
   return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${title}</title>
+  <title>${safeTitle}</title>
   <style>
-    :root { color-scheme: light dark; }
-    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 2rem; line-height: 1.5; }
-    h1 { margin-bottom: 0.5rem; }
-    p { margin-top: 0; color: #666; }
+    :root { color-scheme: dark; }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: 28px;
+      font-family: "Avenir Next", "SF Pro Display", "Segoe UI", sans-serif;
+      color: #f8f8f8;
+      background:
+        radial-gradient(1000px 480px at 12% -10%, rgba(255, 110, 58, 0.26), transparent 60%),
+        radial-gradient(760px 480px at 100% 120%, rgba(99, 102, 241, 0.22), transparent 65%),
+        linear-gradient(140deg, #0f0f12 0%, #131319 45%, #11131a 100%);
+    }
+    .panel {
+      width: min(520px, 100%);
+      border-radius: 24px;
+      border: 1px solid rgba(255, 255, 255, 0.16);
+      background: linear-gradient(160deg, rgba(255,255,255,0.08), rgba(255,255,255,0.03));
+      backdrop-filter: blur(8px);
+      box-shadow:
+        0 18px 60px rgba(0, 0, 0, 0.45),
+        inset 0 1px 0 rgba(255, 255, 255, 0.18);
+      padding: 26px 26px 24px;
+    }
+    .head {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      margin-bottom: 14px;
+    }
+    .logo-wrap {
+      width: 62px;
+      height: 62px;
+      border-radius: 18px;
+      border: 1px solid rgba(255,255,255,0.2);
+      background: radial-gradient(circle at 25% 20%, rgba(255,255,255,0.17), rgba(255,255,255,0.02));
+      display: grid;
+      place-items: center;
+      flex: 0 0 auto;
+    }
+    .logo {
+      width: 46px;
+      height: 46px;
+      display: block;
+    }
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      border-radius: 999px;
+      padding: 5px 11px;
+      border: 1px solid ${accent}66;
+      background: ${accent}26;
+      color: ${accent};
+      font-size: 12px;
+      font-weight: 600;
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+      margin-bottom: 8px;
+    }
+    h1 {
+      margin: 0;
+      font-size: 25px;
+      line-height: 1.2;
+      letter-spacing: 0.01em;
+      color: #ffffff;
+    }
+    p {
+      margin: 0;
+      color: #d7d8df;
+      font-size: 15px;
+      line-height: 1.6;
+    }
+    .footer {
+      margin-top: 18px;
+      padding-top: 14px;
+      border-top: 1px solid rgba(255, 255, 255, 0.11);
+      font-size: 12px;
+      color: #9ea3b2;
+      letter-spacing: 0.02em;
+    }
   </style>
 </head>
 <body>
-  <h1>${title}</h1>
-  <p>${message}</p>
+  <main class="panel">
+    <div class="head">
+      <div class="logo-wrap">${renderLogoSvg()}</div>
+      <div>
+        <div class="badge">${badge}</div>
+        <h1>${safeTitle}</h1>
+      </div>
+    </div>
+    <p>${safeMessage}</p>
+    <div class="footer">Granular CLI authentication flow completed.</div>
+  </main>
 </body>
 </html>`;
 }
@@ -5841,7 +6073,7 @@ async function loginWithBrowser(options) {
         if (!returnedState || returnedState !== state) {
           res.statusCode = 400;
           res.setHeader("Content-Type", "text/html; charset=utf-8");
-          res.end(renderHtmlPage("Granular login failed", "State mismatch. Please close this window and retry."));
+          res.end(renderHtmlPage("Granular login failed", "State mismatch. Please close this window and retry.", "error"));
           if (!settled) {
             settled = true;
             clearTimeout(timeout);
@@ -5852,7 +6084,13 @@ async function loginWithBrowser(options) {
         if (error2) {
           res.statusCode = 400;
           res.setHeader("Content-Type", "text/html; charset=utf-8");
-          res.end(renderHtmlPage("Granular login failed", "Authentication was canceled or failed. You can close this window."));
+          res.end(
+            renderHtmlPage(
+              "Granular login failed",
+              `${describeAuthError(error2)} You can close this window and return to the CLI.`,
+              "error"
+            )
+          );
           if (!settled) {
             settled = true;
             clearTimeout(timeout);
@@ -5863,7 +6101,7 @@ async function loginWithBrowser(options) {
         if (!apiKey2) {
           res.statusCode = 400;
           res.setHeader("Content-Type", "text/html; charset=utf-8");
-          res.end(renderHtmlPage("Granular login failed", "No API key was returned. Please retry."));
+          res.end(renderHtmlPage("Granular login failed", "No API key was returned. Please retry.", "error"));
           if (!settled) {
             settled = true;
             clearTimeout(timeout);
@@ -5873,7 +6111,7 @@ async function loginWithBrowser(options) {
         }
         res.statusCode = 200;
         res.setHeader("Content-Type", "text/html; charset=utf-8");
-        res.end(renderHtmlPage("Granular login complete", "Authentication succeeded. You can close this window."));
+        res.end(renderHtmlPage("Granular login complete", "Authentication succeeded. You can close this window.", "success"));
         if (!settled) {
           settled = true;
           clearTimeout(timeout);
@@ -7475,6 +7713,18 @@ function prompt(question, defaultValue) {
     });
   });
 }
+function waitForEnter(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return Promise.resolve();
+  }
+  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`  ${message}`, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
 function confirm(question, defaultYes = true) {
   const hint2 = defaultYes ? "Y/n" : "y/N";
   return prompt(`${question} [${hint2}]`).then((answer) => {
@@ -7495,6 +7745,8 @@ async function initCommand(projectName, options) {
   let apiKey = loadApiKey();
   if (!apiKey) {
     info("No API key found. Starting browser login...");
+    await waitForEnter("Press Enter to open the login page in your browser...");
+    console.log();
     const waiting = spinner("Opening browser and waiting for authentication...");
     try {
       apiKey = await loginWithBrowser({
@@ -7615,6 +7867,18 @@ function promptSecret(question) {
     });
   });
 }
+function waitForEnter2(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return Promise.resolve();
+  }
+  const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`  ${message}`, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
 function maskApiKey(apiKey) {
   if (apiKey.length < 10) return `${apiKey}...`;
   return `${apiKey.substring(0, 10)}...`;
@@ -7636,6 +7900,8 @@ async function loginCommand(options = {}) {
       apiKey = await promptSecret("Enter your API key");
     } else {
       const timeoutMs = options.timeout && options.timeout > 0 ? options.timeout * 1e3 : void 0;
+      await waitForEnter2("Press Enter to open the login page in your browser...");
+      console.log();
       const waiting = spinner("Opening browser and waiting for authentication...");
       try {
         apiKey = await loginWithBrowser({
@@ -8409,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-CnX4jXYQ.mjs';
-export { a2 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a0 as ManifestImport, x as ManifestListResponse, $ as ManifestOperation, Z as ManifestPropertySpec, _ as ManifestRelationshipDef, a1 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, N as RPCRequest, V as RPCRequestFromServer, O as RPCResponse, Q as SyncMessage, X as ToolInvokeParams, Y as ToolResultParams, q as ToolSchema } from './types-CnX4jXYQ.mjs';
+import { 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,14 +16,24 @@ 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
      */
     connect(): Promise<void>;
+    private normalizeReason;
+    private rejectPending;
+    private buildDisconnectError;
     private handleDisconnect;
     private handleMessage;
     /**
@@ -322,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;
@@ -637,7 +656,10 @@ declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private tokenProvider?;
     private WebSocketCtor?;
+    private onUnexpectedClose?;
+    private onReconnectError?;
     /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
     private sandboxEffects;
     /** Active environments tracker: sandboxId → Environment[] */

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-CnX4jXYQ.js';
-export { a2 as APIError, u as Assignment, z as Build, F as BuildListResponse, B as BuildPolicy, y as BuildStatus, v as EnvironmentListResponse, r as GranularAuth, H as JobStatus, K as JobSubmitResult, w as Manifest, a0 as ManifestImport, x as ManifestListResponse, $ as ManifestOperation, Z as ManifestPropertySpec, _ as ManifestRelationshipDef, a1 as ManifestVolume, t as PermissionProfileListResponse, s as PermissionRules, L as Prompt, N as RPCRequest, V as RPCRequestFromServer, O as RPCResponse, Q as SyncMessage, X as ToolInvokeParams, Y as ToolResultParams, q as ToolSchema } from './types-CnX4jXYQ.js';
+import { 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,14 +16,24 @@ 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
      */
     connect(): Promise<void>;
+    private normalizeReason;
+    private rejectPending;
+    private buildDisconnectError;
     private handleDisconnect;
     private handleMessage;
     /**
@@ -322,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;
@@ -637,7 +656,10 @@ declare class Granular {
     private apiKey;
     private apiUrl;
     private httpUrl;
+    private tokenProvider?;
     private WebSocketCtor?;
+    private onUnexpectedClose?;
+    private onReconnectError?;
     /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
     private sandboxEffects;
     /** Active environments tracker: sandboxId → Environment[] */