@granular-software/sdk 0.4.14 → 0.4.15

package/dist/index.d.mts

@@ -122,6 +122,24 @@ interface ConnectOptions {
         id: string;
     }>;
 }
+/**
+ * Control-plane session row: one real-time conversation thread with the agent for an environment.
+ */
+interface ConversationSessionInfo {
+    sessionId: string;
+    tenantId?: string;
+    environmentId: string;
+    versionId?: string | null;
+    docId: string;
+    status: 'active' | 'closed' | 'expired';
+    createdAt: string;
+    lastSeenAt: string;
+    summary?: string | null;
+    summaryUpdatedAt?: string | null;
+    subjectId?: string | null;
+    jobCount?: number;
+    toolCallCount?: number;
+}
 /**
  * A sandbox container
  */
@@ -1742,6 +1760,49 @@ declare class Granular {
      * ```
     */
     connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * List active (open) sessions for an environment — each session is one agent conversation thread.
+     */
+    listOpenSessions(filters: {
+        environmentId: string;
+    }): Promise<ConversationSessionInfo[]>;
+    /**
+     * List closed sessions for an environment (conversations that have disconnected).
+     */
+    listClosedSessions(filters: {
+        environmentId: string;
+    }): Promise<ConversationSessionInfo[]>;
+    private listSessionsForEnvironment;
+    private normalizeConversationSession;
+    private static coerceIsoDate;
+    /**
+     * 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.
+     */
+    createSession(options: {
+        environmentId: string;
+        clientId?: string;
+        initialHeap?: ConnectOptions['initialHeap'];
+    }): Promise<Environment>;
+    /**
+     * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
+     */
+    connectSession(options: {
+        sessionId: string;
+        clientId?: string;
+    }): Promise<Environment>;
+    /**
+     * 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.
+     */
+    closeSession(sessionId: string, environment?: Environment | null): Promise<void>;
+    /**
+     * Re-open a closed session in the index and connect to its existing runtime document.
+     */
+    reopenSession(sessionId: string, options?: {
+        clientId?: string;
+    }): Promise<Environment>;
+    private bindWebSocketEnvironment;
     private activateEnvironment;
     private getSandboxEffectMap;
     private serializeEffect;
@@ -1859,4 +1920,4 @@ type EffectRuntimeRequest = {
 declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
 declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type ConversationSessionInfo, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };

package/dist/index.d.ts

@@ -122,6 +122,24 @@ interface ConnectOptions {
         id: string;
     }>;
 }
+/**
+ * Control-plane session row: one real-time conversation thread with the agent for an environment.
+ */
+interface ConversationSessionInfo {
+    sessionId: string;
+    tenantId?: string;
+    environmentId: string;
+    versionId?: string | null;
+    docId: string;
+    status: 'active' | 'closed' | 'expired';
+    createdAt: string;
+    lastSeenAt: string;
+    summary?: string | null;
+    summaryUpdatedAt?: string | null;
+    subjectId?: string | null;
+    jobCount?: number;
+    toolCallCount?: number;
+}
 /**
  * A sandbox container
  */
@@ -1742,6 +1760,49 @@ declare class Granular {
      * ```
     */
     connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * List active (open) sessions for an environment — each session is one agent conversation thread.
+     */
+    listOpenSessions(filters: {
+        environmentId: string;
+    }): Promise<ConversationSessionInfo[]>;
+    /**
+     * List closed sessions for an environment (conversations that have disconnected).
+     */
+    listClosedSessions(filters: {
+        environmentId: string;
+    }): Promise<ConversationSessionInfo[]>;
+    private listSessionsForEnvironment;
+    private normalizeConversationSession;
+    private static coerceIsoDate;
+    /**
+     * 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.
+     */
+    createSession(options: {
+        environmentId: string;
+        clientId?: string;
+        initialHeap?: ConnectOptions['initialHeap'];
+    }): Promise<Environment>;
+    /**
+     * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
+     */
+    connectSession(options: {
+        sessionId: string;
+        clientId?: string;
+    }): Promise<Environment>;
+    /**
+     * 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.
+     */
+    closeSession(sessionId: string, environment?: Environment | null): Promise<void>;
+    /**
+     * Re-open a closed session in the index and connect to its existing runtime document.
+     */
+    reopenSession(sessionId: string, options?: {
+        clientId?: string;
+    }): Promise<Environment>;
+    private bindWebSocketEnvironment;
     private activateEnvironment;
     private getSandboxEffectMap;
     private serializeEffect;
@@ -1859,4 +1920,4 @@ type EffectRuntimeRequest = {
 declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
 declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type ConversationSessionInfo, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };

package/dist/index.js

@@ -5747,7 +5747,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
             })
           }
         );
@@ -6531,7 +6532,7 @@ var Environment = class extends Session {
     return super.unpublishAllEffects();
   }
 };
-var Granular = class {
+var Granular = class _Granular {
   apiKey;
   apiUrl;
   httpUrl;
@@ -6701,6 +6702,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,