@granular-software/sdk 0.3.3 → 0.3.4

package/dist/adapters/anthropic.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-CnX4jXYQ.mjs';
+import { T as ToolWithHandler } from '../types-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.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-D5B8WlF4.js';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/cli/index.js

@@ -5741,23 +5741,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 +6021,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 +6032,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 +6049,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 +6059,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 +7661,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 +7693,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 +7815,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 +7848,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({

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-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 { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -24,6 +24,9 @@ declare class WSClient {
      * @returns {Promise<void>} Resolves when connection is open
      */
     connect(): Promise<void>;
+    private normalizeReason;
+    private rejectPending;
+    private buildDisconnectError;
     private handleDisconnect;
     private handleMessage;
     /**
@@ -638,6 +641,8 @@ declare class Granular {
     private apiUrl;
     private httpUrl;
     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-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 { Doc } from '@automerge/automerge/slim';
 
 declare class WSClient {
@@ -24,6 +24,9 @@ declare class WSClient {
      * @returns {Promise<void>} Resolves when connection is open
      */
     connect(): Promise<void>;
+    private normalizeReason;
+    private rejectPending;
+    private buildDisconnectError;
     private handleDisconnect;
     private handleMessage;
     /**
@@ -638,6 +641,8 @@ declare class Granular {
     private apiUrl;
     private httpUrl;
     private WebSocketCtor?;
+    private onUnexpectedClose?;
+    private onReconnectError?;
     /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
     private sandboxEffects;
     /** Active environments tracker: sandboxId → Environment[] */

package/dist/index.js

@@ -3966,6 +3966,10 @@ var WSClient = class {
    */
   async connect() {
     this.isExplicitlyDisconnected = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
     let WebSocketClass = this.options.WebSocketCtor || GlobalWebSocket;
     if (!WebSocketClass) {
       try {
@@ -3987,6 +3991,10 @@ var WSClient = class {
         const socket = this.ws;
         if (typeof socket.on === "function") {
           socket.on("open", () => {
+            if (this.reconnectTimer) {
+              clearTimeout(this.reconnectTimer);
+              this.reconnectTimer = null;
+            }
             this.emit("open", {});
             resolve();
           });
@@ -4004,12 +4012,20 @@ var WSClient = class {
               reject(error);
             }
           });
-          socket.on("close", () => {
-            this.emit("close", {});
-            this.handleDisconnect();
+          socket.on("close", (code, reason) => {
+            this.handleDisconnect({
+              code,
+              reason: this.normalizeReason(reason),
+              // ws does not provide wasClean on Node-style close callback
+              wasClean: code === 1e3
+            });
           });
         } else {
           this.ws.onopen = () => {
+            if (this.reconnectTimer) {
+              clearTimeout(this.reconnectTimer);
+              this.reconnectTimer = null;
+            }
             this.emit("open", {});
             resolve();
           };
@@ -4030,9 +4046,12 @@ var WSClient = class {
               reject(error);
             }
           };
-          this.ws.onclose = () => {
-            this.emit("close", {});
-            this.handleDisconnect();
+          this.ws.onclose = (event) => {
+            this.handleDisconnect({
+              code: event.code,
+              reason: event.reason,
+              wasClean: event.wasClean
+            });
           };
         }
       } catch (error) {
@@ -4040,13 +4059,80 @@ var WSClient = class {
       }
     });
   }
-  handleDisconnect() {
+  normalizeReason(reason) {
+    if (reason === null || reason === void 0) return void 0;
+    if (typeof reason === "string") return reason;
+    if (typeof reason === "object" && reason && "toString" in reason) {
+      try {
+        const text = String(reason.toString());
+        return text || void 0;
+      } catch {
+        return void 0;
+      }
+    }
+    return void 0;
+  }
+  rejectPending(error) {
+    this.messageQueue.forEach((pending) => pending.reject(error));
+    this.messageQueue = [];
+  }
+  buildDisconnectError(info) {
+    const details = [
+      info.code !== void 0 ? `code=${info.code}` : void 0,
+      info.reason ? `reason=${info.reason}` : void 0
+    ].filter(Boolean).join(", ");
+    const suffix = details ? ` (${details})` : "";
+    return new Error(`WebSocket disconnected${suffix}`);
+  }
+  handleDisconnect(close = {}) {
+    const reconnectDelayMs = 3e3;
+    const unexpected = !this.isExplicitlyDisconnected;
+    const info = {
+      code: close.code,
+      reason: close.reason,
+      wasClean: close.wasClean,
+      unexpected,
+      timestamp: Date.now(),
+      reconnectScheduled: false
+    };
     this.ws = null;
-    if (!this.isExplicitlyDisconnected) {
+    this.emit("close", info);
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (unexpected) {
+      const disconnectError = this.buildDisconnectError(info);
+      this.rejectPending(disconnectError);
+      this.emit("disconnect", info);
+      info.reconnectScheduled = true;
+      info.reconnectDelayMs = reconnectDelayMs;
+      if (this.options.onUnexpectedClose) {
+        try {
+          this.options.onUnexpectedClose(info);
+        } catch (callbackError) {
+          console.error("[Granular] onUnexpectedClose callback failed:", callbackError);
+        }
+      }
       this.reconnectTimer = setTimeout(() => {
         console.log("[Granular] Attempting reconnect...");
-        this.connect().catch((e) => console.error("[Granular] Reconnect failed:", e));
-      }, 3e3);
+        this.connect().catch((error) => {
+          console.error("[Granular] Reconnect failed:", error);
+          const reconnectInfo = {
+            error: error instanceof Error ? error.message : String(error),
+            sessionId: this.sessionId,
+            timestamp: Date.now()
+          };
+          this.emit("reconnect_error", reconnectInfo);
+          if (this.options.onReconnectError) {
+            try {
+              this.options.onReconnectError(reconnectInfo);
+            } catch (callbackError) {
+              console.error("[Granular] onReconnectError callback failed:", callbackError);
+            }
+          }
+        });
+      }, reconnectDelayMs);
     }
   }
   handleMessage(message) {
@@ -4266,13 +4352,15 @@ var WSClient = class {
    */
   disconnect() {
     this.isExplicitlyDisconnected = true;
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
     if (this.ws) {
-      this.ws.close();
+      this.ws.close(1e3, "Client disconnect");
       this.ws = null;
     }
-    this.messageQueue.forEach((q) => q.reject(new Error("Client explicitly disconnected")));
-    this.messageQueue = [];
+    this.rejectPending(new Error("Client explicitly disconnected"));
     this.rpcHandlers.clear();
     this.emit("disconnect", {});
   }
@@ -4817,7 +4905,7 @@ import { ${allImports} } from "./sandbox-tools";
       this.checkForToolChanges();
     });
     this.client.on("prompt", (prompt) => this.emit("prompt", prompt));
-    this.client.on("disconnect", () => this.emit("disconnect", {}));
+    this.client.on("disconnect", (payload) => this.emit("disconnect", payload || {}));
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
@@ -5744,6 +5832,8 @@ var Granular = class {
   apiUrl;
   httpUrl;
   WebSocketCtor;
+  onUnexpectedClose;
+  onReconnectError;
   /** Sandbox-level effect registry: sandboxId → (toolName → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
   /** Active environments tracker: sandboxId → Environment[] */
@@ -5760,6 +5850,8 @@ var Granular = class {
     this.apiKey = auth;
     this.apiUrl = options.apiUrl || "wss://api.granular.dev/v2/ws";
     this.WebSocketCtor = options.WebSocketCtor;
+    this.onUnexpectedClose = options.onUnexpectedClose;
+    this.onReconnectError = options.onReconnectError;
     this.httpUrl = this.apiUrl.replace("wss://", "https://").replace("/ws", "");
   }
   /**
@@ -5844,7 +5936,9 @@ var Granular = class {
       url: this.apiUrl,
       sessionId: envData.environmentId,
       token: this.apiKey,
-      WebSocketCtor: this.WebSocketCtor
+      WebSocketCtor: this.WebSocketCtor,
+      onUnexpectedClose: this.onUnexpectedClose,
+      onReconnectError: this.onReconnectError
     });
     await client.connect();
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;