@granular-software/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1801 @@
+'use strict';
+
+var WebSocket = require('ws');
+var Automerge = require('@automerge/automerge');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var WebSocket__default = /*#__PURE__*/_interopDefault(WebSocket);
+var Automerge__namespace = /*#__PURE__*/_interopNamespace(Automerge);
+
+// src/ws-client.ts
+var WSClient = class {
+  ws = null;
+  url;
+  sessionId;
+  token;
+  messageQueue = [];
+  syncHandlers = [];
+  rpcHandlers = /* @__PURE__ */ new Map();
+  eventHandlers = /* @__PURE__ */ new Map();
+  nextRpcId = 1;
+  doc = Automerge__namespace.init();
+  syncState = Automerge__namespace.initSyncState();
+  reconnectTimer = null;
+  isExplicitlyDisconnected = false;
+  constructor(options) {
+    this.url = options.url;
+    this.sessionId = options.sessionId;
+    this.token = options.token;
+  }
+  /**
+   * Connect to the WebSocket server
+   * @returns {Promise<void>} Resolves when connection is open
+   */
+  async connect() {
+    this.isExplicitlyDisconnected = false;
+    return new Promise((resolve, reject) => {
+      try {
+        const wsUrl = new URL(this.url);
+        wsUrl.searchParams.set("sessionId", this.sessionId);
+        wsUrl.searchParams.set("token", this.token);
+        this.ws = new WebSocket__default.default(wsUrl.toString());
+        this.ws.on("open", () => {
+          this.emit("open", {});
+          resolve();
+        });
+        this.ws.on("message", (data) => {
+          try {
+            const message = JSON.parse(data.toString());
+            this.handleMessage(message);
+          } catch (error) {
+            console.error("[Granular] Failed to parse message:", error);
+          }
+        });
+        this.ws.on("error", (error) => {
+          this.emit("error", error);
+          if (this.ws?.readyState !== WebSocket__default.default.OPEN) {
+            reject(error);
+          }
+        });
+        this.ws.on("close", () => {
+          this.emit("close", {});
+          this.handleDisconnect();
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+  handleDisconnect() {
+    this.ws = null;
+    if (!this.isExplicitlyDisconnected) {
+      this.reconnectTimer = setTimeout(() => {
+        console.log("[Granular] Attempting reconnect...");
+        this.connect().catch((e) => console.error("[Granular] Reconnect failed:", e));
+      }, 3e3);
+    }
+  }
+  handleMessage(message) {
+    if (typeof message !== "object" || message === null) return;
+    console.log("[Granular DEBUG] Received message:", JSON.stringify(message).slice(0, 500));
+    if ("type" in message && message.type === "sync") {
+      const syncMessage = message;
+      try {
+        let bytes;
+        const payload = syncMessage.message || syncMessage.data;
+        if (typeof payload === "string") {
+          const binaryString = atob(payload);
+          const len = binaryString.length;
+          bytes = new Uint8Array(len);
+          for (let i = 0; i < len; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+          }
+        } else if (Array.isArray(payload)) {
+          bytes = new Uint8Array(payload);
+        } else if (payload instanceof Uint8Array) {
+          bytes = payload;
+        } else {
+          return;
+        }
+        const [newDoc, newSyncState] = Automerge__namespace.receiveSyncMessage(
+          this.doc,
+          this.syncState,
+          bytes
+        );
+        this.doc = newDoc;
+        this.syncState = newSyncState;
+        this.emit("sync", this.doc);
+      } catch (e) {
+      }
+      return;
+    }
+    if ("type" in message && (message.type === "rpc_result" || message.type === "rpc_error")) {
+      const response = message;
+      const pending = this.messageQueue.find((q) => q.id === response.id);
+      if (pending) {
+        if (response.type === "rpc_error") {
+          pending.reject(
+            new Error(`RPC error: ${response.error?.message || "Unknown error"}`)
+          );
+        } else {
+          pending.resolve(response.result);
+        }
+        this.messageQueue = this.messageQueue.filter((q) => q.id !== response.id);
+      }
+      return;
+    }
+    if ("type" in message && message.type === "rpc" && "method" in message && "id" in message) {
+      const request = message;
+      this.handleIncomingRpc(request).catch((error) => {
+        console.error("[Granular] Error handling incoming RPC:", error);
+      });
+      return;
+    }
+    if ("type" in message && typeof message.type === "string") {
+      this.emit(message.type, message);
+    }
+  }
+  /**
+   * Make an RPC call to the server
+   * @param {string} method - RPC method name
+   * @param {unknown} params - Request parameters
+   * @returns {Promise<unknown>} Response result
+   * @throws {Error} If connection is closed or timeout occurs
+   */
+  async call(method, params) {
+    if (!this.ws || this.ws.readyState !== WebSocket__default.default.OPEN) {
+      throw new Error("WebSocket not connected");
+    }
+    const id = `rpc-${this.nextRpcId++}`;
+    const request = {
+      type: "rpc",
+      method,
+      params,
+      id
+    };
+    return new Promise((resolve, reject) => {
+      this.messageQueue.push({ resolve, reject, id });
+      this.ws.send(JSON.stringify(request));
+      setTimeout(() => {
+        const pending = this.messageQueue.find((q) => q.id === id);
+        if (pending) {
+          this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
+          reject(new Error(`RPC timeout: ${method}`));
+        }
+      }, 3e4);
+    });
+  }
+  async handleIncomingRpc(request) {
+    const handler = this.rpcHandlers.get(request.method);
+    if (!handler) {
+      const errorResponse = {
+        type: "rpc_error",
+        id: request.id,
+        error: {
+          code: -32601,
+          message: `Method not found: ${request.method}`
+        }
+      };
+      this.ws?.send(JSON.stringify(errorResponse));
+      return;
+    }
+    try {
+      const result = await handler(request.params);
+      if (request.method !== "tool.invoke") {
+        const successResponse = {
+          type: "rpc_result",
+          id: request.id,
+          result
+        };
+        this.ws?.send(JSON.stringify(successResponse));
+      }
+    } catch (error) {
+      const errorResponse = {
+        type: "rpc_error",
+        id: request.id,
+        error: {
+          code: -32e3,
+          message: error instanceof Error ? error.message : "Unknown error"
+        }
+      };
+      this.ws?.send(JSON.stringify(errorResponse));
+    }
+  }
+  /**
+   * Subscribe to client events
+   * @param {string} event - Event name
+   * @param {Function} handler - Event handler
+   */
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event).push(handler);
+  }
+  /**
+   * Register an RPC handler for incoming server requests
+   * @param {string} method - RPC method name
+   * @param {Function} handler - Handler function
+   */
+  registerRpcHandler(method, handler) {
+    this.rpcHandlers.set(method, handler);
+  }
+  /**
+   * Unsubscribe from client events
+   * @param {string} event - Event name
+   * @param {Function} handler - Handler to remove
+   */
+  off(event, handler) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      this.eventHandlers.set(
+        event,
+        handlers.filter((h) => h !== handler)
+      );
+    }
+  }
+  /**
+   * Emit an event locally
+   * @param {string} event - Event name
+   * @param params - Event data
+   */
+  emit(event, params) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => handler(params));
+    }
+  }
+  /**
+   * Disconnect the WebSocket and clear state
+   */
+  disconnect() {
+    this.isExplicitlyDisconnected = true;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.messageQueue.forEach((q) => q.reject(new Error("Client explicitly disconnected")));
+    this.messageQueue = [];
+    this.rpcHandlers.clear();
+    this.emit("disconnect", {});
+  }
+};
+
+// src/session.ts
+var Session = class {
+  client;
+  clientId;
+  jobsMap = /* @__PURE__ */ new Map();
+  eventListeners = /* @__PURE__ */ new Map();
+  toolHandlers = /* @__PURE__ */ new Map();
+  /** Tracks which tools are instance methods (className set, not static) */
+  instanceTools = /* @__PURE__ */ new Set();
+  currentDomainRevision = null;
+  constructor(client, clientId) {
+    this.client = client;
+    this.clientId = clientId || `client_${Date.now()}`;
+    this.setupEventHandlers();
+    this.setupToolInvokeHandler();
+  }
+  // --- Public API ---
+  get document() {
+    return this.client.doc;
+  }
+  get domainRevision() {
+    return this.currentDomainRevision;
+  }
+  /**
+   * Make a raw RPC call to the session's Durable Object.
+   *
+   * Use this when you need to call an RPC method that doesn't have a
+   * dedicated wrapper method on the Session/Environment class.
+   *
+   * @param method - RPC method name (e.g. 'domain.fetchPackagePart')
+   * @param params - Request parameters
+   * @returns The raw RPC response
+   *
+   * @example
+   * ```typescript
+   * const result = await env.rpc('domain.fetchPackagePart', {
+   *   moduleSpecifier: '@sandbox/domain',
+   *   part: 'types',
+   * });
+   * ```
+   */
+  async rpc(method, params = {}) {
+    return this.client.call(method, params);
+  }
+  /**
+   * Send client hello to establish the session
+   */
+  async hello() {
+    const result = await this.client.call("client.hello", {
+      clientId: this.clientId,
+      protocolVersion: "2.0"
+    });
+    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
+    };
+  }
+  /**
+   * Submit a job to execute code in the sandbox.
+   *
+   * The code can import typed classes from `./sandbox-tools`:
+   * ```typescript
+   * import { Author, Book, global_search } from './sandbox-tools';
+   *
+   * const tolkien = await Author.find({ id: 'tolkien' });
+   * const bio = await tolkien.get_bio({ detailed: true });
+   * 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
+   * execute locally and return the result to the sandbox.
+   */
+  async submitJob(code, domainRevision) {
+    const revision = domainRevision || this.currentDomainRevision;
+    if (!revision) {
+      throw new Error("No domain revision available. Call publishTools() first.");
+    }
+    const result = await this.client.call("job.submit", {
+      domainRevision: revision,
+      code
+    });
+    if (!result.jobId) {
+      throw new Error("Failed to submit job: no jobId returned");
+    }
+    const job = new JobImplementation(result.jobId, this.client);
+    this.jobsMap.set(result.jobId, job);
+    return job;
+  }
+  /**
+   * Register a handler for a specific tool.
+   * @param isInstance - If true, handler will receive (id, params) for instance method dispatch.
+   */
+  registerToolHandler(name, handler, isInstance = false) {
+    this.toolHandlers.set(name, handler);
+    if (isInstance) {
+      this.instanceTools.add(name);
+    } else {
+      this.instanceTools.delete(name);
+    }
+  }
+  /**
+   * Respond to a prompt request from the sandbox
+   */
+  async answerPrompt(promptId, answer) {
+    await this.client.call("prompt.answer", { promptId, value: answer });
+  }
+  /**
+   * Get the current domain state and available tools
+   */
+  async getDomain() {
+    return this.client.call("domain.getSummary", {});
+  }
+  /**
+   * Get auto-generated TypeScript class declarations for the current domain.
+   *
+   * Returns typed declarations including:
+   * - Classes with readonly properties (from manifest)
+   * - `static find(query: { id: string })` for each class
+   * - Instance methods with typed input/output (from `publishTools` with `className`)
+   * - Static methods (from `publishTools` with `className` + `static: true`)
+   * - Relationship accessors (`get_books()`, `get_author()`, etc.)
+   * - Global tool functions (from `publishTools` without `className`)
+   *
+   * Pass this documentation to LLMs so they can write correct typed code
+   * that imports from `./sandbox-tools`.
+   *
+   * Falls back to generating markdown docs from the domain summary if
+   * the synthesis server is unavailable.
+   */
+  async getDomainDocumentation() {
+    try {
+      const typesResult = await this.client.call("domain.fetchPackagePart", {
+        moduleSpecifier: "@sandbox/domain",
+        part: "types"
+      });
+      if (typesResult.content) {
+        return typesResult.content;
+      }
+    } catch {
+    }
+    const summary = await this.getDomain();
+    return this.generateFallbackDocs(summary);
+  }
+  /**
+   * Generate markdown documentation from the domain summary.
+   * Class-aware: groups tools by class with property/relationship info.
+   */
+  generateFallbackDocs(summary) {
+    const classes = summary.classes;
+    const globalTools = summary.globalTools;
+    const tools = summary.tools || [];
+    if (classes && Object.keys(classes).length > 0) {
+      let docs2 = "# Domain Documentation\n\n";
+      docs2 += "Import classes and tools from `./sandbox-tools`:\n\n";
+      const classNames = Object.keys(classes).map(
+        (c) => c.charAt(0).toUpperCase() + c.slice(1)
+      );
+      const globalNames = (globalTools || []).map((t) => t.name);
+      const allImports = [...classNames, ...globalNames].join(", ");
+      docs2 += `\`\`\`typescript
+import { ${allImports} } from "./sandbox-tools";
+\`\`\`
+
+`;
+      for (const [className, cls] of Object.entries(classes)) {
+        const TsName = className.charAt(0).toUpperCase() + className.slice(1);
+        docs2 += `## ${TsName}
+
+`;
+        if (cls.description) docs2 += `${cls.description}
+
+`;
+        if (cls.properties?.length > 0) {
+          docs2 += "**Properties:**\n";
+          for (const p of cls.properties) {
+            docs2 += `- \`${p.name}\`${p.description ? ": " + p.description : ""}
+`;
+          }
+          docs2 += "\n";
+        }
+        if (cls.relationships?.length > 0) {
+          docs2 += "**Relationships:**\n";
+          for (const r of cls.relationships) {
+            const fModel = r.foreignModel?.charAt(0).toUpperCase() + r.foreignModel?.slice(1);
+            docs2 += `- \`${r.localSubmodel}\` \u2192 ${fModel} (${r.kind})
+`;
+          }
+          docs2 += "\n";
+        }
+        if (cls.methods?.length > 0) {
+          docs2 += "**Methods:**\n";
+          for (const m of cls.methods) {
+            docs2 += `- \`${TsName}.${m.name}(input)\``;
+            if (m.description) docs2 += `: ${m.description}`;
+            docs2 += "\n";
+            if (m.inputSchema?.properties) {
+              docs2 += "  ```json\n  " + JSON.stringify(m.inputSchema, null, 2).replace(/\n/g, "\n  ") + "\n  ```\n";
+            }
+          }
+          docs2 += "\n";
+        }
+      }
+      if (globalTools && globalTools.length > 0) {
+        docs2 += "## Global Tools\n\n";
+        for (const tool of globalTools) {
+          docs2 += `### ${tool.name}
+
+`;
+          if (tool.description) docs2 += `${tool.description}
+
+`;
+          if (tool.inputSchema) {
+            docs2 += "**Input Schema:**\n```json\n";
+            docs2 += JSON.stringify(tool.inputSchema, null, 2);
+            docs2 += "\n```\n\n";
+          }
+        }
+      }
+      return docs2;
+    }
+    if (!tools || tools.length === 0) {
+      return "No tools available in this domain.";
+    }
+    let docs = "# Available Tools\n\n";
+    docs += "Import tools 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);
+`;
+    docs += "```\n\n";
+    for (const tool of tools) {
+      docs += `## ${tool.name}
+
+`;
+      if (tool.description) {
+        docs += `${tool.description}
+
+`;
+      }
+      if (tool.inputSchema) {
+        docs += "**Input Schema:**\n```json\n";
+        docs += JSON.stringify(tool.inputSchema, null, 2);
+        docs += "\n```\n\n";
+      }
+      if (tool.outputSchema) {
+        docs += "**Output Schema:**\n```json\n";
+        docs += JSON.stringify(tool.outputSchema, null, 2);
+        docs += "\n```\n\n";
+      }
+    }
+    return docs;
+  }
+  /**
+   * Close the session and disconnect from the sandbox
+   */
+  async disconnect() {
+    this.client.disconnect();
+  }
+  // --- Event Handling ---
+  /**
+   * Subscribe to session events
+   */
+  on(event, handler) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, []);
+    }
+    this.eventListeners.get(event).push(handler);
+  }
+  /**
+   * Unsubscribe from session events
+   */
+  off(event, handler) {
+    const handlers = this.eventListeners.get(event);
+    if (handlers) {
+      this.eventListeners.set(event, handlers.filter((h) => h !== handler));
+    }
+  }
+  // --- Internal ---
+  setupToolInvokeHandler() {
+    this.client.registerRpcHandler("tool.invoke", async (params) => {
+      const { callId, toolName, input } = params;
+      this.emit("tool:invoke", { callId, toolName, input });
+      const handler = this.toolHandlers.get(toolName);
+      if (!handler) {
+        await this.client.call("tool.result", {
+          callId,
+          error: { code: "TOOL_NOT_FOUND", message: `Tool handler not found: ${toolName}` }
+        });
+        return;
+      }
+      try {
+        let result;
+        if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
+          const { _objectId, ...restParams } = input;
+          result = await handler(_objectId, restParams);
+        } else {
+          result = await handler(input);
+        }
+        this.emit("tool:result", { callId, result });
+        await this.client.call("tool.result", {
+          callId,
+          result
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.emit("tool:result", { callId, error: errorMessage });
+        await this.client.call("tool.result", {
+          callId,
+          error: { code: "TOOL_EXECUTION_FAILED", message: errorMessage }
+        });
+      }
+    });
+  }
+  setupEventHandlers() {
+    this.client.on("sync", (doc) => this.emit("sync", doc));
+    this.client.on("prompt", (prompt) => this.emit("prompt", prompt));
+    this.client.on("disconnect", () => this.emit("disconnect", {}));
+    this.client.on("job.status", (data) => {
+      this.emit("job:status", data);
+    });
+    this.client.on("exec.completed", (data) => {
+      this.emit("exec:completed", data);
+    });
+    this.client.on("exec.progress", (data) => {
+      this.emit("exec:progress", data);
+    });
+  }
+  emit(event, data) {
+    const handlers = this.eventListeners.get(event);
+    if (handlers) {
+      handlers.forEach((h) => h(data));
+    }
+  }
+};
+var JobImplementation = class {
+  id;
+  client;
+  status = "queued";
+  _resultPromise;
+  _resolveResult;
+  _rejectResult;
+  eventListeners = /* @__PURE__ */ new Map();
+  constructor(id, client) {
+    this.id = id;
+    this.client = client;
+    this._resultPromise = new Promise((resolve, reject) => {
+      this._resolveResult = resolve;
+      this._rejectResult = reject;
+    });
+    this.client.on("exec.completed", (data) => {
+      const execData = data;
+      if (execData.execId === id || execData.jobId === id) {
+        this.status = "succeeded";
+        this.emit("status", this.status);
+        if (execData.error) {
+          this._rejectResult(execData.error);
+        } else {
+          this._resolveResult(execData.result);
+        }
+      }
+    });
+    this.client.on("exec.progress", (data) => {
+      const progressData = data;
+      if (progressData.execId === id || progressData.jobId === id) {
+        if (progressData.stdout) {
+          this.emit("stdout", progressData.stdout);
+        }
+        if (progressData.stderr) {
+          this.emit("stderr", progressData.stderr);
+        }
+      }
+    });
+    this.client.on(`job.${id}.status`, (status) => {
+      this.status = status;
+      this.emit("status", status);
+    });
+    this.client.on(`job.${id}.stdout`, (line) => {
+      this.emit("stdout", line);
+    });
+    this.client.on(`job.${id}.stderr`, (line) => {
+      this.emit("stderr", line);
+    });
+    this.client.on(`job.${id}.result`, (result) => {
+      this.status = "succeeded";
+      this._resolveResult(result);
+    });
+    this.client.on(`job.${id}.error`, (error) => {
+      this.status = "failed";
+      this._rejectResult(error);
+    });
+    this.client.on("job.completed", (data) => {
+      const jobData = data;
+      if (jobData.jobId === id) {
+        this.status = "succeeded";
+        this.emit("status", this.status);
+        this._resolveResult(jobData.result);
+      }
+    });
+    this.client.on("job.failed", (data) => {
+      const jobData = data;
+      if (jobData.jobId === id) {
+        this.status = "failed";
+        this.emit("status", this.status);
+        this._rejectResult(jobData.error || new Error("Job failed"));
+      }
+    });
+  }
+  get result() {
+    return this._resultPromise;
+  }
+  on(event, handler) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, []);
+    }
+    this.eventListeners.get(event).push(handler);
+  }
+  emit(event, data) {
+    const handlers = this.eventListeners.get(event);
+    if (handlers) {
+      handlers.forEach((h) => h(data));
+    }
+  }
+};
+
+// src/client.ts
+var STANDARD_MODULES_OPERATIONS = [
+  { create: "entity", has: { id: { value: "auto-generated" }, createdAt: { value: void 0 } } },
+  { create: "class", extends: "entity", has: {} },
+  { create: "user", extends: "entity", has: { email: { value: void 0 }, firstName: { value: void 0 }, lastName: { value: void 0 } } },
+  { create: "company", extends: "entity", has: { name: { value: void 0 }, website: { value: void 0 } } },
+  { create: "string", has: { value: { value: void 0 } } },
+  { create: "number", has: { value: { value: 0 } } },
+  { create: "boolean", has: { value: { value: false } } },
+  { create: "tool_parameter", has: { name: { value: void 0 }, type: { value: "string" }, description: { value: void 0 }, required: { value: false } } }
+];
+var BUILTIN_MODULES = {
+  "standard_modules": STANDARD_MODULES_OPERATIONS
+};
+var Environment = class _Environment extends Session {
+  envData;
+  _apiKey;
+  _apiEndpoint;
+  constructor(client, envData, clientId, apiKey, apiEndpoint) {
+    super(client, clientId);
+    this.envData = envData;
+    this._apiKey = apiKey;
+    this._apiEndpoint = apiEndpoint;
+  }
+  /** The environment ID */
+  get environmentId() {
+    return this.envData.environmentId;
+  }
+  /** The sandbox ID */
+  get sandboxId() {
+    return this.envData.sandboxId;
+  }
+  /** The subject ID */
+  get subjectId() {
+    return this.envData.subjectId;
+  }
+  /** The permission profile ID */
+  get permissionProfileId() {
+    return this.envData.permissionProfileId;
+  }
+  /** The GraphQL API endpoint URL */
+  get apiEndpoint() {
+    return this._apiEndpoint;
+  }
+  // ==================== ID ↔ GRAPH PATH MAPPING ====================
+  /**
+   * Convert a class name + real-world ID into a unique graph path.
+   *
+   * Two objects of *different* classes may share the same real-world ID,
+   * so the graph path must incorporate the class to guarantee uniqueness.
+   *
+   * Format: `{className}_{id}` — deterministic, human-readable.
+   *
+   * **Convention**: class names should be simple identifiers without
+   * underscores (e.g. `author`, `book`).  This ensures the prefix is
+   * unambiguously parseable by `extractIdFromGraphPath`.
+   */
+  static toGraphPath(className, id) {
+    return `${className}_${id}`;
+  }
+  /**
+   * Extract the real-world ID from a graph path, given the class name.
+   *
+   * Strips the `{className}_` prefix. Returns the raw path if the
+   * expected prefix is not found.
+   */
+  static extractIdFromGraphPath(graphPath, className) {
+    const prefix = `${className}_`;
+    return graphPath.startsWith(prefix) ? graphPath.substring(prefix.length) : graphPath;
+  }
+  /**
+   * Execute a GraphQL query against the environment's graph.
+   * 
+   * The query uses the Granular graph query language (based on Cypher/GraphQL).
+   * Authentication is handled automatically using the SDK's API key.
+   * 
+   * @param query - The GraphQL query string
+   * @param variables - Optional variables for the query
+   * @returns The query result data
+   * 
+   * @example
+   * ```typescript
+   * // Read the workspace
+   * const result = await env.graphql(
+   *   `query { model(path: "workspace") { path label submodels { path label } } }`
+   * );
+   * console.log(result.data);
+   * 
+   * // Create a model
+   * const created = await env.graphql(
+   *   `mutation { at(path: "workspace") { create_submodel(subpath: "my_node", label: "My Node", prototype: "Model") { model { path label } } } }`
+   * );
+   * ```
+   */
+  async graphql(query, variables) {
+    const response = await fetch(this._apiEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this._apiKey}`
+      },
+      body: JSON.stringify({
+        environmentId: this.environmentId,
+        query,
+        variables
+      })
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GraphQL API Error (${response.status}): ${errorText}`);
+    }
+    return response.json();
+  }
+  // ==================== RELATIONSHIP METHODS ====================
+  /**
+   * Define a relationship between two model types.
+   * 
+   * Creates both submodels (if they don't exist) and links them with
+   * a RelationshipDef node that encodes cardinality.
+   * 
+   * @example
+   * ```typescript
+   * // Author has many Books, Book has one Author
+   * const rel = await env.defineRelationship({
+   *   model: 'author',
+   *   localSubmodel: 'books',
+   *   localIsMany: true,
+   *   foreignModel: 'book',
+   *   foreignSubmodel: 'author',
+   *   foreignIsMany: false,
+   * });
+   * console.log(rel.relationship_kind); // "one_to_many"
+   * ```
+   */
+  async defineRelationship(options) {
+    const result = await this.graphql(
+      `mutation DefineRelationship(
+                $localSubmodel: String!,
+                $foreignModel: String!,
+                $foreignSubmodel: String!,
+                $localIsMany: Boolean!,
+                $foreignIsMany: Boolean!,
+                $name: String
+            ) {
+                at(path: "${options.model}") {
+                    define_relationship(
+                        local_submodel: $localSubmodel
+                        foreign_model: $foreignModel
+                        foreign_submodel: $foreignSubmodel
+                        local_is_many: $localIsMany
+                        foreign_is_many: $foreignIsMany
+                        name: $name
+                    ) {
+                        name
+                        local_submodel { path label }
+                        local_is_many
+                        foreign_submodel { path label }
+                        foreign_is_many
+                        foreign_model { path label }
+                        relationship_kind
+                    }
+                }
+            }`,
+      {
+        localSubmodel: options.localSubmodel,
+        foreignModel: options.foreignModel,
+        foreignSubmodel: options.foreignSubmodel,
+        localIsMany: options.localIsMany,
+        foreignIsMany: options.foreignIsMany,
+        name: options.name
+      }
+    );
+    if (result.errors?.length) {
+      throw new Error(`defineRelationship failed: ${result.errors[0].message}`);
+    }
+    return result.data.at.define_relationship;
+  }
+  /**
+   * Get all relationships for a model type.
+   * 
+   * @param modelPath - The model type path (e.g., "author")
+   * @returns Array of relationships from this model's perspective
+   * 
+   * @example
+   * ```typescript
+   * const rels = await env.getRelationships('author');
+   * for (const rel of rels) {
+   *   console.log(`${rel.local_submodel.path} -> ${rel.foreign_model.path} (${rel.relationship_kind})`);
+   * }
+   * ```
+   */
+  async getRelationships(modelPath) {
+    const result = await this.graphql(
+      `query GetRelationships($path: String) {
+                model(path: $path) {
+                    relationships {
+                        name
+                        local_submodel { path label }
+                        local_is_many
+                        foreign_submodel { path label }
+                        foreign_is_many
+                        foreign_model { path label }
+                        relationship_kind
+                    }
+                }
+            }`,
+      { path: modelPath }
+    );
+    if (result.errors?.length) {
+      throw new Error(`getRelationships failed: ${result.errors[0].message}`);
+    }
+    return result.data?.model?.relationships || [];
+  }
+  /**
+   * Attach a target model to a relationship submodel.
+   * 
+   * Handles cardinality automatically:
+   * - "One" side: sets/replaces the reference
+   * - "Many" side: adds the target to the collection
+   * 
+   * If the target model doesn't exist, it's created as an instance of the foreign type.
+   * Bidirectional sync is automatic.
+   * 
+   * @param modelPath - The model instance path (e.g., "tolkien")
+   * @param submodelPath - The relationship submodel (e.g., "books")
+   * @param targetPath - The target model to attach (e.g., "lord_of_the_rings")
+   * 
+   * @example
+   * ```typescript
+   * // Attach a book to an author (many side)
+   * await env.attach('tolkien', 'books', 'lord_of_the_rings');
+   * // This also automatically sets lord_of_the_rings:author -> tolkien
+   * ```
+   */
+  async attach(modelPath, submodelPath, targetPath) {
+    const result = await this.graphql(
+      `mutation Attach($target: String!) {
+                at(path: "${modelPath}") {
+                    at(submodel: "${submodelPath}") {
+                        attach(target: $target) {
+                            model { path }
+                        }
+                    }
+                }
+            }`,
+      { target: targetPath }
+    );
+    if (result.errors?.length) {
+      throw new Error(`attach failed: ${result.errors[0].message}`);
+    }
+  }
+  /**
+   * Detach a target model from a relationship submodel.
+   * 
+   * Handles bidirectional cleanup automatically.
+   * 
+   * @param modelPath - The model instance path
+   * @param submodelPath - The relationship submodel
+   * @param targetPath - The target to detach (optional for "one" side; omit on "many" side to detach all)
+   * 
+   * @example
+   * ```typescript
+   * // Detach a specific book
+   * await env.detach('tolkien', 'books', 'lord_of_the_rings');
+   * 
+   * // Detach all books
+   * await env.detach('tolkien', 'books');
+   * ```
+   */
+  async detach(modelPath, submodelPath, targetPath) {
+    const targetArg = targetPath ? `target: "${targetPath}"` : "";
+    const result = await this.graphql(
+      `mutation Detach {
+                at(path: "${modelPath}") {
+                    at(submodel: "${submodelPath}") {
+                        detach(${targetArg}) {
+                            model { path }
+                        }
+                    }
+                }
+            }`
+    );
+    if (result.errors?.length) {
+      throw new Error(`detach failed: ${result.errors[0].message}`);
+    }
+  }
+  /**
+   * List all related models through a relationship submodel.
+   * 
+   * @param modelPath - The model instance path
+   * @param submodelPath - The relationship submodel
+   * @returns Array of related model references
+   * 
+   * @example
+   * ```typescript
+   * const books = await env.listRelated('tolkien', 'books');
+   * console.log(books); // [{ path: "lord_of_the_rings", label: "Lord of the Rings" }, ...]
+   * ```
+   */
+  async listRelated(modelPath, submodelPath) {
+    const result = await this.graphql(
+      `mutation ListRelated {
+                at(path: "${modelPath}") {
+                    at(submodel: "${submodelPath}") {
+                        list_related { path label }
+                    }
+                }
+            }`
+    );
+    if (result.errors?.length) {
+      throw new Error(`listRelated failed: ${result.errors[0].message}`);
+    }
+    return result.data?.at?.at?.list_related || [];
+  }
+  /**
+   * Apply a manifest to the current environment's graph.
+   * 
+   * Translates each manifest operation into GraphQL mutations and executes them
+   * in order. This is the core mechanism for creating classes, fields, and
+   * relationships from a declarative manifest.
+   * 
+   * @param manifest - The manifest content to apply
+   * @returns Summary of applied operations
+   * 
+   * @example
+   * ```typescript
+   * await environment.applyManifest({
+   *   schemaVersion: 2,
+   *   name: 'my-app',
+   *   volumes: [{
+   *     name: 'schema',
+   *     scope: 'sandbox',
+   *     operations: [
+   *       { create: 'author', extends: 'class', has: { name: { type: 'string' } } },
+   *       { create: 'book', extends: 'class', has: { title: { type: 'string' } } },
+   *       { defineRelationship: {
+   *         left: 'author', right: 'book',
+   *         leftSubmodel: 'books', rightSubmodel: 'author',
+   *         leftIsMany: true, rightIsMany: false,
+   *       }},
+   *     ],
+   *   }],
+   * });
+   * ```
+   */
+  async applyManifest(manifest) {
+    const errors = [];
+    let applied = 0;
+    for (const volume of manifest.volumes) {
+      const aliasMap = {};
+      if (volume.imports) {
+        for (const imp of volume.imports) {
+          aliasMap[imp.alias] = imp.name;
+          const builtinOps = BUILTIN_MODULES[imp.name];
+          if (builtinOps) {
+            for (const op of builtinOps) {
+              try {
+                await this._applyOperation(op, {});
+                applied++;
+              } catch (err) {
+                if (!err.message?.includes("already exists")) {
+                  errors.push(`Import ${imp.name} operation failed: ${err.message}`);
+                }
+              }
+            }
+          } else {
+            errors.push(`Unknown module: "${imp.name}" (only built-in modules are supported)`);
+          }
+        }
+      }
+      for (const op of volume.operations) {
+        try {
+          await this._applyOperation(op, aliasMap);
+          applied++;
+        } catch (err) {
+          errors.push(`Operation failed: ${err.message}`);
+        }
+      }
+    }
+    return { applied, errors };
+  }
+  /**
+   * Resolve an alias reference like "@std/class" → "class"
+   * Strips the alias prefix, returning the bare model path.
+   */
+  _resolveAlias(ref, aliasMap) {
+    if (!ref.startsWith("@")) return ref;
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx === -1) return ref;
+    const alias = ref.substring(0, slashIdx);
+    const symbolName = ref.substring(slashIdx + 1);
+    if (aliasMap[alias]) {
+      return symbolName;
+    }
+    return ref;
+  }
+  /**
+   * Apply a single manifest operation via GraphQL
+   */
+  async _applyOperation(op, aliasMap) {
+    if (op.defineRelationship) {
+      const rel = op.defineRelationship;
+      await this.defineRelationship({
+        model: this._resolveAlias(rel.left, aliasMap),
+        localSubmodel: rel.leftSubmodel,
+        localIsMany: rel.leftIsMany,
+        foreignModel: this._resolveAlias(rel.right, aliasMap),
+        foreignSubmodel: rel.rightSubmodel,
+        foreignIsMany: rel.rightIsMany,
+        name: rel.name
+      });
+      return;
+    }
+    if (op.create) {
+      const label = op.create.charAt(0).toUpperCase() + op.create.slice(1);
+      const extendsRef = op.extends ? this._resolveAlias(op.extends, aliasMap) : void 0;
+      const instanceOfRef = op.instanceOf ? this._resolveAlias(op.instanceOf, aliasMap) : void 0;
+      if (extendsRef) {
+        await this.graphql(
+          `mutation { create_model(path: "${op.create}", label: "${label}") { model { path } } }`
+        );
+        await this.graphql(
+          `mutation { at(path: "${op.create}") { add_superclass(superclass: "${extendsRef}") { model { path } } } }`
+        );
+      } else if (instanceOfRef) {
+        await this.graphql(
+          `mutation { at(path: "${instanceOfRef}") { instantiate(path: "${op.create}", label: "${label}") { model { path } } } }`
+        );
+      } else {
+        await this.graphql(
+          `mutation { create_model(path: "${op.create}", label: "${label}") { model { path } } }`
+        );
+      }
+      if (op.has) {
+        await this._applyFields(op.create, op.has);
+      }
+      return;
+    }
+    if (op.on) {
+      const target = this._resolveAlias(op.on, aliasMap);
+      if (op.has) {
+        await this._applyFields(target, op.has);
+      }
+      return;
+    }
+  }
+  /**
+   * Apply field definitions (has) to a model via GraphQL
+   */
+  async _applyFields(modelPath, fields) {
+    for (const [fieldName, spec] of Object.entries(fields)) {
+      const fieldLabel = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
+      await this.graphql(
+        `mutation {
+                    at(path: "${modelPath}") {
+                        create_submodel(subpath: "${fieldName}", label: "${fieldLabel}") {
+                            model { path }
+                        }
+                    }
+                }`
+      );
+      if (spec.type) {
+        await this.graphql(
+          `mutation {
+                        at(path: "${modelPath}") {
+                            at(submodel: "${fieldName}") {
+                                add_prototype(prototype: "${spec.type}") { done }
+                            }
+                        }
+                    }`
+        );
+      }
+      if (spec.description) {
+        await this.graphql(
+          `mutation {
+                        at(path: "${modelPath}") {
+                            at(submodel: "${fieldName}") {
+                                set_description(description: "${spec.description}") { done }
+                            }
+                        }
+                    }`
+        );
+      }
+      if (spec.value !== void 0 && spec.value !== null) {
+        if (typeof spec.value === "string") {
+          await this.graphql(
+            `mutation {
+                            at(path: "${modelPath}") {
+                                at(submodel: "${fieldName}") {
+                                    set_string_value(value: "${spec.value}") { done }
+                                }
+                            }
+                        }`
+          );
+        } else if (typeof spec.value === "number") {
+          await this.graphql(
+            `mutation {
+                            at(path: "${modelPath}") {
+                                at(submodel: "${fieldName}") {
+                                    set_number_value(value: ${spec.value}) { done }
+                                }
+                            }
+                        }`
+          );
+        } else if (typeof spec.value === "boolean") {
+          await this.graphql(
+            `mutation {
+                            at(path: "${modelPath}") {
+                                at(submodel: "${fieldName}") {
+                                    set_boolean_value(value: ${spec.value}) { done }
+                                }
+                            }
+                        }`
+          );
+        }
+      }
+      if (spec.ref) {
+        await this.graphql(
+          `mutation {
+                        at(path: "${modelPath}") {
+                            at(submodel: "${fieldName}") {
+                                set_reference(reference: "${spec.ref}") { done }
+                            }
+                        }
+                    }`
+        );
+      }
+      if (spec.has) {
+        await this._applyFields(`${modelPath}:${fieldName}`, spec.has);
+      }
+    }
+  }
+  // ==================== RECORD OBJECT ====================
+  /**
+   * Create or update an instance of a class in the graph.
+   *
+   * Uses `instantiate` under the hood, which has find-or-create semantics:
+   * if an instance with the given `id` already exists for the class it is
+   * returned; otherwise a new instance is created.  Fields are then set
+   * (overwriting previous values) and relationships are attached.
+   *
+   * The graph path is derived as `{className}_{id}` to ensure uniqueness
+   * across classes (two objects of different classes may share the same
+   * real-world ID).  Relationship targets are also resolved automatically
+   * using the foreign class from the relationship definition.
+   *
+   * @param options - The object specification
+   * @returns The graph path, real-world ID, and creation status
+   *
+   * @example
+   * ```typescript
+   * // Create an author with fields
+   * const result = await env.recordObject({
+   *   className: 'author',
+   *   id: 'tolkien',
+   *   label: 'J.R.R. Tolkien',
+   *   fields: { name: 'J.R.R. Tolkien', birth_year: 1892 },
+   *   relationships: { books: ['lotr', 'silmarillion'] },
+   * });
+   * // result.path → 'author_tolkien'  (internal graph path)
+   * // result.id   → 'tolkien'         (real-world ID)
+   * // result.created → true
+   * ```
+   */
+  async recordObject(options) {
+    const { className, id, label, fields, relationships } = options;
+    const graphPath = _Environment.toGraphPath(className, id);
+    const existsResult = await this.graphql(
+      `query { model(path: "${graphPath}") { path } }`
+    );
+    const alreadyExists = !!existsResult.data?.model;
+    const instResult = await this.graphql(
+      `mutation {
+                at(path: "${className}") {
+                    instantiate(path: "${graphPath}"${label ? `, label: "${label}"` : ""}) {
+                        model { path }
+                    }
+                }
+            }`
+    );
+    if (instResult.errors?.length) {
+      throw new Error(`recordObject instantiate failed: ${instResult.errors[0].message}`);
+    }
+    const instancePath = instResult.data?.at?.instantiate?.model?.path ?? graphPath;
+    await this.graphql(
+      `mutation {
+                at(path: "${instancePath}") {
+                    create_submodel(subpath: "_realId", label: "_realId") {
+                        model { path }
+                    }
+                }
+            }`
+    );
+    await this.graphql(
+      `mutation {
+                at(path: "${instancePath}") {
+                    at(submodel: "_realId") {
+                        set_string_value(value: "${id.replace(/"/g, '\\"')}") { done }
+                    }
+                }
+            }`
+    );
+    if (fields) {
+      for (const [fieldName, value] of Object.entries(fields)) {
+        if (value === null) continue;
+        await this.graphql(
+          `mutation {
+                        at(path: "${instancePath}") {
+                            create_submodel(subpath: "${fieldName}", label: "${fieldName}") {
+                                model { path }
+                            }
+                        }
+                    }`
+        );
+        if (typeof value === "string") {
+          await this.graphql(
+            `mutation {
+                            at(path: "${instancePath}") {
+                                at(submodel: "${fieldName}") {
+                                    set_string_value(value: "${value.replace(/"/g, '\\"')}") { done }
+                                }
+                            }
+                        }`
+          );
+        } else if (typeof value === "number") {
+          await this.graphql(
+            `mutation {
+                            at(path: "${instancePath}") {
+                                at(submodel: "${fieldName}") {
+                                    set_number_value(value: ${value}) { done }
+                                }
+                            }
+                        }`
+          );
+        } else if (typeof value === "boolean") {
+          await this.graphql(
+            `mutation {
+                            at(path: "${instancePath}") {
+                                at(submodel: "${fieldName}") {
+                                    set_boolean_value(value: ${value}) { done }
+                                }
+                            }
+                        }`
+          );
+        }
+      }
+    }
+    if (relationships) {
+      const rels = await this.getRelationships(className);
+      const relMap = {};
+      for (const rel of rels) {
+        const submodelLeaf = rel.local_submodel.path.includes(":") ? rel.local_submodel.path.split(":").pop() : rel.local_submodel.path;
+        relMap[submodelLeaf] = rel.foreign_model.path;
+      }
+      for (const [submodelName, targets] of Object.entries(relationships)) {
+        const foreignClass = relMap[submodelName];
+        const targetList = Array.isArray(targets) ? targets : [targets];
+        for (const target of targetList) {
+          const targetGraphPath = foreignClass ? _Environment.toGraphPath(foreignClass, target) : target;
+          await this.attach(instancePath, submodelName, targetGraphPath);
+        }
+      }
+    }
+    return { path: instancePath, id, created: !alreadyExists };
+  }
+  // ==================== 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;
+   * ```
+   */
+  async publishTools(tools, revision = "1.0.0") {
+    return super.publishTools(tools, revision);
+  }
+};
+var Granular = class {
+  apiKey;
+  apiUrl;
+  httpUrl;
+  /**
+   * Create a new Granular client
+   * @param options - Client configuration
+   */
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.apiUrl = options.apiUrl || "wss://api.granular.dev/v2/ws";
+    this.httpUrl = this.apiUrl.replace("wss://", "https://").replace("/ws", "");
+  }
+  /**
+   * Records/upserts a user and prepares them for sandbox connections
+   * 
+   * @param options - User options
+   * @returns The user object to pass to connect()
+   * 
+   * @example
+   * ```typescript
+   * const user = await granular.recordUser({
+   *   userId: 'user_123',
+   *   name: 'John Doe',
+   *   permissions: ['agent'],
+   * });
+   * ```
+   */
+  async recordUser(options) {
+    const subject = await this.request("/control/subjects", {
+      method: "POST",
+      body: JSON.stringify({
+        identityId: options.userId,
+        name: options.name,
+        email: options.email
+      })
+    });
+    return {
+      subjectId: subject.subjectId,
+      identityId: options.userId,
+      name: options.name,
+      email: options.email,
+      permissions: options.permissions || []
+    };
+  }
+  /**
+   * 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.
+   * 
+   * @param options - Connection options
+   * @returns An active environment session
+   * 
+   * @example
+   * ```typescript
+   * const user = await granular.recordUser({
+   *   userId: 'user_123',
+   *   permissions: ['agent'],
+   * });
+   * 
+   * const environment = await granular.connect({
+   *   sandbox: 'my-sandbox',
+   *   user,
+   * });
+   * 
+   * // Publish tools
+   * await environment.publishTools([
+   *   { name: 'greet', description: 'Say hello', inputSchema: {}, handler: async () => 'Hello!' },
+   * ]);
+   * 
+   * // Submit job
+   * const job = await environment.submitJob(`
+   *   import { tools } from './sandbox-tools';
+   *   return await tools.greet({});
+   * `);
+   * 
+   * console.log(await job.result); // 'Hello!'
+   * ```
+   */
+  async connect(options) {
+    const clientId = `client_${Date.now()}`;
+    const sandbox = await this.findOrCreateSandbox(options.sandbox);
+    for (const profileName of options.user.permissions) {
+      const profileId = await this.ensurePermissionProfile(sandbox.sandboxId, profileName);
+      await this.ensureAssignment(options.user.subjectId, sandbox.sandboxId, profileId);
+    }
+    const envData = await this.environments.create(sandbox.sandboxId, {
+      subjectId: options.user.subjectId,
+      permissionProfileId: null
+    });
+    const client = new WSClient({
+      url: this.apiUrl,
+      sessionId: envData.environmentId,
+      token: this.apiKey
+    });
+    await client.connect();
+    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
+    const environment = new Environment(client, envData, clientId, this.apiKey, graphqlEndpoint);
+    await environment.hello();
+    return environment;
+  }
+  /**
+   * Find a sandbox by name or create it if it doesn't exist
+   */
+  async findOrCreateSandbox(nameOrId) {
+    try {
+      const sandbox = await this.sandboxes.get(nameOrId);
+      return sandbox;
+    } catch {
+      const sandboxes = await this.sandboxes.list();
+      const existing = sandboxes.items.find((s) => s.name === nameOrId);
+      if (existing) {
+        return existing;
+      }
+      const created = await this.sandboxes.create({ name: nameOrId });
+      return created;
+    }
+  }
+  /**
+   * Ensure a permission profile exists for a sandbox, creating it if needed.
+   * If profileName matches an existing profile name, returns its ID.
+   * Otherwise, creates a new profile with default allow-all rules.
+   */
+  async ensurePermissionProfile(sandboxId, profileName) {
+    try {
+      const profiles = await this.permissionProfiles.list(sandboxId);
+      const existing = profiles.find((p) => p.name === profileName);
+      if (existing) {
+        return existing.permissionProfileId;
+      }
+    } catch {
+    }
+    const created = await this.permissionProfiles.create(sandboxId, {
+      name: profileName,
+      rules: {
+        tools: { allow: ["*"] },
+        resources: { allow: ["*"] }
+      }
+    });
+    return created.permissionProfileId;
+  }
+  /**
+   * Ensure an assignment exists for a subject in a sandbox with a permission profile
+   */
+  async ensureAssignment(subjectId, sandboxId, permissionProfileId) {
+    try {
+      const assignments = await this.request(
+        `/control/subjects/${subjectId}/assignments`
+      );
+      const existing = assignments.items.find(
+        (a) => a.sandboxId === sandboxId
+      );
+      if (existing) {
+        if (existing.permissionProfileId === permissionProfileId) {
+          return;
+        }
+        await this.request(`/control/assignments/${existing.assignmentId}`, {
+          method: "DELETE"
+        });
+      }
+    } catch {
+    }
+    await this.request(`/control/subjects/${subjectId}/assignments`, {
+      method: "POST",
+      body: JSON.stringify({
+        sandboxId,
+        subjectId,
+        permissionProfileId
+      })
+    });
+  }
+  /**
+   * Sandbox management API
+   */
+  get sandboxes() {
+    return {
+      list: async () => {
+        return this.request("/control/sandboxes");
+      },
+      get: async (id) => {
+        return this.request(`/control/sandboxes/${id}`);
+      },
+      create: async (data) => {
+        return this.request("/control/sandboxes", {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+      },
+      update: async (id, data) => {
+        return this.request(`/control/sandboxes/${id}`, {
+          method: "PATCH",
+          body: JSON.stringify(data)
+        });
+      },
+      delete: async (id) => {
+        return this.request(`/control/sandboxes/${id}`, {
+          method: "DELETE"
+        });
+      }
+    };
+  }
+  /**
+   * Permission Profile management for sandboxes
+   */
+  get permissionProfiles() {
+    return {
+      list: async (sandboxId) => {
+        const result = await this.request(
+          `/control/sandboxes/${sandboxId}/permission-profiles`
+        );
+        return result.items;
+      },
+      get: async (sandboxId, profileId) => {
+        return this.request(
+          `/control/sandboxes/${sandboxId}/permission-profiles/${profileId}`
+        );
+      },
+      create: async (sandboxId, data) => {
+        return this.request(
+          `/control/sandboxes/${sandboxId}/permission-profiles`,
+          {
+            method: "POST",
+            body: JSON.stringify(data)
+          }
+        );
+      },
+      delete: async (sandboxId, profileId) => {
+        return this.request(
+          `/control/sandboxes/${sandboxId}/permission-profiles/${profileId}`,
+          {
+            method: "DELETE"
+          }
+        );
+      }
+    };
+  }
+  /**
+   * Environment management
+   */
+  get environments() {
+    return {
+      list: async (sandboxId) => {
+        const result = await this.request(
+          `/control/sandboxes/${sandboxId}/environments`
+        );
+        return result.items;
+      },
+      get: async (environmentId) => {
+        return this.request(`/control/environments/${environmentId}`);
+      },
+      create: async (sandboxId, data) => {
+        return this.request(`/control/sandboxes/${sandboxId}/environments`, {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+      },
+      delete: async (environmentId) => {
+        return this.request(`/control/environments/${environmentId}`, {
+          method: "DELETE"
+        });
+      }
+    };
+  }
+  /**
+   * Subject management
+   */
+  get subjects() {
+    return {
+      get: async (subjectId) => {
+        return this.request(`/control/subjects/${subjectId}`);
+      },
+      listAssignments: async (subjectId) => {
+        return this.request(`/control/subjects/${subjectId}/assignments`);
+      }
+    };
+  }
+  /**
+   * @deprecated Use recordUser() instead
+   */
+  get users() {
+    return {
+      create: async (data) => {
+        return this.request("/control/subjects", {
+          method: "POST",
+          body: JSON.stringify({
+            identityId: data.id,
+            name: data.name,
+            email: data.email
+          })
+        });
+      },
+      get: async (id) => {
+        return this.request(`/control/subjects/${id}`);
+      }
+    };
+  }
+  /**
+   * Make an authenticated API request
+   */
+  async request(path, options = {}) {
+    const url = `${this.httpUrl}${path}`;
+    console.log(`[SDK] Requesting: ${url}`);
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Granular API Error (${response.status}): ${errorText}`);
+    }
+    if (response.status === 204) {
+      return { deleted: true };
+    }
+    return response.json();
+  }
+};
+
+exports.Environment = Environment;
+exports.Granular = Granular;
+exports.Session = Session;
+exports.WSClient = WSClient;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map