@granular-software/sdk 0.4.13 → 0.4.15

package/dist/index.mjs

@@ -5591,6 +5591,19 @@ function normalizeUser(user) {
     permissions: Array.isArray(user.permissions) ? user.permissions : []
   };
 }
+function normalizeEnvironmentData(environment) {
+  const buildPolicy = environment.buildPolicy || environment.tracking || (environment.tagId ? { mode: "tag", tagId: environment.tagId } : { mode: "pinned", versionId: environment.versionId || environment.buildId });
+  const environmentName = environment.environment || environment.envName || "prod";
+  return {
+    ...environment,
+    ontologyId: environment.ontologyId || environment.sandboxId,
+    versionId: environment.versionId || environment.buildId,
+    envName: environmentName,
+    environment: environmentName,
+    buildPolicy,
+    tracking: environment.tracking || buildPolicy
+  };
+}
 var Environment = class extends Session {
   envData;
   _apiKey;
@@ -5609,10 +5622,26 @@ var Environment = class extends Session {
   get sandboxId() {
     return this.envData.sandboxId;
   }
+  /** The ontology ID */
+  get ontologyId() {
+    return this.envData.ontologyId || this.envData.sandboxId;
+  }
   /** The subject ID */
   get subjectId() {
     return this.envData.subjectId;
   }
+  /** The named environment slot, such as dev or prod */
+  get envName() {
+    return this.envData.envName;
+  }
+  /** The named environment slot, such as dev or prod */
+  get environment() {
+    return this.envData.environment || this.envData.envName;
+  }
+  /** The resolved ontology version backing this environment */
+  get versionId() {
+    return this.envData.versionId || this.envData.buildId;
+  }
   /** Internal Granular user identifier for this environment */
   get granularId() {
     return this.envData.subjectId;
@@ -5696,7 +5725,8 @@ var Environment = class extends Session {
               "Authorization": `Bearer ${this._apiKey}`
             },
             body: JSON.stringify({
-              reason: "sdk_disconnect_http_fallback"
+              reason: "sdk_disconnect_http_fallback",
+              sessionId: this.client.currentSessionId
             })
           }
         );
@@ -6480,7 +6510,7 @@ var Environment = class extends Session {
     return super.unpublishAllEffects();
   }
 };
-var Granular = class {
+var Granular = class _Granular {
   apiKey;
   apiUrl;
   httpUrl;
@@ -6584,7 +6614,7 @@ var Granular = class {
     throw new Error("connect() requires either userId, granularId, or a user object returned by recordUser().");
   }
   /**
-   * Connect to a sandbox and establish a real-time environment session.
+   * Connect to an ontology environment and establish a real-time session.
    * 
    * Effects are registered at the sandbox level via `granular.registerEffect()`
    * or `granular.registerEffects()`. Sessions pick up live availability from
@@ -6596,7 +6626,8 @@ var Granular = class {
    * @example
    * ```typescript
    * const environment = await granular.connect({
-   *   sandbox: 'my-sandbox',
+   *   ontology: 'my-ontology',
+   *   environment: 'dev',
    *   userId: 'user_123',
    *   permissions: ['agent'],
    * });
@@ -6616,17 +6647,28 @@ var Granular = class {
    * 
    * console.log(await job.result); // 'Hello!'
    * ```
-   */
+  */
   async connect(options) {
     const clientId = options.clientId || `client_${Date.now()}`;
+    const ontology = options.ontology;
+    if (!ontology) {
+      throw new Error("connect() requires `ontology`.");
+    }
+    const environmentName = options.environment;
+    if (!environmentName) {
+      throw new Error("connect() requires `environment`.");
+    }
+    const tagName = options.tagName?.trim() || void 0;
     const user = await this.resolveConnectUser(options);
-    const sandbox = await this.findOrCreateSandbox(options.sandbox);
+    const sandbox = await this.findOrCreateSandbox(ontology);
     for (const profileName of user.permissions) {
       const profileId = await this.ensurePermissionProfile(sandbox.sandboxId, profileName);
       await this.ensureAssignment(user.granularId, sandbox.sandboxId, profileId);
     }
     const envData = await this.environments.create(sandbox.sandboxId, {
       subjectId: user.granularId,
+      environment: environmentName,
+      tagName,
       permissionProfileId: null
     });
     await this.activateEnvironment(envData.environmentId);
@@ -6638,6 +6680,120 @@ var Granular = class {
         initialHeap: options.initialHeap
       })
     });
+    return this.bindWebSocketEnvironment(envData, clientId, session);
+  }
+  /**
+   * List active (open) sessions for an environment — each session is one agent conversation thread.
+   */
+  async listOpenSessions(filters) {
+    return this.listSessionsForEnvironment(filters.environmentId, "active");
+  }
+  /**
+   * List closed sessions for an environment (conversations that have disconnected).
+   */
+  async listClosedSessions(filters) {
+    return this.listSessionsForEnvironment(filters.environmentId, "closed");
+  }
+  async listSessionsForEnvironment(environmentId, status) {
+    const query = new URLSearchParams({ environmentId, status });
+    const res = await this.request(
+      `/control/sessions?${query.toString()}`
+    );
+    const items = Array.isArray(res.items) ? res.items : [];
+    return items.map((row) => this.normalizeConversationSession(row));
+  }
+  normalizeConversationSession(row) {
+    const sessionId = String(row.sessionId ?? row.session_id ?? "");
+    const environmentId = String(row.environmentId ?? row.environment_id ?? "");
+    return {
+      sessionId,
+      tenantId: row.tenantId != null ? String(row.tenantId) : void 0,
+      environmentId,
+      versionId: row.versionId != null ? String(row.versionId) : null,
+      docId: String(row.docId ?? row.doc_id ?? ""),
+      status: row.status || "active",
+      createdAt: _Granular.coerceIsoDate(row.createdAt ?? row.created_at),
+      lastSeenAt: _Granular.coerceIsoDate(row.lastSeenAt ?? row.last_seen_at),
+      summary: row.summary != null ? String(row.summary) : null,
+      summaryUpdatedAt: row.summaryUpdatedAt != null || row.summary_updated_at != null ? _Granular.coerceIsoDate(row.summaryUpdatedAt ?? row.summary_updated_at) : null,
+      subjectId: row.subjectId != null ? String(row.subjectId) : null,
+      jobCount: typeof row.jobCount === "number" ? row.jobCount : void 0,
+      toolCallCount: typeof row.toolCallCount === "number" ? row.toolCallCount : void 0
+    };
+  }
+  static coerceIsoDate(value) {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof value === "number") {
+      return new Date(value).toISOString();
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    return (/* @__PURE__ */ new Date(0)).toISOString();
+  }
+  /**
+   * Create a new session (conversation) for an existing environment and connect to it.
+   * The runtime graph is shared across all sessions for the same environment.
+   */
+  async createSession(options) {
+    const clientId = options.clientId || `client_${Date.now()}`;
+    await this.activateEnvironment(options.environmentId);
+    const envData = await this.environments.get(options.environmentId);
+    const session = await this.request("/ws/sessions", {
+      method: "POST",
+      body: JSON.stringify({
+        environmentId: options.environmentId,
+        clientId,
+        initialHeap: options.initialHeap
+      })
+    });
+    return this.bindWebSocketEnvironment(envData, clientId, session);
+  }
+  /**
+   * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
+   */
+  async connectSession(options) {
+    const clientId = options.clientId || `client_${Date.now()}`;
+    const minted = await this.request(`/ws/sessions/${encodeURIComponent(options.sessionId)}/token`, {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+    const envData = await this.environments.get(minted.environmentId);
+    return this.bindWebSocketEnvironment(envData, clientId, minted);
+  }
+  /**
+   * Mark a session closed in the control plane. If `environment` is the connected handle for that
+   * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
+   */
+  async closeSession(sessionId, environment) {
+    if (environment && environment.sessionId === sessionId) {
+      await environment.disconnect();
+      return;
+    }
+    await this.request(`/control/sessions/${encodeURIComponent(sessionId)}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        status: "closed",
+        lastSeenAt: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    });
+  }
+  /**
+   * Re-open a closed session in the index and connect to its existing runtime document.
+   */
+  async reopenSession(sessionId, options) {
+    await this.request(`/control/sessions/${encodeURIComponent(sessionId)}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        status: "active",
+        lastSeenAt: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    });
+    return this.connectSession({ sessionId, clientId: options?.clientId });
+  }
+  async bindWebSocketEnvironment(envData, clientId, session) {
     const client = new WSClient({
       url: session.wsUrl,
       sessionId: session.sessionId,
@@ -7061,16 +7217,22 @@ var Granular = class {
         const result = await this.request(
           `/control/sandboxes/${sandboxId}/environments`
         );
-        return result.items;
+        return result.items.map(normalizeEnvironmentData);
       },
       get: async (environmentId) => {
-        return this.request(`/control/environments/${environmentId}`);
+        return normalizeEnvironmentData(
+          await this.request(`/control/environments/${environmentId}`)
+        );
       },
       create: async (sandboxId, data) => {
-        return this.request(`/control/sandboxes/${sandboxId}/environments`, {
+        const environmentName = data.environment || data.envName;
+        return normalizeEnvironmentData(await this.request(`/control/sandboxes/${sandboxId}/environments`, {
           method: "POST",
-          body: JSON.stringify(data)
-        });
+          body: JSON.stringify({
+            ...data,
+            envName: environmentName
+          })
+        }));
       },
       delete: async (environmentId) => {
         return this.request(`/control/environments/${environmentId}`, {