@granular-software/sdk 0.4.49 → 0.4.51

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.
@@ -50,15 +50,6 @@ interface MatchedPolicy {
50
50
  reason?: string;
51
51
  summary: string;
52
52
  }
53
- interface PolicyDecision {
54
- outcome: PolicyOutcome;
55
- matches: MatchedPolicy[];
56
- }
57
- interface PolicyEvaluationContext {
58
- input?: Record<string, unknown> | null;
59
- object?: Record<string, unknown> | null;
60
- stateMachines?: Record<string, string | null | undefined> | null;
61
- }
62
53
  interface PermissionProfileFile {
63
54
  schemaVersion?: number;
64
55
  name: string;
@@ -265,6 +256,13 @@ interface ConnectOptions extends OpenEnvironmentOptions {
265
256
  interface CreateSessionOptions {
266
257
  /** Optional stable client ID. Defaults to `client_${Date.now()}`. */
267
258
  clientId?: string;
259
+ /**
260
+ * Optional application-owned history scope for this conversation.
261
+ *
262
+ * Use the same value when listing sessions or reading the materialized user
263
+ * environment state so unrelated product surfaces never share history.
264
+ */
265
+ sessionScope?: string;
268
266
  /**
269
267
  * Optional session heap seed. Each item uses application record identity:
270
268
  * class name plus the record id from the customer's own system. Granular
@@ -294,6 +292,23 @@ interface ConversationSessionInfo {
294
292
  jobCount?: number;
295
293
  toolCallCount?: number;
296
294
  }
295
+ type ConversationSessionListStatus = ConversationSessionInfo["status"] | "all";
296
+ /**
297
+ * Bounded filters for indexed conversation history.
298
+ *
299
+ * At least one ownership filter (`environmentId`, `sandboxId`, or
300
+ * `subjectId`) is required by the SDK. Results are newest-first and default to
301
+ * 100 rows; use `offset` to request the next page.
302
+ */
303
+ interface ConversationSessionListOptions {
304
+ environmentId?: string;
305
+ sandboxId?: string;
306
+ subjectId?: string;
307
+ sessionScope?: string | null;
308
+ status?: ConversationSessionListStatus;
309
+ limit?: number;
310
+ offset?: number;
311
+ }
297
312
  type SpendLineItemType = "llm_tokens" | "granular_session_time" | string;
298
313
  type QuotaScopeType = "tenant" | "sandbox" | "permission_profile" | "subject";
299
314
  type QuotaPeriod = "hour" | "day" | "week" | "month";
@@ -902,6 +917,10 @@ interface Job {
902
917
  }
903
918
  interface Prompt {
904
919
  id: string;
920
+ /** Job that owns this prompt, when it was opened by a running job. */
921
+ jobId?: string;
922
+ /** Harness turn that owns this prompt. */
923
+ turnId?: string;
905
924
  type: "confirm" | "choice" | "input";
906
925
  title: string;
907
926
  message: string;
@@ -920,14 +939,73 @@ interface ConversationMessageShowRefs {
920
939
  listNames?: string[];
921
940
  variableNames?: string[];
922
941
  fileIds?: string[];
942
+ sessionArtifactIds?: string[];
943
+ actionSuggestions?: ConversationActionSuggestion[];
944
+ tables?: ConversationTableProjection[];
945
+ }
946
+ type ConversationTableCell = string | number | boolean | null | {
947
+ kind: "relative_time" | "date";
948
+ value: string | number;
949
+ };
950
+ interface ConversationTableColumn {
951
+ id: string;
952
+ label: string;
923
953
  }
954
+ interface ConversationTableRowReference {
955
+ entryPath?: string;
956
+ className?: string;
957
+ id?: string;
958
+ label?: string;
959
+ }
960
+ interface ConversationTableRow {
961
+ id: string;
962
+ reference?: ConversationTableRowReference;
963
+ cells: ConversationTableCell[];
964
+ }
965
+ interface ConversationTableProjection {
966
+ id: string;
967
+ label?: string;
968
+ source?: string;
969
+ columns: ConversationTableColumn[];
970
+ rows: ConversationTableRow[];
971
+ }
972
+ interface ConversationActionSuggestion {
973
+ suggestionId?: string;
974
+ label: string;
975
+ description?: string | null;
976
+ artifact?: Record<string, unknown>;
977
+ target?: Record<string, unknown> | null;
978
+ metadata?: Record<string, unknown>;
979
+ }
980
+ /** A normalized action embedded in an ordered assistant message stream. */
981
+ interface ConversationMessageAction {
982
+ kind: "frontend" | "backend" | "system";
983
+ label: string;
984
+ status?: "done" | "queued" | "failed";
985
+ }
986
+ /**
987
+ * A durable assistant message segment in the order it reached the client.
988
+ *
989
+ * `content` and `actions` remain the canonical compatibility fields on the
990
+ * message. Parts only preserve their interleaving for capable clients.
991
+ */
992
+ type ConversationMessagePart = {
993
+ type: "text";
994
+ text: string;
995
+ } | {
996
+ type: "action";
997
+ action: ConversationMessageAction;
998
+ };
924
999
  interface ConversationMessageInput {
1000
+ /** Optional caller-owned id used to correlate optimistic and durable turns. */
1001
+ id?: string;
925
1002
  role: "user" | "assistant";
926
1003
  content?: string;
927
1004
  show?: ConversationMessageShowRefs;
928
1005
  reasoningLines?: string[];
929
1006
  reasoningDurationMs?: number;
930
1007
  actions?: Array<Record<string, unknown>>;
1008
+ parts?: ConversationMessagePart[];
931
1009
  target?: Record<string, unknown>;
932
1010
  jobId?: string;
933
1011
  promptId?: string;
@@ -948,6 +1026,7 @@ interface SessionConversationMessage {
948
1026
  reasoningLines?: string[];
949
1027
  reasoningDurationMs?: number;
950
1028
  actions?: Array<Record<string, unknown>>;
1029
+ parts?: ConversationMessagePart[];
951
1030
  target?: Record<string, unknown>;
952
1031
  jobId?: string;
953
1032
  promptId?: string;
@@ -995,6 +1074,265 @@ interface SessionFileRecord {
995
1074
  outputPath?: string;
996
1075
  metadata?: Record<string, unknown>;
997
1076
  }
1077
+ type SessionArtifactStatus = "draft" | "ready" | "needs_edit" | "blocked" | "running" | "awaiting_human" | "completed" | "partially_completed" | "failed" | "canceled" | "stale";
1078
+ type SessionArtifactKind = "effect" | "batch" | "state_path";
1079
+ /**
1080
+ * Declarative impact metadata consumed by deterministic clients before an
1081
+ * artifact can execute. Missing metadata must be treated conservatively.
1082
+ */
1083
+ interface SessionArtifactAutonomyPolicy {
1084
+ sideEffect?: "read" | "readonly" | "read_only" | "ui" | "write" | "delete" | "destructive" | "irreversible";
1085
+ scope?: "internal" | "bulk" | "external" | "financial" | "permission";
1086
+ risk?: "low" | "medium" | "high";
1087
+ targetCount?: number;
1088
+ reversible?: boolean;
1089
+ destructive?: boolean;
1090
+ external?: boolean;
1091
+ financial?: boolean;
1092
+ permissionChange?: boolean;
1093
+ reverse?: string | Record<string, unknown>;
1094
+ undo?: string | Record<string, unknown>;
1095
+ rollback?: string | Record<string, unknown>;
1096
+ [key: string]: unknown;
1097
+ }
1098
+ interface SessionArtifactRecord {
1099
+ artifactId: string;
1100
+ sessionId?: string | null;
1101
+ environmentId?: string | null;
1102
+ subjectId?: string | null;
1103
+ buildId?: string | null;
1104
+ buildVersionNumber?: number | null;
1105
+ createdByJobId?: string | null;
1106
+ kind: SessionArtifactKind;
1107
+ label: string;
1108
+ description?: string | null;
1109
+ status: SessionArtifactStatus;
1110
+ target?: {
1111
+ className: string;
1112
+ id: string;
1113
+ path?: string | null;
1114
+ label?: string | null;
1115
+ } | null;
1116
+ inputValues?: Record<string, unknown>;
1117
+ inputSchema?: {
1118
+ fields?: Array<Record<string, unknown>>;
1119
+ [key: string]: unknown;
1120
+ } | null;
1121
+ relationships?: Record<string, string | string[] | null>;
1122
+ validation?: Record<string, unknown> | null;
1123
+ policy?: SessionArtifactAutonomyPolicy | null;
1124
+ metadata?: Record<string, unknown> & {
1125
+ autonomy?: SessionArtifactAutonomyPolicy;
1126
+ };
1127
+ parentArtifactId?: string | null;
1128
+ subArtifactIds?: string[];
1129
+ createdAt: number;
1130
+ updatedAt: number;
1131
+ executedAt?: number | null;
1132
+ completedAt?: number | null;
1133
+ canceledAt?: number | null;
1134
+ }
1135
+ interface SessionArtifactListOptions extends SessionCollectionListOptions {
1136
+ jobId?: string | null;
1137
+ latestJob?: boolean | null;
1138
+ kind?: SessionArtifactKind | SessionArtifactKind[] | null;
1139
+ status?: SessionArtifactStatus | SessionArtifactStatus[] | "all" | null;
1140
+ target?: {
1141
+ className?: string | null;
1142
+ id?: string | null;
1143
+ } | null;
1144
+ }
1145
+ interface SessionArtifactValidationResult {
1146
+ ok: boolean;
1147
+ status: SessionArtifactStatus;
1148
+ artifact: SessionArtifactRecord;
1149
+ errors: Array<Record<string, unknown>>;
1150
+ }
1151
+ interface SessionArtifactExecutionResult {
1152
+ ok: boolean;
1153
+ status: SessionArtifactStatus;
1154
+ artifact: SessionArtifactRecord;
1155
+ result?: Record<string, unknown> | null;
1156
+ error?: string | null;
1157
+ }
1158
+ interface SessionArtifactExecutionOptions {
1159
+ idempotencyKey: string;
1160
+ }
1161
+ interface SessionArtifactApprovalOptions extends SessionArtifactExecutionOptions {
1162
+ approved: boolean;
1163
+ reason?: string | null;
1164
+ }
1165
+ type ArtifactApprovalTaskStatus = "awaiting" | "approved" | "denied" | "canceled" | "completed";
1166
+ interface ArtifactApprovalTask {
1167
+ approvalTaskId: string;
1168
+ tenantId: string;
1169
+ sandboxId: string | null;
1170
+ environmentId: string;
1171
+ sessionId: string;
1172
+ artifactId: string;
1173
+ status: ArtifactApprovalTaskStatus;
1174
+ requesterSubjectId: string | null;
1175
+ requiredSubjectId: string | null;
1176
+ requiredPermissionProfileId: string | null;
1177
+ requiredPermissionProfileName: string | null;
1178
+ actorSubjectId: string | null;
1179
+ actorPermissionProfileId: string | null;
1180
+ actorPermissionProfileName: string | null;
1181
+ label: string | null;
1182
+ reason: string | null;
1183
+ decisionReason: string | null;
1184
+ target: {
1185
+ className: string | null;
1186
+ id: string | null;
1187
+ path: string | null;
1188
+ label: string | null;
1189
+ };
1190
+ machineName: string;
1191
+ targetState: string;
1192
+ pendingTransition: string;
1193
+ metadata: Record<string, unknown>;
1194
+ createdAt: number;
1195
+ updatedAt: number;
1196
+ decidedAt: number | null;
1197
+ }
1198
+ interface ArtifactApprovalTaskListOptions extends SessionCollectionListOptions {
1199
+ status?: ArtifactApprovalTaskStatus | ArtifactApprovalTaskStatus[] | null;
1200
+ sessionId?: string | null;
1201
+ artifactId?: string | null;
1202
+ subjectId?: string | null;
1203
+ permissionProfileId?: string | null;
1204
+ permissionProfileName?: string | null;
1205
+ includeUnassigned?: boolean | null;
1206
+ }
1207
+ interface ArtifactApprovalDecisionInput {
1208
+ approved: boolean;
1209
+ reason?: string | null;
1210
+ idempotencyKey?: string | null;
1211
+ }
1212
+ interface ArtifactApprovalDecisionResult {
1213
+ item: ArtifactApprovalTask;
1214
+ runtime?: SessionArtifactExecutionResult;
1215
+ alreadyDecided?: boolean;
1216
+ }
1217
+ type ManualActionStatus = "completed" | "failed" | "canceled" | "started";
1218
+ type ManualActionSource = "app_sdk" | "dock" | "customer_backend" | "manual_import";
1219
+ interface ManualActionTarget {
1220
+ className?: string | null;
1221
+ id?: string | null;
1222
+ path?: string | null;
1223
+ label?: string | null;
1224
+ }
1225
+ interface ManualActionRelatedRecord extends ManualActionTarget {
1226
+ role?: string | null;
1227
+ }
1228
+ interface RecordManualActionInput {
1229
+ /**
1230
+ * Stable idempotency key for this occurrence. Reusing it makes recording safe
1231
+ * across app retries and page reloads.
1232
+ */
1233
+ idempotencyKey?: string;
1234
+ /** Backwards-compatible explicit occurrence id alias. */
1235
+ actionOccurrenceId?: string;
1236
+ actionKey: string;
1237
+ label?: string | null;
1238
+ status?: ManualActionStatus | null;
1239
+ target?: ManualActionTarget | null;
1240
+ related?: ManualActionRelatedRecord[];
1241
+ input?: Record<string, unknown>;
1242
+ result?: Record<string, unknown> | null;
1243
+ metadata?: Record<string, unknown>;
1244
+ source?: ManualActionSource;
1245
+ actorId?: string | null;
1246
+ occurredAt?: number | string | Date | null;
1247
+ sessionId?: string | null;
1248
+ /**
1249
+ * Optional graph projection for customers who model manual actions as
1250
+ * first-class graph records. Durable audit recording succeeds even if this
1251
+ * best-effort projection fails.
1252
+ */
1253
+ graphProjection?: boolean | {
1254
+ className?: string;
1255
+ id?: string;
1256
+ label?: string;
1257
+ fields?: Record<string, string | number | boolean | null>;
1258
+ relationships?: Record<string, string | string[]>;
1259
+ };
1260
+ }
1261
+ interface ManualActionOccurrence {
1262
+ actionOccurrenceId: string;
1263
+ tenantId: string;
1264
+ sandboxId: string | null;
1265
+ environmentId: string;
1266
+ sessionId: string | null;
1267
+ subjectId: string | null;
1268
+ actionKey: string;
1269
+ label: string | null;
1270
+ status: ManualActionStatus;
1271
+ target: {
1272
+ className: string | null;
1273
+ id: string | null;
1274
+ path: string | null;
1275
+ label: string | null;
1276
+ };
1277
+ related: ManualActionRelatedRecord[];
1278
+ input: Record<string, unknown>;
1279
+ result: Record<string, unknown> | null;
1280
+ metadata: Record<string, unknown>;
1281
+ source: ManualActionSource;
1282
+ actorId: string | null;
1283
+ occurredAt: number;
1284
+ createdAt: number;
1285
+ updatedAt: number;
1286
+ }
1287
+ interface ManualActionRecordResult {
1288
+ item: ManualActionOccurrence;
1289
+ created: boolean;
1290
+ graphProjection?: {
1291
+ attempted: boolean;
1292
+ ok: boolean;
1293
+ path?: string | null;
1294
+ id?: string | null;
1295
+ className?: string | null;
1296
+ error?: string | null;
1297
+ };
1298
+ }
1299
+ interface ManualActionListOptions extends SessionCollectionListOptions {
1300
+ sessionId?: string | null;
1301
+ subjectId?: string | null;
1302
+ actionKey?: string | null;
1303
+ status?: ManualActionStatus | ManualActionStatus[] | null;
1304
+ source?: ManualActionSource | null;
1305
+ targetClassName?: string | null;
1306
+ targetId?: string | null;
1307
+ relatedClassName?: string | null;
1308
+ relatedId?: string | null;
1309
+ relatedRole?: string | null;
1310
+ since?: number | string | Date | null;
1311
+ until?: number | string | Date | null;
1312
+ }
1313
+ interface ManualActionSuggestion {
1314
+ actionKey: string;
1315
+ label: string | null;
1316
+ targetClassName: string | null;
1317
+ count: number;
1318
+ lastOccurredAt: number;
1319
+ subjectCount: number;
1320
+ successCount: number;
1321
+ failureCount: number;
1322
+ sources: string[];
1323
+ sampleTargetIds: string[];
1324
+ }
1325
+ interface ManualActionSuggestionOptions {
1326
+ subjectId?: string | null;
1327
+ actionKey?: string | null;
1328
+ targetClassName?: string | null;
1329
+ relatedClassName?: string | null;
1330
+ relatedId?: string | null;
1331
+ relatedRole?: string | null;
1332
+ since?: number | string | Date | null;
1333
+ minCount?: number | null;
1334
+ limit?: number | null;
1335
+ }
998
1336
  interface SessionFileUploadOptions {
999
1337
  filename?: string;
1000
1338
  contentType?: string;
@@ -1035,6 +1373,8 @@ interface SessionTranscriptEntry {
1035
1373
  jobResultPreview?: string;
1036
1374
  error?: string;
1037
1375
  show?: ConversationMessageShowRefs;
1376
+ actions?: ConversationMessageAction[];
1377
+ parts?: ConversationMessagePart[];
1038
1378
  historyContent?: string;
1039
1379
  source: "conversation" | "job_code" | "job_result" | "job_prompt" | "job_agent_message";
1040
1380
  }
@@ -1105,9 +1445,12 @@ interface SessionDocumentResult {
1105
1445
  interface SessionCollectionListOptions {
1106
1446
  limit?: number;
1107
1447
  cursor?: string | null;
1448
+ /** Return only the newest page, in chronological order. */
1449
+ latest?: boolean | null;
1108
1450
  }
1109
1451
  interface SessionJobListOptions extends SessionCollectionListOptions {
1110
1452
  status?: string | null;
1453
+ latest?: boolean | null;
1111
1454
  }
1112
1455
  interface SessionCollectionListResult<T = unknown> {
1113
1456
  items: T[];
@@ -1153,6 +1496,8 @@ interface UserEnvironmentState {
1153
1496
  tenantId?: string;
1154
1497
  sessionScope?: string | null;
1155
1498
  updatedAt: number;
1499
+ /** Monotonic materialized-index revision used for conditional refreshes. */
1500
+ revision?: number;
1156
1501
  stateSource?: "user_environment_snapshot" | "live_session_aggregate";
1157
1502
  stale?: boolean;
1158
1503
  snapshotUpdatedAt?: number | null;
@@ -1194,6 +1539,7 @@ interface WSClientOptions {
1194
1539
  url: string;
1195
1540
  sessionId: string;
1196
1541
  token: string;
1542
+ initialDocumentSnapshot?: Record<string, unknown> | Uint8Array | null;
1197
1543
  tokenProvider?: AccessTokenProvider;
1198
1544
  WebSocketCtor?: any;
1199
1545
  maxReconnectAttempts?: number;
@@ -1317,7 +1663,59 @@ interface RecordObjectOptions {
1317
1663
  * - For a "many" side: pass an array of target IDs
1318
1664
  */
1319
1665
  relationships?: Record<string, string | string[]>;
1666
+ /**
1667
+ * Optional product-owned state observations, keyed by state-machine name.
1668
+ *
1669
+ * A plain string is the observed state name. The object form carries audit
1670
+ * and causality metadata for richer workflow/state-machine integrations.
1671
+ */
1672
+ states?: Record<string, RecordObjectStateValue>;
1673
+ }
1674
+ type RecordObjectStateValue = string | {
1675
+ state: string;
1676
+ source?: "customer_backend" | "external_sync" | "granular_effect" | "manual";
1677
+ cause?: {
1678
+ kind: "backend_method" | "effect" | "event" | "manual" | "unknown";
1679
+ name?: string;
1680
+ id?: string;
1681
+ };
1682
+ actorId?: string;
1683
+ observedAt?: string | number;
1684
+ force?: boolean;
1685
+ metadata?: Record<string, unknown>;
1686
+ };
1687
+ interface EnvironmentStateTarget {
1688
+ className: string;
1689
+ id: string;
1690
+ label?: string;
1691
+ fields?: Record<string, string | number | boolean | null>;
1692
+ relationships?: Record<string, string | string[]>;
1320
1693
  }
1694
+ interface EnvironmentStateObservationInput {
1695
+ state?: string;
1696
+ observedState?: string;
1697
+ source?: "customer_backend" | "external_sync" | "granular_effect" | "manual";
1698
+ cause?: {
1699
+ kind: "backend_method" | "effect" | "event" | "manual" | "unknown";
1700
+ name?: string;
1701
+ id?: string;
1702
+ };
1703
+ actorId?: string;
1704
+ observedAt?: string | number;
1705
+ force?: boolean;
1706
+ metadata?: Record<string, unknown>;
1707
+ }
1708
+ interface EnvironmentStateUpdateInput extends EnvironmentStateTarget, Omit<EnvironmentStateObservationInput, "observedState"> {
1709
+ machine: string;
1710
+ state: string;
1711
+ }
1712
+ type EnvironmentStateMachineProxy = {
1713
+ to(state: string, input?: Omit<EnvironmentStateObservationInput, "state" | "observedState">): Promise<RecordObjectResult>;
1714
+ [stateMethod: string]: any;
1715
+ };
1716
+ type EnvironmentStateProxy = {
1717
+ [machineName: string]: EnvironmentStateMachineProxy;
1718
+ };
1321
1719
  /**
1322
1720
  * Return value from `recordObject()`
1323
1721
  */
@@ -1503,15 +1901,87 @@ interface ManifestValidationRuleSpec {
1503
1901
  }
1504
1902
  interface ManifestStateMachineStateSpec {
1505
1903
  name: string;
1904
+ label?: string;
1905
+ description?: string;
1506
1906
  isFinal?: boolean;
1507
1907
  }
1908
+ type ManifestStateTransitionInputBinding = null | string | number | boolean | ManifestStateTransitionInputBinding[] | {
1909
+ [key: string]: ManifestStateTransitionInputBinding;
1910
+ } | {
1911
+ const: unknown;
1912
+ } | {
1913
+ from: "object";
1914
+ path: string;
1915
+ editable?: boolean;
1916
+ } | {
1917
+ from: "field";
1918
+ name: string;
1919
+ editable?: boolean;
1920
+ } | {
1921
+ from: "relationship";
1922
+ name: string;
1923
+ path?: string;
1924
+ many?: boolean;
1925
+ editable?: boolean;
1926
+ } | {
1927
+ from: "session";
1928
+ path: string;
1929
+ editable?: boolean;
1930
+ } | {
1931
+ from: "actor";
1932
+ path: string;
1933
+ editable?: boolean;
1934
+ };
1935
+ interface ManifestStateTransitionActionSpec {
1936
+ effect: string;
1937
+ input?: Record<string, ManifestStateTransitionInputBinding>;
1938
+ }
1939
+ interface ManifestStateTransitionAssigneeSpec {
1940
+ kind: string;
1941
+ from?: ManifestStateTransitionInputBinding;
1942
+ role?: string;
1943
+ label?: string;
1944
+ }
1945
+ interface ManifestStateTransitionRelatedStateRequirementSpec {
1946
+ relationship: string;
1947
+ machine: string;
1948
+ state: string;
1949
+ className?: string;
1950
+ label?: string;
1951
+ mode?: "every" | "some" | "any";
1952
+ }
1953
+ interface ManifestStateTransitionRequirementsSpec {
1954
+ fields?: string[];
1955
+ relationships?: string[];
1956
+ relatedStates?: ManifestStateTransitionRelatedStateRequirementSpec[];
1957
+ }
1958
+ interface ManifestStateTransitionPermissionSpec {
1959
+ profile?: string;
1960
+ profileId?: string;
1961
+ label?: string;
1962
+ reason?: string;
1963
+ }
1964
+ interface ManifestStateTransitionExpectedOutcomeSpec {
1965
+ machine?: string;
1966
+ state: string;
1967
+ summary?: string;
1968
+ }
1508
1969
  interface ManifestStateMachineTransitionSpec {
1509
1970
  name: string;
1510
1971
  from: string;
1511
1972
  to: string;
1973
+ label?: string;
1974
+ description?: string;
1975
+ action?: ManifestStateTransitionActionSpec;
1976
+ assignee?: ManifestStateTransitionAssigneeSpec;
1977
+ requirements?: ManifestStateTransitionRequirementsSpec;
1978
+ permission?: ManifestStateTransitionPermissionSpec | string;
1979
+ risk?: "low" | "medium" | "high";
1980
+ expectedOutcome?: ManifestStateTransitionExpectedOutcomeSpec | string;
1512
1981
  }
1513
1982
  interface ManifestStateMachineSpec {
1514
1983
  name: string;
1984
+ stateField?: string;
1515
1985
  entryState: string;
1516
1986
  states: Array<string | ManifestStateMachineStateSpec>;
1517
1987
  transitions: ManifestStateMachineTransitionSpec[];
@@ -1534,15 +2004,23 @@ interface ManifestApprovalRequiredSpec {
1534
2004
  reason?: string;
1535
2005
  mode?: string;
1536
2006
  }
2007
+ type ManifestCreatesSpec = string | {
2008
+ className: string;
2009
+ idPath?: string;
2010
+ pathPath?: string;
2011
+ statePath?: string;
2012
+ classStateHandle?: boolean;
2013
+ };
1537
2014
  interface ManifestEffectMetamodelSpec {
1538
2015
  postCondition?: string | ManifestPostConditionSpec;
1539
2016
  dryRun?: boolean | ManifestDryRunSpec;
1540
2017
  reverse?: string | ManifestReverseSpec;
1541
2018
  approvalRequired?: boolean | ManifestApprovalRequiredSpec;
2019
+ creates?: ManifestCreatesSpec;
1542
2020
  /**
1543
2021
  * Declarative effect category used by orchestration/validation.
1544
2022
  *
1545
- * `read` means the callable observes or explains current state without
2023
+ * `read` means the effect observes or explains current state without
1546
2024
  * changing product state. `write` means it can mutate product state or call an
1547
2025
  * external side-effect. `ui` is reserved for frontend-only UI effects.
1548
2026
  */
@@ -1710,13 +2188,23 @@ interface OpenAIModelPricing {
1710
2188
  currency: "USD";
1711
2189
  inputUsdPerMillion: number;
1712
2190
  cachedInputUsdPerMillion: number;
2191
+ cacheWriteUsdPerMillion?: number | null;
1713
2192
  outputUsdPerMillion: number;
2193
+ contextTier?: "short" | "long";
2194
+ longContextThresholdTokens?: number | null;
2195
+ longContextPricing?: {
2196
+ inputUsdPerMillion: number;
2197
+ cachedInputUsdPerMillion: number;
2198
+ cacheWriteUsdPerMillion?: number | null;
2199
+ outputUsdPerMillion: number;
2200
+ };
1714
2201
  sourceUrl: string;
1715
2202
  effectiveDate: string;
1716
2203
  }
1717
2204
  interface NormalizedOpenAIUsage {
1718
2205
  inputTokens: number;
1719
2206
  cachedInputTokens: number;
2207
+ cacheWriteTokens: number;
1720
2208
  uncachedInputTokens: number;
1721
2209
  outputTokens: number;
1722
2210
  reasoningTokens: number;
@@ -1727,6 +2215,7 @@ interface OpenAITokenSpend {
1727
2215
  model: string;
1728
2216
  inputTokens: number;
1729
2217
  cachedInputTokens: number;
2218
+ cacheWriteTokens: number;
1730
2219
  uncachedInputTokens: number;
1731
2220
  outputTokens: number;
1732
2221
  reasoningTokens: number;
@@ -1735,13 +2224,17 @@ interface OpenAITokenSpend {
1735
2224
  currency: "USD";
1736
2225
  inputPricePerMillionMicros: number;
1737
2226
  cachedInputPricePerMillionMicros: number;
2227
+ cacheWritePricePerMillionMicros: number | null;
2228
+ cacheWriteCostMicros: number;
1738
2229
  outputPricePerMillionMicros: number;
2230
+ pricingContextTier: "short" | "long";
2231
+ longContextThresholdTokens: number | null;
1739
2232
  pricingSource: string;
1740
2233
  pricingEffectiveAt: string;
1741
2234
  usage: NormalizedOpenAIUsage;
1742
2235
  }
1743
2236
  declare const OPENAI_MODEL_PRICING_USD_PER_MILLION: Record<string, OpenAIModelPricing>;
1744
- declare function getOpenAIModelPricing(model: string): OpenAIModelPricing | null;
2237
+ declare function getOpenAIModelPricing(model: string, inputTokens?: number): OpenAIModelPricing | null;
1745
2238
  declare function normalizeOpenAIUsage(rawUsage: unknown): NormalizedOpenAIUsage;
1746
2239
  declare function calculateOpenAITokenSpend(model: string, rawUsage: unknown): OpenAITokenSpend | null;
1747
2240
 
@@ -1779,4 +2272,4 @@ declare function toGranularHttpBase(apiUrl: string): string;
1779
2272
  declare function buildOpenAISpendEventId(usage: Pick<OpenAIUsageSpendEvent, "requestId">, context?: GranularSpendContext): string | undefined;
1780
2273
  declare function recordOpenAIUsageSpend(options: RecordOpenAIUsageSpendOptions): Promise<RecordOpenAIUsageSpendResult>;
1781
2274
 
1782
- export { type ConversationSessionInfo as $, type PolicyEvaluationContext as A, type PermissionProfileFile as B, type ConditionIR as C, type DomainState as D, type EndpointMode as E, type PermissionPolicySpec as F, type GranularSpendContext as G, type PermissionActionSpec as H, type InstanceToolHandler as I, type ConditionalPolicySpec as J, type AccessTokenProvider as K, type LimitPolicySpec as L, type ManifestEffectMetamodelSpec as M, type NormalizedOpenAIUsage as N, type OpenAIModelPricing as O, type Prompt as P, type GranularOptions as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type GranularAuth as U, type User as V, type RecordUserOptions as W, type Subject as X, type OpenEnvironmentOptions as Y, type ConnectOptions as Z, type CreateSessionOptions as _, type EffectHandlerContext as a, type SessionFileStatus as a$, type SpendLineItemType as a0, type QuotaScopeType as a1, type QuotaPeriod as a2, type QuotaStatus as a3, type SpendSummary as a4, type QuotaLineItemFilter as a5, type GranularQuotaPolicy as a6, type GranularQuotaProgress as a7, type Sandbox as a8, type CreateSandboxData as a9, type EffectInvocationMetadata as aA, type EffectSchema as aB, type EffectWithHandler as aC, type PublishEffectsResult as aD, type EffectVersionSelector as aE, type ToolInfo as aF, type EffectInfo as aG, type ToolsChangedEvent as aH, type EffectsChangedEvent as aI, type EffectHandler as aJ, type InstanceEffectHandler as aK, type JobStatus as aL, type JobFeedbackSentiment as aM, type JobFeedbackToolCall as aN, type JobFeedbackMetadata as aO, type JobFeedbackInput as aP, type JobFeedbackRecord as aQ, type EnvironmentFeedbackRecord as aR, type JobSubmitResult as aS, type Job as aT, type ConversationMessageShowRefs as aU, type ConversationMessageInput as aV, type ConversationAppendResult as aW, type SessionConversationMessage as aX, type SessionTimelineEvent as aY, type SessionFileSource as aZ, type SessionFileKind as a_, type SandboxListResponse as aa, type PermissionRules as ab, type PermissionProfile as ac, type CreatePermissionProfileData as ad, type PermissionProfileListResponse as ae, type Assignment as af, type AssignmentListResponse as ag, type BuildPolicy as ah, type VersionTracking as ai, type VersionTag as aj, type EnvironmentData as ak, type CreateEnvironmentData as al, type EnvironmentListResponse as am, type Manifest as an, type ManifestListResponse as ao, type BuildStatus as ap, type Build as aq, type Version as ar, type BuildListResponse as as, type SemanticVersionDiffEntry as at, type SemanticVersionDiff as au, type ResolvedEffectPostCondition as av, type ResolvedEffectDryRun as aw, type ResolvedEffectReverse as ax, type ResolvedEffectApprovalRequired as ay, type EffectInvocationMode as az, type SessionHeapList as b, type ManifestEffectDeclaration as b$, type SessionFileRecord as b0, type SessionFileUploadOptions as b1, type SessionJobRecord as b2, type SessionHeapFieldType as b3, type SessionHeapFieldValue as b4, type SessionHeapVariable as b5, type RecordSearchResult as b6, type RecordSearchOptions as b7, type RecordMentionInput as b8, type SessionDocumentResult as b9, type RecordImportOptions as bA, type RecordImportStatus as bB, type RecordImportItemStatus as bC, type RecordImportStats as bD, type RecordImportItem as bE, type RecordImport as bF, type EnvironmentRecordImportSummary as bG, type EnvironmentSetupTriggerReason as bH, type RunEnvironmentImporterOptions as bI, type EnvironmentSetupLifecycleStatus as bJ, type EnvironmentSetupSummary as bK, type EnvironmentImporterImportOptions as bL, type EnvironmentImporter as bM, type ManifestPropertySpec as bN, type ManifestValidationOperator as bO, type ManifestEnumRuleSpec as bP, type ManifestFilterBySpec as bQ, type ManifestValidationRuleSpec as bR, type ManifestStateMachineStateSpec as bS, type ManifestStateMachineTransitionSpec as bT, type ManifestStateMachineSpec as bU, type ManifestPostConditionSpec as bV, type ManifestDryRunSpec as bW, type ManifestReverseSpec as bX, type ManifestApprovalRequiredSpec as bY, type ManifestRelationshipDef as bZ, type ManifestEffectSchema as b_, type SessionCollectionListOptions as ba, type SessionJobListOptions as bb, type SessionCollectionListResult as bc, type UserEnvironmentPrompt as bd, type UserEnvironmentMessagePreview as be, type UserEnvironmentSessionState as bf, type UserEnvironmentState as bg, type UserEnvironmentStateOptions as bh, type MarkUserEnvironmentReadOptions as bi, type WSDisconnectInfo as bj, type WSReconnectErrorInfo as bk, type WSClientOptions as bl, type RPCRequest as bm, type RPCResponse as bn, type SyncMessage as bo, type RPCRequestFromServer as bp, type ToolInvokeParams as bq, type ToolResultParams as br, type ModelRef as bs, type RelationshipInfo as bt, type DefineRelationshipOptions as bu, type RecordObjectOptions as bv, type RecordObjectResult as bw, type RecordObjectsChunkInfo as bx, type RecordObjectsOptions as by, type RecordImportWriteMode as bz, type SessionHeapSnapshot as c, type ManifestEventTypeDef as c0, type ManifestEventStreamDef as c1, type ManifestOperation as c2, type ManifestImport as c3, type ManifestVolume as c4, type ManifestContent as c5, type GraphQLResult as c6, type APIError as c7, type DeleteResponse as c8, type StreamEvent as c9, type StreamSubscription as ca, type StreamStats as cb, type SessionTranscriptEntry as d, type ToolSchema as e, type PublishToolsResult as f, type ToolHandler as g, type OpenAITokenSpend as h, OPENAI_MODEL_PRICING_USD_PER_MILLION as i, getOpenAIModelPricing as j, calculateOpenAITokenSpend as k, type OpenAIUsageSpendEvent as l, type RecordOpenAIUsageSpendOptions as m, normalizeOpenAIUsage as n, type RecordOpenAIUsageSpendResult as o, buildOpenAISpendEventId as p, type PolicyOutcome as q, recordOpenAIUsageSpend as r, type PolicySource as s, toGranularHttpBase as t, type PolicyPredicateSource as u, type PolicyOperator as v, type PolicyOrigin as w, type PolicyRuleIR as x, type MatchedPolicy as y, type PolicyDecision as z };
2275
+ export { type QuotaLineItemFilter as $, type AccessTokenProvider as A, type RecordUserOptions as B, type ConditionIR as C, type DomainState as D, type EndpointMode as E, type Subject as F, type GranularSpendContext as G, type OpenEnvironmentOptions as H, type InstanceToolHandler as I, type ConnectOptions as J, type CreateSessionOptions as K, type ConversationSessionInfo as L, type ManifestEffectMetamodelSpec as M, type NormalizedOpenAIUsage as N, type OpenAIModelPricing as O, type Prompt as P, type ConversationSessionListStatus as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type ConversationSessionListOptions as V, type SpendLineItemType as W, type QuotaScopeType as X, type QuotaPeriod as Y, type QuotaStatus as Z, type SpendSummary as _, type EffectHandlerContext as a, type SessionFileSource as a$, type GranularQuotaPolicy as a0, type GranularQuotaProgress as a1, type Sandbox as a2, type CreateSandboxData as a3, type SandboxListResponse as a4, type PermissionRules as a5, type PermissionProfile as a6, type CreatePermissionProfileData as a7, type PermissionProfileListResponse as a8, type Assignment as a9, type EffectInfo as aA, type ToolsChangedEvent as aB, type EffectsChangedEvent as aC, type EffectHandler as aD, type InstanceEffectHandler as aE, type JobStatus as aF, type JobFeedbackSentiment as aG, type JobFeedbackToolCall as aH, type JobFeedbackMetadata as aI, type JobFeedbackInput as aJ, type JobFeedbackRecord as aK, type EnvironmentFeedbackRecord as aL, type JobSubmitResult as aM, type Job as aN, type ConversationMessageShowRefs as aO, type ConversationTableCell as aP, type ConversationTableColumn as aQ, type ConversationTableRowReference as aR, type ConversationTableRow as aS, type ConversationTableProjection as aT, type ConversationActionSuggestion as aU, type ConversationMessageAction as aV, type ConversationMessagePart as aW, type ConversationMessageInput as aX, type ConversationAppendResult as aY, type SessionConversationMessage as aZ, type SessionTimelineEvent as a_, type AssignmentListResponse as aa, type BuildPolicy as ab, type VersionTracking as ac, type VersionTag as ad, type EnvironmentData as ae, type CreateEnvironmentData as af, type EnvironmentListResponse as ag, type Manifest as ah, type ManifestListResponse as ai, type BuildStatus as aj, type Build as ak, type Version as al, type BuildListResponse as am, type SemanticVersionDiffEntry as an, type SemanticVersionDiff as ao, type ResolvedEffectPostCondition as ap, type ResolvedEffectDryRun as aq, type ResolvedEffectReverse as ar, type ResolvedEffectApprovalRequired as as, type EffectInvocationMode as at, type EffectInvocationMetadata as au, type EffectSchema as av, type EffectWithHandler as aw, type PublishEffectsResult as ax, type EffectVersionSelector as ay, type ToolInfo as az, type SessionHeapList as b, type EnvironmentStateProxy as b$, type SessionFileKind as b0, type SessionFileStatus as b1, type SessionFileRecord as b2, type SessionArtifactStatus as b3, type SessionArtifactKind as b4, type SessionArtifactAutonomyPolicy as b5, type SessionArtifactRecord as b6, type SessionArtifactListOptions as b7, type SessionArtifactValidationResult as b8, type SessionArtifactExecutionResult as b9, type SessionCollectionListOptions as bA, type SessionJobListOptions as bB, type SessionCollectionListResult as bC, type UserEnvironmentPrompt as bD, type UserEnvironmentMessagePreview as bE, type UserEnvironmentSessionState as bF, type UserEnvironmentState as bG, type UserEnvironmentStateOptions as bH, type MarkUserEnvironmentReadOptions as bI, type WSDisconnectInfo as bJ, type WSReconnectErrorInfo as bK, type WSClientOptions as bL, type RPCRequest as bM, type RPCResponse as bN, type SyncMessage as bO, type RPCRequestFromServer as bP, type ToolInvokeParams as bQ, type ToolResultParams as bR, type ModelRef as bS, type RelationshipInfo as bT, type DefineRelationshipOptions as bU, type RecordObjectOptions as bV, type RecordObjectStateValue as bW, type EnvironmentStateTarget as bX, type EnvironmentStateObservationInput as bY, type EnvironmentStateUpdateInput as bZ, type EnvironmentStateMachineProxy as b_, type SessionArtifactExecutionOptions as ba, type SessionArtifactApprovalOptions as bb, type ArtifactApprovalTaskStatus as bc, type ArtifactApprovalTask as bd, type ArtifactApprovalTaskListOptions as be, type ArtifactApprovalDecisionInput as bf, type ArtifactApprovalDecisionResult as bg, type ManualActionStatus as bh, type ManualActionSource as bi, type ManualActionTarget as bj, type ManualActionRelatedRecord as bk, type RecordManualActionInput as bl, type ManualActionOccurrence as bm, type ManualActionRecordResult as bn, type ManualActionListOptions as bo, type ManualActionSuggestion as bp, type ManualActionSuggestionOptions as bq, type SessionFileUploadOptions as br, type SessionJobRecord as bs, type SessionHeapFieldType as bt, type SessionHeapFieldValue as bu, type SessionHeapVariable as bv, type RecordSearchResult as bw, type RecordSearchOptions as bx, type RecordMentionInput as by, type SessionDocumentResult as bz, type SessionHeapSnapshot as c, type RecordObjectResult as c0, type RecordObjectsChunkInfo as c1, type RecordObjectsOptions as c2, type RecordImportWriteMode as c3, type RecordImportOptions as c4, type RecordImportStatus as c5, type RecordImportItemStatus as c6, type RecordImportStats as c7, type RecordImportItem as c8, type RecordImport as c9, type ManifestCreatesSpec as cA, type ManifestRelationshipDef as cB, type ManifestEffectSchema as cC, type ManifestEffectDeclaration as cD, type ManifestEventTypeDef as cE, type ManifestEventStreamDef as cF, type ManifestOperation as cG, type ManifestImport as cH, type ManifestVolume as cI, type ManifestContent as cJ, type GraphQLResult as cK, type APIError as cL, type DeleteResponse as cM, type StreamEvent as cN, type StreamSubscription as cO, type StreamStats as cP, type EnvironmentRecordImportSummary as ca, type EnvironmentSetupTriggerReason as cb, type RunEnvironmentImporterOptions as cc, type EnvironmentSetupLifecycleStatus as cd, type EnvironmentSetupSummary as ce, type EnvironmentImporterImportOptions as cf, type EnvironmentImporter as cg, type ManifestPropertySpec as ch, type ManifestValidationOperator as ci, type ManifestEnumRuleSpec as cj, type ManifestFilterBySpec as ck, type ManifestValidationRuleSpec as cl, type ManifestStateMachineStateSpec as cm, type ManifestStateTransitionInputBinding as cn, type ManifestStateTransitionActionSpec as co, type ManifestStateTransitionAssigneeSpec as cp, type ManifestStateTransitionRelatedStateRequirementSpec as cq, type ManifestStateTransitionRequirementsSpec as cr, type ManifestStateTransitionPermissionSpec as cs, type ManifestStateTransitionExpectedOutcomeSpec as ct, type ManifestStateMachineTransitionSpec as cu, type ManifestStateMachineSpec as cv, type ManifestPostConditionSpec as cw, type ManifestDryRunSpec as cx, type ManifestReverseSpec as cy, type ManifestApprovalRequiredSpec as cz, type SessionTranscriptEntry as d, type ToolSchema as e, type PublishToolsResult as f, type ToolHandler as g, type OpenAITokenSpend as h, OPENAI_MODEL_PRICING_USD_PER_MILLION as i, getOpenAIModelPricing as j, calculateOpenAITokenSpend as k, type OpenAIUsageSpendEvent as l, type RecordOpenAIUsageSpendOptions as m, normalizeOpenAIUsage as n, type RecordOpenAIUsageSpendResult as o, buildOpenAISpendEventId as p, type PolicySource as q, recordOpenAIUsageSpend as r, type PolicyPredicateSource as s, toGranularHttpBase as t, type PolicyOperator as u, type PolicyOrigin as v, type PolicyRuleIR as w, type MatchedPolicy as x, type GranularOptions as y, type GranularAuth as z };