@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/README.md +14 -12
- package/dist/cli/index.js +362 -75
- package/dist/index.d.mts +156 -12
- package/dist/index.d.ts +156 -12
- package/dist/index.js +173 -11
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +173 -11
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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
|
|
89
|
+
* Options for connecting to an ontology environment
|
|
90
90
|
*/
|
|
91
91
|
interface ConnectOptions {
|
|
92
|
-
/** The
|
|
93
|
-
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
-
*
|
|
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
|
|
89
|
+
* Options for connecting to an ontology environment
|
|
90
90
|
*/
|
|
91
91
|
interface ConnectOptions {
|
|
92
|
-
/** The
|
|
93
|
-
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
-
*
|
|
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 };
|