@granular-software/sdk 0.4.13 → 0.4.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -86,11 +86,15 @@ interface Subject {
86
86
  updatedAt: number;
87
87
  }
88
88
  /**
89
- * Options for connecting to a sandbox
89
+ * Options for connecting to an ontology environment
90
90
  */
91
91
  interface ConnectOptions {
92
- /** The sandbox name or ID to connect to */
93
- sandbox: string;
92
+ /** The ontology name or ID to connect to */
93
+ ontology: string;
94
+ /** Named environment slot such as `dev` or `prod` */
95
+ environment: string;
96
+ /** Advanced override for the version tag/channel to follow. In the common case, omit this. */
97
+ tagName?: string;
94
98
  /**
95
99
  * External user identifier from your app. This is the primary input for
96
100
  * connecting to a sandbox and the only required user field in the common case.
@@ -118,6 +122,24 @@ interface ConnectOptions {
118
122
  id: string;
119
123
  }>;
120
124
  }
125
+ /**
126
+ * Control-plane session row: one real-time conversation thread with the agent for an environment.
127
+ */
128
+ interface ConversationSessionInfo {
129
+ sessionId: string;
130
+ tenantId?: string;
131
+ environmentId: string;
132
+ versionId?: string | null;
133
+ docId: string;
134
+ status: 'active' | 'closed' | 'expired';
135
+ createdAt: string;
136
+ lastSeenAt: string;
137
+ summary?: string | null;
138
+ summaryUpdatedAt?: string | null;
139
+ subjectId?: string | null;
140
+ jobCount?: number;
141
+ toolCallCount?: number;
142
+ }
121
143
  /**
122
144
  * A sandbox container
123
145
  */
@@ -211,11 +233,30 @@ interface AssignmentListResponse {
211
233
  items: Assignment[];
212
234
  }
213
235
  /**
214
- * Build policy for environments
236
+ * Version tracking policy for environments.
237
+ *
238
+ * Environments either follow a version tag such as `dev` or `prod`, or they
239
+ * pin themselves to one immutable ontology version.
215
240
  */
216
241
  interface BuildPolicy {
217
- mode: 'current' | 'pinned';
242
+ mode: 'tag' | 'current' | 'pinned';
218
243
  buildId?: string;
244
+ versionId?: string;
245
+ tagId?: string;
246
+ tagName?: string;
247
+ }
248
+ type VersionTracking = BuildPolicy;
249
+ interface VersionTag {
250
+ tagId: string;
251
+ sandboxId: string;
252
+ name: string;
253
+ kind: 'channel' | 'release' | 'system';
254
+ targetBuildId?: string | null;
255
+ targetVersionId?: string | null;
256
+ description?: string | null;
257
+ protected?: boolean;
258
+ createdAt: number;
259
+ updatedAt: number;
219
260
  }
220
261
  /**
221
262
  * An environment links a user (subject) to a sandbox with specific permissions
@@ -223,10 +264,18 @@ interface BuildPolicy {
223
264
  interface EnvironmentData {
224
265
  environmentId: string;
225
266
  sandboxId: string;
267
+ ontologyId?: string;
226
268
  buildId: string;
269
+ versionId: string;
227
270
  subjectId: string;
271
+ envName: string;
272
+ environment?: string;
228
273
  permissionProfileId: string;
274
+ tagId?: string | null;
275
+ tag?: VersionTag | null;
276
+ tracking?: BuildPolicy;
229
277
  buildPolicy: BuildPolicy;
278
+ updateState?: 'up_to_date' | 'update_available' | 'upgrading' | 'failed';
230
279
  createdAt: number;
231
280
  updatedAt: number;
232
281
  }
@@ -236,9 +285,19 @@ interface EnvironmentData {
236
285
  interface CreateEnvironmentData {
237
286
  /** The user/subject ID to create the environment for */
238
287
  subjectId: string;
288
+ /** Named environment slot such as dev or prod */
289
+ environment?: string;
290
+ /** @deprecated Use `environment` instead. */
291
+ envName?: string;
239
292
  /** The permission profile to apply (optional - uses assignment if not specified) */
240
293
  permissionProfileId?: string | null;
241
- /** Build policy (defaults to current build) */
294
+ /** Follow a tag directly */
295
+ tagId?: string;
296
+ /** Follow a tag by name, typically dev or prod */
297
+ tagName?: string;
298
+ /** Pin the environment to a specific version */
299
+ versionId?: string;
300
+ /** Legacy/compat environment tracking input */
242
301
  buildPolicy?: BuildPolicy;
243
302
  }
244
303
  /**
@@ -267,25 +326,58 @@ interface ManifestListResponse {
267
326
  }
268
327
  type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
269
328
  /**
270
- * A build represents a compiled version of a manifest
329
+ * An immutable ontology version derived from a specific manifest revision.
330
+ *
331
+ * The same version may have multiple build runs over time when the manifest
332
+ * content is unchanged but the compilation process is re-executed.
271
333
  */
272
334
  interface Build {
273
335
  buildId: string;
274
336
  sandboxId: string;
275
337
  manifestId: string;
338
+ manifestDigest?: string;
339
+ versionNumber?: number;
276
340
  status: BuildStatus;
277
341
  graphBinaryId?: string | null;
278
342
  logsUri?: string | null;
343
+ latestBuildRunId?: string | null;
344
+ buildRunId?: string;
345
+ createdNewVersion?: boolean;
346
+ environmentCount?: number;
347
+ laggingEnvironmentCount?: number;
348
+ sessionCount?: number;
279
349
  createdAt: number;
280
350
  updatedAt: number;
281
351
  isCurrent?: boolean;
282
352
  }
353
+ type Version = Build;
283
354
  /**
284
- * List response for builds
355
+ * List response for versions
285
356
  */
286
357
  interface BuildListResponse {
287
358
  items: Build[];
288
359
  }
360
+ interface SemanticVersionDiffEntry {
361
+ operationId: string;
362
+ kind: 'create' | 'update' | 'relationship' | 'effect' | 'unknown';
363
+ changeType: 'added' | 'removed' | 'changed';
364
+ label: string;
365
+ additive: boolean;
366
+ breaking: boolean;
367
+ before?: Record<string, unknown>;
368
+ after?: Record<string, unknown>;
369
+ }
370
+ interface SemanticVersionDiff {
371
+ summary: {
372
+ added: number;
373
+ removed: number;
374
+ changed: number;
375
+ additive: number;
376
+ breaking: number;
377
+ onlyAdditiveChanges: boolean;
378
+ };
379
+ entries: SemanticVersionDiffEntry[];
380
+ }
289
381
  /**
290
382
  * Effect handler for static/global effects: receives (input, context)
291
383
  */
@@ -1253,8 +1345,16 @@ declare class Environment extends Session {
1253
1345
  get environmentId(): string;
1254
1346
  /** The sandbox ID */
1255
1347
  get sandboxId(): string;
1348
+ /** The ontology ID */
1349
+ get ontologyId(): string;
1256
1350
  /** The subject ID */
1257
1351
  get subjectId(): string;
1352
+ /** The named environment slot, such as dev or prod */
1353
+ get envName(): string;
1354
+ /** The named environment slot, such as dev or prod */
1355
+ get environment(): string;
1356
+ /** The resolved ontology version backing this environment */
1357
+ get versionId(): string;
1258
1358
  /** Internal Granular user identifier for this environment */
1259
1359
  get granularId(): string;
1260
1360
  /** The permission profile ID */
@@ -1625,7 +1725,7 @@ declare class Granular {
1625
1725
  recordUser(options: RecordUserOptions): Promise<User>;
1626
1726
  private resolveConnectUser;
1627
1727
  /**
1628
- * Connect to a sandbox and establish a real-time environment session.
1728
+ * Connect to an ontology environment and establish a real-time session.
1629
1729
  *
1630
1730
  * Effects are registered at the sandbox level via `granular.registerEffect()`
1631
1731
  * or `granular.registerEffects()`. Sessions pick up live availability from
@@ -1637,7 +1737,8 @@ declare class Granular {
1637
1737
  * @example
1638
1738
  * ```typescript
1639
1739
  * const environment = await granular.connect({
1640
- * sandbox: 'my-sandbox',
1740
+ * ontology: 'my-ontology',
1741
+ * environment: 'dev',
1641
1742
  * userId: 'user_123',
1642
1743
  * permissions: ['agent'],
1643
1744
  * });
@@ -1657,8 +1758,51 @@ declare class Granular {
1657
1758
  *
1658
1759
  * console.log(await job.result); // 'Hello!'
1659
1760
  * ```
1660
- */
1761
+ */
1661
1762
  connect(options: ConnectOptions): Promise<Environment>;
1763
+ /**
1764
+ * List active (open) sessions for an environment — each session is one agent conversation thread.
1765
+ */
1766
+ listOpenSessions(filters: {
1767
+ environmentId: string;
1768
+ }): Promise<ConversationSessionInfo[]>;
1769
+ /**
1770
+ * List closed sessions for an environment (conversations that have disconnected).
1771
+ */
1772
+ listClosedSessions(filters: {
1773
+ environmentId: string;
1774
+ }): Promise<ConversationSessionInfo[]>;
1775
+ private listSessionsForEnvironment;
1776
+ private normalizeConversationSession;
1777
+ private static coerceIsoDate;
1778
+ /**
1779
+ * Create a new session (conversation) for an existing environment and connect to it.
1780
+ * The runtime graph is shared across all sessions for the same environment.
1781
+ */
1782
+ createSession(options: {
1783
+ environmentId: string;
1784
+ clientId?: string;
1785
+ initialHeap?: ConnectOptions['initialHeap'];
1786
+ }): Promise<Environment>;
1787
+ /**
1788
+ * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
1789
+ */
1790
+ connectSession(options: {
1791
+ sessionId: string;
1792
+ clientId?: string;
1793
+ }): Promise<Environment>;
1794
+ /**
1795
+ * Mark a session closed in the control plane. If `environment` is the connected handle for that
1796
+ * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
1797
+ */
1798
+ closeSession(sessionId: string, environment?: Environment | null): Promise<void>;
1799
+ /**
1800
+ * Re-open a closed session in the index and connect to its existing runtime document.
1801
+ */
1802
+ reopenSession(sessionId: string, options?: {
1803
+ clientId?: string;
1804
+ }): Promise<Environment>;
1805
+ private bindWebSocketEnvironment;
1662
1806
  private activateEnvironment;
1663
1807
  private getSandboxEffectMap;
1664
1808
  private serializeEffect;
@@ -1776,4 +1920,4 @@ type EffectRuntimeRequest = {
1776
1920
  declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
1777
1921
  declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
1778
1922
 
1779
- 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, 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, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };
1923
+ 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 CHANGED
@@ -86,11 +86,15 @@ interface Subject {
86
86
  updatedAt: number;
87
87
  }
88
88
  /**
89
- * Options for connecting to a sandbox
89
+ * Options for connecting to an ontology environment
90
90
  */
91
91
  interface ConnectOptions {
92
- /** The sandbox name or ID to connect to */
93
- sandbox: string;
92
+ /** The ontology name or ID to connect to */
93
+ ontology: string;
94
+ /** Named environment slot such as `dev` or `prod` */
95
+ environment: string;
96
+ /** Advanced override for the version tag/channel to follow. In the common case, omit this. */
97
+ tagName?: string;
94
98
  /**
95
99
  * External user identifier from your app. This is the primary input for
96
100
  * connecting to a sandbox and the only required user field in the common case.
@@ -118,6 +122,24 @@ interface ConnectOptions {
118
122
  id: string;
119
123
  }>;
120
124
  }
125
+ /**
126
+ * Control-plane session row: one real-time conversation thread with the agent for an environment.
127
+ */
128
+ interface ConversationSessionInfo {
129
+ sessionId: string;
130
+ tenantId?: string;
131
+ environmentId: string;
132
+ versionId?: string | null;
133
+ docId: string;
134
+ status: 'active' | 'closed' | 'expired';
135
+ createdAt: string;
136
+ lastSeenAt: string;
137
+ summary?: string | null;
138
+ summaryUpdatedAt?: string | null;
139
+ subjectId?: string | null;
140
+ jobCount?: number;
141
+ toolCallCount?: number;
142
+ }
121
143
  /**
122
144
  * A sandbox container
123
145
  */
@@ -211,11 +233,30 @@ interface AssignmentListResponse {
211
233
  items: Assignment[];
212
234
  }
213
235
  /**
214
- * Build policy for environments
236
+ * Version tracking policy for environments.
237
+ *
238
+ * Environments either follow a version tag such as `dev` or `prod`, or they
239
+ * pin themselves to one immutable ontology version.
215
240
  */
216
241
  interface BuildPolicy {
217
- mode: 'current' | 'pinned';
242
+ mode: 'tag' | 'current' | 'pinned';
218
243
  buildId?: string;
244
+ versionId?: string;
245
+ tagId?: string;
246
+ tagName?: string;
247
+ }
248
+ type VersionTracking = BuildPolicy;
249
+ interface VersionTag {
250
+ tagId: string;
251
+ sandboxId: string;
252
+ name: string;
253
+ kind: 'channel' | 'release' | 'system';
254
+ targetBuildId?: string | null;
255
+ targetVersionId?: string | null;
256
+ description?: string | null;
257
+ protected?: boolean;
258
+ createdAt: number;
259
+ updatedAt: number;
219
260
  }
220
261
  /**
221
262
  * An environment links a user (subject) to a sandbox with specific permissions
@@ -223,10 +264,18 @@ interface BuildPolicy {
223
264
  interface EnvironmentData {
224
265
  environmentId: string;
225
266
  sandboxId: string;
267
+ ontologyId?: string;
226
268
  buildId: string;
269
+ versionId: string;
227
270
  subjectId: string;
271
+ envName: string;
272
+ environment?: string;
228
273
  permissionProfileId: string;
274
+ tagId?: string | null;
275
+ tag?: VersionTag | null;
276
+ tracking?: BuildPolicy;
229
277
  buildPolicy: BuildPolicy;
278
+ updateState?: 'up_to_date' | 'update_available' | 'upgrading' | 'failed';
230
279
  createdAt: number;
231
280
  updatedAt: number;
232
281
  }
@@ -236,9 +285,19 @@ interface EnvironmentData {
236
285
  interface CreateEnvironmentData {
237
286
  /** The user/subject ID to create the environment for */
238
287
  subjectId: string;
288
+ /** Named environment slot such as dev or prod */
289
+ environment?: string;
290
+ /** @deprecated Use `environment` instead. */
291
+ envName?: string;
239
292
  /** The permission profile to apply (optional - uses assignment if not specified) */
240
293
  permissionProfileId?: string | null;
241
- /** Build policy (defaults to current build) */
294
+ /** Follow a tag directly */
295
+ tagId?: string;
296
+ /** Follow a tag by name, typically dev or prod */
297
+ tagName?: string;
298
+ /** Pin the environment to a specific version */
299
+ versionId?: string;
300
+ /** Legacy/compat environment tracking input */
242
301
  buildPolicy?: BuildPolicy;
243
302
  }
244
303
  /**
@@ -267,25 +326,58 @@ interface ManifestListResponse {
267
326
  }
268
327
  type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
269
328
  /**
270
- * A build represents a compiled version of a manifest
329
+ * An immutable ontology version derived from a specific manifest revision.
330
+ *
331
+ * The same version may have multiple build runs over time when the manifest
332
+ * content is unchanged but the compilation process is re-executed.
271
333
  */
272
334
  interface Build {
273
335
  buildId: string;
274
336
  sandboxId: string;
275
337
  manifestId: string;
338
+ manifestDigest?: string;
339
+ versionNumber?: number;
276
340
  status: BuildStatus;
277
341
  graphBinaryId?: string | null;
278
342
  logsUri?: string | null;
343
+ latestBuildRunId?: string | null;
344
+ buildRunId?: string;
345
+ createdNewVersion?: boolean;
346
+ environmentCount?: number;
347
+ laggingEnvironmentCount?: number;
348
+ sessionCount?: number;
279
349
  createdAt: number;
280
350
  updatedAt: number;
281
351
  isCurrent?: boolean;
282
352
  }
353
+ type Version = Build;
283
354
  /**
284
- * List response for builds
355
+ * List response for versions
285
356
  */
286
357
  interface BuildListResponse {
287
358
  items: Build[];
288
359
  }
360
+ interface SemanticVersionDiffEntry {
361
+ operationId: string;
362
+ kind: 'create' | 'update' | 'relationship' | 'effect' | 'unknown';
363
+ changeType: 'added' | 'removed' | 'changed';
364
+ label: string;
365
+ additive: boolean;
366
+ breaking: boolean;
367
+ before?: Record<string, unknown>;
368
+ after?: Record<string, unknown>;
369
+ }
370
+ interface SemanticVersionDiff {
371
+ summary: {
372
+ added: number;
373
+ removed: number;
374
+ changed: number;
375
+ additive: number;
376
+ breaking: number;
377
+ onlyAdditiveChanges: boolean;
378
+ };
379
+ entries: SemanticVersionDiffEntry[];
380
+ }
289
381
  /**
290
382
  * Effect handler for static/global effects: receives (input, context)
291
383
  */
@@ -1253,8 +1345,16 @@ declare class Environment extends Session {
1253
1345
  get environmentId(): string;
1254
1346
  /** The sandbox ID */
1255
1347
  get sandboxId(): string;
1348
+ /** The ontology ID */
1349
+ get ontologyId(): string;
1256
1350
  /** The subject ID */
1257
1351
  get subjectId(): string;
1352
+ /** The named environment slot, such as dev or prod */
1353
+ get envName(): string;
1354
+ /** The named environment slot, such as dev or prod */
1355
+ get environment(): string;
1356
+ /** The resolved ontology version backing this environment */
1357
+ get versionId(): string;
1258
1358
  /** Internal Granular user identifier for this environment */
1259
1359
  get granularId(): string;
1260
1360
  /** The permission profile ID */
@@ -1625,7 +1725,7 @@ declare class Granular {
1625
1725
  recordUser(options: RecordUserOptions): Promise<User>;
1626
1726
  private resolveConnectUser;
1627
1727
  /**
1628
- * Connect to a sandbox and establish a real-time environment session.
1728
+ * Connect to an ontology environment and establish a real-time session.
1629
1729
  *
1630
1730
  * Effects are registered at the sandbox level via `granular.registerEffect()`
1631
1731
  * or `granular.registerEffects()`. Sessions pick up live availability from
@@ -1637,7 +1737,8 @@ declare class Granular {
1637
1737
  * @example
1638
1738
  * ```typescript
1639
1739
  * const environment = await granular.connect({
1640
- * sandbox: 'my-sandbox',
1740
+ * ontology: 'my-ontology',
1741
+ * environment: 'dev',
1641
1742
  * userId: 'user_123',
1642
1743
  * permissions: ['agent'],
1643
1744
  * });
@@ -1657,8 +1758,51 @@ declare class Granular {
1657
1758
  *
1658
1759
  * console.log(await job.result); // 'Hello!'
1659
1760
  * ```
1660
- */
1761
+ */
1661
1762
  connect(options: ConnectOptions): Promise<Environment>;
1763
+ /**
1764
+ * List active (open) sessions for an environment — each session is one agent conversation thread.
1765
+ */
1766
+ listOpenSessions(filters: {
1767
+ environmentId: string;
1768
+ }): Promise<ConversationSessionInfo[]>;
1769
+ /**
1770
+ * List closed sessions for an environment (conversations that have disconnected).
1771
+ */
1772
+ listClosedSessions(filters: {
1773
+ environmentId: string;
1774
+ }): Promise<ConversationSessionInfo[]>;
1775
+ private listSessionsForEnvironment;
1776
+ private normalizeConversationSession;
1777
+ private static coerceIsoDate;
1778
+ /**
1779
+ * Create a new session (conversation) for an existing environment and connect to it.
1780
+ * The runtime graph is shared across all sessions for the same environment.
1781
+ */
1782
+ createSession(options: {
1783
+ environmentId: string;
1784
+ clientId?: string;
1785
+ initialHeap?: ConnectOptions['initialHeap'];
1786
+ }): Promise<Environment>;
1787
+ /**
1788
+ * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
1789
+ */
1790
+ connectSession(options: {
1791
+ sessionId: string;
1792
+ clientId?: string;
1793
+ }): Promise<Environment>;
1794
+ /**
1795
+ * Mark a session closed in the control plane. If `environment` is the connected handle for that
1796
+ * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
1797
+ */
1798
+ closeSession(sessionId: string, environment?: Environment | null): Promise<void>;
1799
+ /**
1800
+ * Re-open a closed session in the index and connect to its existing runtime document.
1801
+ */
1802
+ reopenSession(sessionId: string, options?: {
1803
+ clientId?: string;
1804
+ }): Promise<Environment>;
1805
+ private bindWebSocketEnvironment;
1662
1806
  private activateEnvironment;
1663
1807
  private getSandboxEffectMap;
1664
1808
  private serializeEffect;
@@ -1776,4 +1920,4 @@ type EffectRuntimeRequest = {
1776
1920
  declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
1777
1921
  declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
1778
1922
 
1779
- 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, 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, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };
1923
+ 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 };